The relaxation dispersion auto-analysis

In relax, optimisation can either be performed manually or one of the auto-analyses can be employed. Note that if you are using the relax GUI, you will be using the dispersion auto-analysis. The auto-analysis is a fully self-contained protocol designed to make the analysis as simple as possible. All details can be seen in the auto_analyses/relax_disp.py file which, in reality, is simply a large relax script.

The relaxation dispersion auto-analysis implements many of the concepts described in detail in the next sections. It can be summarised as:

Peak intensity error analysis:

An error analysis is performed to determine the peak intensity errors, if not already calculated (see Section 17.2.213 on page

`R2eff' model optimisation:

Firstly the `R2eff' model is either optimised (using the minimise.execute user function) or simply calculated (using the minimise.calculate user function) to find the R_2eff or R_1ρ values used as the base data for all other dispersion models (see Section 11.2.1 on page

Dispersion curve insignificance:

Spins with insignificant dispersion profiles will be deselected with the relax_disp.insignificance user function, as described below, excluding the `No Rex' model.

Model optimisation:

Sequential optimisation of each of the specified dispersion models. This consists of a grid search followed by Nelder-Mead simplex optimisation constrained using the log-barrier constraint algorithm. Each model will be stored in a different data pipe. See Section 17.2.70 on page

for the grid search and Section 17.2.69 on page

for minimisation.

Grid search avoidance:

A number of tricks are used to speed up optimisation by skipping or decreasing the size of the initial grid search:

Pre-run directory:: If a pre-run directory is supplied - a separate 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 used in a clustered analysis whereby the pre-run directory contains results from a non-clustered analysis. 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 R₂⁰ values for each spin and magnetic field, as well as the parameters related to the chemical shift difference Δω, the optimised values of the previous run will be directly copied.
Model nesting:: If two models are nested, then the parameters of the simpler will be used as the starting point for optimisation of the more complex. The currently supported nested model sets are presented in Table 11.3 on page . The models are optimised in the order presented in that table. In some cases, the R_2A⁰ and R_2B⁰ parameter values are set to the simpler model R₂⁰ value and the grid search is bypassed.
Model equivalence:: When two models are equivalent, the optimised parameters of one model can be used as the starting point of the other rather than performing a grid search. This is used in the auto-analysis for avoiding the grid search in the numeric models. The optimised `CR72' model is used for the `NS CPMG 2-site expanded', `NS CPMG 2-site 3D', and `NS CPMG 2-site star' models. The optimised `MMQ CR72' model is used for the `NS MMQ 2-site' model. And the `MP05' model is used for the `NS R1rho 2-site' model.

Interruption:

The optimisation procedure of the auto-analysis can read saved results files if a previous calculation was interrupted.

Model elimination:

As it is quite common that some of the dispersion models fail to optimise to reasonable values, or will even optimise to non-physically possible values where the global minimum is located, model elimination is performed to remove these models. The relax implementation is described in d'Auvergne and Gooley (2006). This needs to be performed prior to model selection as a failed model will often provide a statistically better fit than a non-failed model.

Per-model error analysis:

If desired, Monte Carlo simulations for error propagation can be performed for each model. This does however require far greater computation time.

Model selection:

If more than one model is analysed, AIC model selection will be performed to judge statistical significance of the models (Akaike, 1973). This is used to determine if statistically significant R_ex contributions can be extracted form the data, as well as determine if one model is better than the other. Different statistical techniques such as AICc and BIC can be used when using the script UI (Hurvich and Tsai, 1989; Schwarz, 1978). The AIC, AICc and BIC equations for NMR relaxation data were derived in d'Auvergne and Gooley (2003). In most cases, the list models to choose from should be severely limited. The results will be stored in a new `final' data pipe and output files placed in the final directory.

Error analysis:

Monte Carlo simulations for error propagation is performed on the final data pipe (see Section 17.2.96 on page

as well as the descriptions for all of the other monte_carlo user functions). Model elimination is performed again to remove the Monte Carlo simulations which have failed.

Output file creation:

For each of the models and the final model selection results, the relax_disp.plot_disp_curves (Section 17.2.170 on page

), relax_disp.plot_exp_curves (Section 17.2.171 on page

), relax_disp.write_disp_curves (Section 17.2.182 on page

), grace.write (Section 17.2.56 on page

) and value.write (Section 17.2.269 on page

) user functions will be called to generate all the output files you would need. These generate both Grace 2D plots of the data as well as plain text files. Additional output files can be created after the analysis by using the user functions manually.

All these steps will be shown in full detail in the relax logs. You should check very carefully for any relax warnings as these can be an indication that something has not been set up correctly.

If you are a power user, you are free to use all of the relax user functions, the relax library, and the relax data store to implement your own protocol. If you wish, the protocol can be converted into a new auto-analysis and distributed as part of relax. The relax test suite will ensure the protocol remains functional for the lifetime of relax.

**Table 11.3:** Model nesting for the relaxation dispersion auto-analysis.

Model	Nested models^11.1


Base models
R_2eff/R_1ρ'	-
No Rex	-

Single quantum (SQ) CPMG-type
LM63	-
LM63 3-site	LM63
CR72	NS CPMG 2-site expanded, NS CPMG 2-site 3D, NS CPMG 2-site star, B14
CR72 full	NS CPMG 2-site 3D full, NS CPMG 2-site star full, B14 full, NS CPMG 2-site expanded,
	NS CPMG 2-site 3D, NS CPMG 2-site star, B14, CR72
IT99	-
TSMFK01	-
B14	NS CPMG 2-site expanded, NS CPMG 2-site 3D, NS CPMG 2-site star, CR72
B14 full	NS CPMG 2-site 3D full, NS CPMG 2-site star full, CR72 full, NS CPMG 2-site expanded,
	NS CPMG 2-site 3D, NS CPMG 2-site star, B14, CR72
NS CPMG 2-site expanded	NS CPMG 2-site 3D, NS CPMG 2-site star, B14, CR72
NS CPMG 2-site 3D	NS CPMG 2-site expanded, NS CPMG 2-site star, B14, CR72
NS CPMG 2-site 3D full	NS CPMG 2-site star full, B14 full, CR72 full, NS CPMG 2-site expanded, NS CPMG 2-site 3D,
	NS CPMG 2-site star, B14, CR72
NS CPMG 2-site star	NS CPMG 2-site expanded, NS CPMG 2-site 3D, B14, CR722
NS CPMG 2-site star full	NS CPMG 2-site 3D full, B14 full, CR72 full, NS CPMG 2-site expanded, NS CPMG 2-site 3D,
	NS CPMG 2-site star, B14, CR72

MMQ (SQ, ZQ, DQ, & MQ) CPMG-type
MMQ CR72	NS MMQ 2-site
NS MMQ 2-site	MMQ CR72
NS MMQ 3-site linear	NS MMQ 3-site, NS MMQ 2-site, MMQ CR72
NS MMQ 3-site	NS MMQ 3-site linear, NS MMQ 2-site, MMQ CR72

R_1ρ-type
M61	-
M61 skew	-
DPL94	-
DPL94 R₁ fit	-
TP02	MP05, TAP03
TP02 R₁ fit	MP05 R₁ fit, TAP03 R₁ fit
TAP03	MP05, TP02
TAP03 R₁ fit	MP05 R₁ fit, TP02 R₁ fit
MP05	TAP03, TP02
MP05 R₁ fit	TAP03 R₁ fit, TP02 R₁ fit
NS R_1ρ 2-site	MP05, TAP03, TP02
NS R_1ρ 2-site R₁ fit	MP05 R₁ fit, TAP03 R₁ fit, TP02 R₁ fit
NS R_1ρ 3-site linear	NS R_1ρ 2-site, MP05, TAP03, TP02
NS R_1ρ 3-site	NS R_1ρ 3-site linear, NS R_1ρ 2-site, MP05, TAP03, TP02

The relax user manual (PDF), created 2024-06-08.