Last update: 3/30/08
NOTE: The goal of this document is to explain internal principle and details of LineShapeKin operation so you could better understand and use the package, as well as modify if necessary. The development of the package is continuing so this document may become outdated.
(Every module has its own header with description of its features, please, read).
Modules specific to the experiment and the model reside in user folder with the data user1/ are shown in green. Statistical testing module for comparing different models resides in any folder user2/ .Shown in white the modules you call from MATLAB command line.
module  brief description 
Useredited modules  
user1/setup.m  Modeldependent This is where all experimental parameters are set up and operation mode is chosen Called by main.m 
user2/AIC_setup_ 2models.m 
Setup module for statistical testing of the likelihood to be correct for models with different number of parameters. Called by compare_2models.m 
user1/AIC_setup.m  Setup module for testing of global vs individual fitting results. Here you insert the dataset name you like to test. Called by compare.m 
user1/model_setup.m  Modeldependent Here starting values of the adjustable parameter of the model are set. Part of the header below:
Called by setup.m 
Data fitting modules


code/ main.m  Reads setup.m and model_setup.m located in a user working folder. Selects an operation mode (single, individual, global, simulation), forms a residue list. Calls fit_all_data and passes resnames (array of dataset names), starting Kds, Koffs and scale_factor. Receives back optimized parameters, their errors and a norm (average sum of squares). Calls display_fit_results to plot results for individual residue. Started from MATLAB command line. 
code/fit_all_data.m  Here the main arrays for fitting Xfull and Yfull is constructed. Calls prepare_residue_data and passes it residue name and plot_mode=YES to plot the data. Receives back res_data structure and concatenates the res_data.Xcomposite and res_data.Ytotal data together if more than one residue was in the resnames list. Runs fit_run first with an array of koffs and setting estimate_error to NO. Receives back optimized parameters corresponding to a minimum norm value and the reruns fit_run with this minimum koff as starting parameter and estimate_error=YES Called by main.m 
code/fit_run.m  if modes.gird_search=YES  does data fitting to model at each grid point array set by B_vector (model_setup.m). if estimate_error=YES  runs error analysis for fitting parameters (takes as much time as actual fitting!) Reports (saves) results and returns minimum norm fitting parameters. Called by fit_all_data.m 
Modeldefining modules


code/ model.m  Calculates the spectrum intensity over entire frequency range of experimental dataset at every frequency point. Calls rate_matrix to generate the rate matrix for specific ligand concentration. Calls spectrum to produce spectral intensity at every point. Called by least squares routine in fit_run.m 
code/spectrum.m  Calculates matrix equation for total magnetization at a specific frequency point using provided Kmatrix. Independent of the model definition. Called by model.m 
user/ rate_matrix.m  Modeldependent Edit this file to introduce new mathematical model of the exchange This is where mathematical model for the experimental system resides. Here rate matrix is calculated for every particular conditions (P and L concentrations and koff). Called by model.m 
code/classic_lorentzian.m  Simple analytical lorentzian line shape for estimates of the peak positions and relaxation rates of the end points of titration. Called by prepare_residue_data.m 
Data import, export and display modules


code/load_raw_ 
Loading spectral data for a residue Called by prepare_residue_data.m 
code/prepare_ residue_data.m 
This module calls load_residue_data to read the spectral data for the residue All 1D slices get normalized and data plotted for quality control. R2 and resonance position of the first and last peaks are obtained by lorentzian fitting. res_data.Xcomposite and res_data.Ytotal arrays are generated Called by main.m and fit_all_data.m 
code/display_ fit_results.m 
Plot results of fitting or simulation. Calles model.m Called by main.m 
Statistical analysis of the data  
code/AICc.m  function for calculation of the second order corrected Akaike's information criterion 
code/ compare.m  reads AIC_setup.m in the user working folder Performs testing of two alternative fitting sessions, global and individual ('indiv' or 'single' modes) fitting by Akaike's criterion. Calculates likelihood of correctness of the models and evidence ratio. Started from MATLAB command line 
code/ compare_2models.m  reads user2/AIC_setup_2models.m Tests relative likelihood to be correct of the models with different number of fitting parameters. 
Direct Parameter Mapping modules integrated with LineShapeKin  
user1/DPM_setup.m  This module accompanies the setup.m, model_setup.m and rate_matrix.m files of the threeparameter model fitting Kd, Koff and w0(B). All the values are set here for DPM analysis. Called by setup.m and main.m 
DPM_code/DPM_run.m  Main control module of DPM package. Called by main.m 
DPM_code/ 
The module that performs computation of SSD matrix over a threedimensional grid. Very timeconsuming operation. Needs to be run only once on a particular dataset and 'bestfit' parameters. called by DPM_run.m 
DPM_code/ matrix_analysis_v3.m 
This module performs analysis of SSD matrix produced by matrix_computation.m. Searches for equivalent parameter sets and plots the data. 
DPM_model.m  lowlevel 'adaptor' function for interfacing the fitting model (model.m) with the DPM module. 
DPM_code/ linear.m pwr10.m 
functions to allow nonlinear sampling of the parameter dimension. We use pwr10 to create logarithmic sampling of Kd and Koff space while third parameter is sampled linearly. Assigned in DPM_setup.m 
DPM_code/ R2_2st_alltmscl_multi_ field.m 
not used 
Raw_Data  The cell array of structures res_data containting all raw and normalized spectral data for each residue. 
res_data  Structure with raw and normalized spectral data generated by load_raw_residue_data.m and prepare_residue_data.m. Header:

presets  A structure containing what it finds in 'manual_R2.txt', Fields: Generated by load_residue_data.m 
Xcomposite  Composite array of experimental conditions. Each experimental variable takes column set in Xcolumns in model_setup.m. Each 1D slice X and Y columns are complemented columns containing total protein concentration Ptotal, ratio of ligand to protein, relaxation rates and the frequency positions of the end states. Lengths of each 1D slice data are recorded in res_data.lengths array. 1D slices of consecutive titration points are concatenated to make final res_data.Xcomposite array. Normalized spectral intensities Ynormalized are correspondingly concatenated to make res_data.Ytotal. Generated by prepare_residue_data.m. 
Xfull, Yfull  The arrays actually submitted for fitting to lsqcurvefit function. In case of global fitting they consist of concatenated arrays corresponding to residues in the group. Generated in fit_all_data.m 
modes  Allpurpose structure to carry flags for operation modes
modes.simulation_mode=YES/NO modes.stacked_plot=Stacked_Plot; % YES to display the titration series stacked rather than overlayed fit_all_data.m 
conditions  Structure of experimental conditions from setup.m set up in main.m conditions.Ptotal=Ptotal; 
X_columns  Global structure with positions of different experimental variables in Xcomposite and Xfull arrays. set up in model_setup.m 
Model  Global structure containing starting values and min/max limits for the adjustable parameters of the model (to fit). Set up in model_setup.m 
B_vector  Global structure  definition of fitting parameters vector for fit_all_data.m, fit_run.m, model.m and rate_matrix.m. Allows to change fitting parameters more easily with changes only needed in model.m and rate_matrix.m while other modules do not need to know which parameter means what. Defines starting values, min and max limits and the names of the parameters (for nice output). Defines positions of the model parameters in beta vector. Assignes gridsearch parameter and its starting values. Set up in model_setup.m 
beta  Local vector of adjustable parameters of the fitting model. Used everywhere. Positions of specific parameters are set by B_vector (model_setup.m) 