Class Relax_disp

The relaxation dispersion auto-analysis.

Instance Methods

__init__(self, pipe_name=None, pipe_bundle=None, results_dir=None, models=['R2eff'], grid_inc=11, mc_sim_num=500, exp_mc_sim_num=None, modsel='AIC', pre_run_dir=None, optimise_r2eff=False, insignificance=0.0, numeric_only=False, mc_sim_all_models=False, eliminate=True, set_grid_r20=False, r1_fit=False)
Perform a full relaxation dispersion analysis for the given list of models.

bool is_model_for_selection(self, model=None)
Determine if the model should be used for model selection.

check_vars(self)
Check that the user has set the variables correctly.

check_numpy_less_1_8_and_numerical_model(self)
Check for numerical model using numpy version under 1.8.

error_analysis(self)
Perform an error analysis of the peak intensities for each field strength separately.

name_pipe(self, prefix)
Generate a unique name for the data pipe.

bool nesting(self, model=None)
Support for model nesting.

optimise(self, model=None, model_path=None)
Optimise the model, taking model nesting into account.

pre_run_parameters(self, model=None, model_path=None)
Copy parameters from an earlier analysis.

run(self)
Execute the auto-analysis.

write_results(self, path=None, model=None)
Create a set of results, text and Grace files for the current data pipe.

write_results_test(self, path=None, model=None, models_tested=None, param=None, file_name_ini=None)
Create a set of results, text and Grace files for the current data pipe.

Class Variables

opt_func_tol = 1e-25

opt_max_iterations = 10000000

Method Details

__init__(self, pipe_name=None, pipe_bundle=None, results_dir=None, models=['R2eff'], grid_inc=11, mc_sim_num=500, exp_mc_sim_num=None, modsel='AIC', pre_run_dir=None, optimise_r2eff=False, insignificance=0.0, numeric_only=False, mc_sim_all_models=False, eliminate=True, set_grid_r20=False, r1_fit=False)
(Constructor)

Perform a full relaxation dispersion analysis for the given list of models.

Parameters:

• pipe_name (str) - The name of the data pipe containing all of the data for the analysis.
• pipe_bundle (str) - The data pipe bundle to associate all spawned data pipes with.
• results_dir (str) - The directory where results files are saved.
• models (list of str) - The list of relaxation dispersion models to optimise.
• grid_inc (int or None) - Number of grid search increments. If set to None, then the grid search will be turned off and the default parameter values will be used instead.
• mc_sim_num (int) - The number of Monte Carlo simulations to be used for error analysis at the end of the analysis.
• exp_mc_sim_num (int or None) - The number of Monte Carlo simulations for the error analysis in the 'R2eff' model when exponential curves are fitted. This defaults to the value of the mc_sim_num argument when not given. When set to '-1', the R2eff errors are estimated from the Covariance matrix. For the 2-point fixed-time calculation for the 'R2eff' model, this argument is ignored.
• modsel (str) - The model selection technique to use in the analysis to determine which model is the best for each spin cluster. This can currently be one of 'AIC', 'AICc', and 'BIC'.
• pre_run_dir (None or str) - The optional directory containing the dispersion auto-analysis results from a previous run. The optimised parameters from these previous results will be used as the starting point for optimisation rather than performing a grid search. This is essential for when large spin clusters are specified, as a grid search becomes prohibitively expensive with clusters of three or more spins. At some point a RelaxError will occur because the grid search is impossibly large. For the cluster specific parameters, i.e. the populations of the states and the exchange parameters, an average value will be used as the starting point. For all other parameters, the R20 values for each spin and magnetic field, as well as the parameters related to the chemical shift difference dw, the optimised values of the previous run will be directly copied.
• optimise_r2eff (bool) - Flag to specify if the read previous R2eff results should be optimised. For R1rho models where the error of R2eff values are determined by Monte-Carlo simulations, it can be valuable to make an initial R2eff run with a high number of Monte-Carlo simulations. Any subsequent model analysis can then be based on these R2eff values, without optimising the R2eff values.
• insignificance (float) - The R2eff/R1rho value in rad/s by which to judge insignificance. If the maximum difference between two points on all dispersion curves for a spin is less than this value, that spin will be deselected. This does not affect the 'No Rex' model. Set this value to 0.0 to use all data. The value will be passed on to the relax_disp.insignificance user function.
• numeric_only (bool) - The class of models to use in the model selection. The default of False allows all dispersion models to be used in the analysis (no exchange, the analytic models and the numeric models). The value of True will activate a pure numeric solution - the analytic models will be optimised, as they are very useful for replacing the grid search for the numeric models, but the final model selection will not include them.
• mc_sim_all_models (bool) - A flag which if True will cause Monte Carlo simulations to be performed for each individual model. Otherwise Monte Carlo simulations will be reserved for the final model.
• eliminate (bool) - A flag which if True will enable the elimination of failed models and failed Monte Carlo simulations through the eliminate user function.
• set_grid_r20 (bool) - A flag which if True will set the grid R20 values from the minimum R2eff values through the r20_from_min_r2eff user function. This will speed up the grid search with a factor GRID_INC^(Nr_spec_freq). For a CPMG experiment with two fields and standard GRID_INC=21, the speed-up is a factor 441.
• r1_fit - A flag which if True will activate R1 parameter fitting via relax_disp.r1_fit for the models that support it. If False, then the relax_disp.r1_fit user function will not be called.

is_model_for_selection(self, model=None)

Determine if the model should be used for model selection.

Parameters:

• model (str) - The model to check.

Returns: bool

True if the model should be included in the model selection list, False if not.

check_numpy_less_1_8_and_numerical_model(self)

Check for numerical model using numpy version under 1.8. This will result in slow "for loop" calculation through data, making the analysis 5-6 times slower.

name_pipe(self, prefix)

Generate a unique name for the data pipe.

Parameters:

• prefix (str) - The prefix of the data pipe name.

nesting(self, model=None)

Support for model nesting.

If model nesting is detected, the optimised parameters from the simpler model will be used for the more complex model. The method will then signal if the nesting condition is met for the model, allowing the grid search to be skipped.

Parameters:

• model (str) - The model to be optimised.

Returns: bool

True if the model parameters is equivalent to the nested model, and all parameters are copied. False if none or some of the parameters have been translated from the nested model. Here the Grid search should still be performed.

optimise(self, model=None, model_path=None)

Optimise the model, taking model nesting into account.

Parameters:

• model (str) - The model to be optimised.
• model_path (str) - The folder name for the model, where possible spaces has been replaced with underscore.

pre_run_parameters(self, model=None, model_path=None)

Copy parameters from an earlier analysis.

Parameters:

• model (str) - The model to be optimised.
• model_path (str) - The folder name for the model, where possible spaces has been replaced with underscore.

write_results(self, path=None, model=None)

Create a set of results, text and Grace files for the current data pipe.

Parameters:

• path (str) - The directory to place the files into.

write_results_test(self, path=None, model=None, models_tested=None, param=None, file_name_ini=None)

Create a set of results, text and Grace files for the current data pipe.

Parameters:

• path (str) - The directory to place the files into.
• model (None or str) - The model tested.
• model_tested (None or list of str.) - List of models tested, if the pipe is final.
• param (None or list of str.) - The param to write out.
• file_name_ini (None or str.) - The initial part of the file name for the grace and text files.