Technical description of the package

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.

Contents

• Data structure
• Listing of the M-modules
• Notes on fitting procedure

Listing of the M-modules

(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
User-edited modules
user1/setup.m	Model-dependent 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	Model-dependent Here starting values of the adjustable parameter of the model are set. Part of the header below:   % X_columns is a structure that % specifies column positions of protein concentration, ligand/protein % ratio, relaxation rates, peak positions, temperature etc. % % B_vector % is a structure that specifies positions of variable for fitting such % as Koff, scale_factor, Kd, activation energy etc. % % Model_description % is a structure that contains additional information on the fitting % model 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 re-runs 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
Model-defining 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 K-matrix. Independent of the model definition. Called by model.m
user/ rate_matrix.m	Model-dependent 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_ residue_data.m	Loading spectral data for a residue Returns res_data - a structure with the data for this residue and presets (R2, w0, Scale Factor) 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 three-parameter 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/ matrix_computation.m	The module that performs computation of SSD matrix over a three-dimensional grid. Very time-consuming operation. Needs to be run only once on a particular dataset and 'best-fit' 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	low-level 'adaptor' function for interfacing the fitting model (model.m) with the DPM module.
DPM_code/ linear.m pwr10.m	functions to allow non-linear 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

Data structures

• Sparky extension exports the data to the disk into a residue-dimension folder
  • in a plain text format as X Y matrices for every titration point named with a point number you entered in the Setup window.

    ---

  • It creates points_list.txt that contains the list of all points exported. You may remove some of the points from fitting by deleting the names from this list.

    ---

  • It creates empty files manual_R2.txt and manual_w0.txt. If you wish to override automatic determination of frequencies and relaxation rates (determined from line widths) for the endpoints of titration - enter specific numbers in these files as frequencies in Hz, or R2s in /s units for A and B:
    manual_w0.txt:
    6345
    6355
    or manual_R2.txt
    56
    61

    ---

  • Intensities in experimental spectra are scaled with the number found in scale_factor.txt. By default it is set to 1. After you run fitting with Scale Factor determination you adjust the number here and then all different residues will have comparable intensities.

    ---

  
  Main data structures
  

• 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: % fields % % name - residue name % indices - array of indices of titration points corresponding % to ligand concentrations in main array % (we may have some titration points dropped and then using index % we can extract corresponding concentrations) % Xs - cell array of X arrays, each one is a column (sequential order as read from the data folder. % NOT the sequential titration order! That one is set by indices.) % Ys - cell array of Y arrays % % lengths - lengths of individual X arrays % % Ynormalized - cell array of arrays of normalizes intensity data % (in the order of reading off the disk) % Xcomposite - X array containing frequency as well as relaxation % rates, endpoint frequencies, concentrations etc % % Ytotal - Y array for all the slices
  presets	A structure containing what it finds in 'manual_R2.txt', % 'manual_w0.txt'  and 'scale_factor.txt' files Fields: % R2s - array of preset R2s or empty to enable estimates by % fitting % w0s - array of preset w0 or empty to enable estimates by fitting % scale_factor- a divider to compensate for incomplete peak % envelope 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	All-purpose structure to carry flags for operation modes main.m modes.normalization=Normalization; modes.baseline_correction=Baseline_Correction; modes.integration_mode=Integration_mode modes.plot_raw_data=YES/NO; modes.simulation_mode=YES/NO modes.stacked_plot=Stacked_Plot; %--- YES to display the titration series stacked rather than overlayed modes.percent_shift=Percent_Shift; %-- percentage of the peak height for shifting next trace up fit_all_data.m modes.estimate_error=NO/NO; modes.grid_search=YES/NO;
  conditions	Structure of experimental conditions from setup.m set up in main.m conditions.Ptotal=Ptotal; conditions.LPratio=LPratio; conditions.Temperature=T; conditions.LineWidth0=Line_Width_0; %-- list of editable titration points to use for specific residue conditions. titration_points_list_fname= 'points_list.txt'; %-- standard file names to control estimates for A and B states R2 and w0 conditions.manual_R2_fname='manual_R2.txt'; conditions.manual_w0_fname='manual_w0.txt'; conditions.scale_factor_fname='scale_factor.txt'; conditions.figures_path=figures_path;
  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 grid-search 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)

  
  

Notes on fitting procedure

• Scale factor is a multiplier that changes the absolute value of intensities in the entire titration series. This variable must be fit because it is very difficult to encompass full lorentzian peak envelope. You inevitably cut tails (especially in crowded regions) and reduce the area under the peak. However, we may just multiply entire dataset by a fixed number which is not dependent on Kd, Koff etc.
• In the 'single' fitting session you fit and determine this scale factor for every individual set of 1D slices. This factor will change after you do new 'slicing' of the peak in Sparky. By default, the raw data is scaled with a scale_factor=1 (saved in 'scale_factor.txt' by LineShapeKin Sparky extension.
• After successful fitting you should update this number in 'scale_factor.txt'. Then the raw data will be scaled with this factor prior to next fitting session and you should see scale factor =1 after fitting. If this is the case, you may fit globally (because different datasets will no longer need specific scaling factors - they will be equal to 1) or switch the model entirely to the one that does NOT involve scale factor fitting and fits for Kd instead, for example.
• After 'single' session the scale factor is updated in 'scale_factor.txt' in the raw data folder and will be read again if you repeat fitting. However, second fitting session should yield