Package auto_analyses :: Module relax_disp :: Class Relax_disp
[hide private]
[frames] | no frames]

Class Relax_disp

source code

The relaxation dispersion auto-analysis.

Instance Methods [hide private]
 
__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.
source code
bool
is_model_for_selection(self, model=None)
Determine if the model should be used for model selection.
source code
 
check_vars(self)
Check that the user has set the variables correctly.
source code
 
check_numpy_less_1_8_and_numerical_model(self)
Check for numerical model using numpy version under 1.8.
source code
 
error_analysis(self)
Perform an error analysis of the peak intensities for each field strength separately.
source code
 
name_pipe(self, prefix)
Generate a unique name for the data pipe.
source code
bool
nesting(self, model=None)
Support for model nesting.
source code
 
optimise(self, model=None, model_path=None)
Optimise the model, taking model nesting into account.
source code
 
pre_run_parameters(self, model=None, model_path=None)
Copy parameters from an earlier analysis.
source code
 
run(self)
Execute the auto-analysis.
source code
 
write_results(self, path=None, model=None)
Create a set of results, text and Grace files for the current data pipe.
source code
 
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.
source code
Class Variables [hide private]
  opt_func_tol = 1e-25
  opt_max_iterations = 10000000
Method Details [hide private]

__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)

source code 

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)

source code 

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)

source code 

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)

source code 

Generate a unique name for the data pipe.

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

nesting(self, model=None)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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.