Class Model_free_main

Class containing functions specific to model-free analysis.

Instance Methods

str or None _are_mf_params_set(self, spin)
Test if the model-free parameter values are set.

list of str _assemble_param_names(self, model_type, spin_id=None)
Function for assembling a list of all the model parameter names.

numpy array _assemble_param_vector(self, spin=None, spin_id=None, sim_index=None, model_type=None)
Assemble the model-free parameter vector (as numpy array).

numpy diagonal matrix _assemble_scaling_matrix(self, num_params, model_type=None, spin=None, spin_id=None, scaling=True)
Create and return the scaling matrix.

float back_calc_ri(self, spin_index=None, ri_id=None, ri_type=None, frq=None)
Back-calculation of relaxation data from the model-free parameter values.

_compare_objects(self, object_from, object_to, pipe_from, pipe_to)
Compare the contents of the two objects and raise RelaxErrors if they are not the same.

float _conv_factor_rex(self)
Calculate and return the Rex conversion factor.

_create_model(self, model=None, equation=None, params=None, spin_id=None)
Function for creating a custom model-free model.

_delete(self)
Delete all the model-free data.

str or None _determine_model_type(self)
Determine the global model type.

str, list _model_map(self, model)
Return the equation name and parameter list corresponding to the given model.

_model_setup(self, model=None, equation=None, params=None, spin_id=None)
Function for updating various data structures depending on the model selected.

_remove_tm(self, spin_id=None)
Remove local tm from the set of model-free parameters for the given spins.

_select_model(self, model=None, spin_id=None)
Function for the selection of a preset model-free model.

str _units_rex(self)
Return the units for the Rex parameter.

list of floats create_mc_data(self, data_id=None)
Create the Monte Carlo Ri data.

data_init(self, data_cont, sim=False)
Initialise the spin specific data structures.

list of str data_names(self, set='all', error_names=False, sim_names=False)
Return a list of all spin container specific model-free object names.

str data_type(self, param=None)
Return the type of data, as a string, that the parameter should be.

float default_value(self, param)
The default model-free parameter values.

deselect(self, model_info, sim_index=None)
Deselect models or simulations.

duplicate_data(self, pipe_from=None, pipe_to=None, model_info=None, global_stats=False, verbose=True)
Duplicate the data specific to a single model-free model.

bool eliminate(self, name, value, model_info, args, sim=None)
Model-free model elimination, parameter by parameter.

list of str get_param_names(self, model_info=None)
Return a vector of parameter names.

list of str get_param_values(self, model_info=None, sim_index=None)
Return a vector of parameter values.

bool is_spin_param(self, name)
Determine whether the given parameter is spin specific.

list of float map_bounds(self, param, spin_id=None)
Create bounds for the OpenDX mapping function.

str model_desc(self, model_info)
Return a description of the model.

int model_loop(self)
Generator method for looping over the models (global or local).

tuple of (int, int, float) model_statistics(self, model_info=None, spin_id=None, global_stats=None)
Return the k, n, and chi2 model statistics.

str model_type(self)
Return the type of the model, either being 'local' or 'global'.

int num_instances(self)
Function for returning the number of instances.

overfit_deselect(self)
Deselect spins which have insufficient data to support minimisation.

str or None return_data_desc(self, name)
Return a description of the spin specific object.

str return_data_name(self, param)
Return a unique identifying string for the model-free parameter.

set_error(self, model_info, index, error)
Set the parameter errors.

set_param_values(self, param=None, value=None, spin_id=None, force=True)
Set the model-free parameter values.

set_selected_sim(self, model_info, select_sim)
Set all simulation selection flags.

set_update(self, param, spin)
Function to update the other model-free parameters.

sim_init_values(self)
Initialise the Monte Carlo parameter values.

list of float or float sim_return_chi2(self, model_info, index=None)
Return the simulation chi-squared values.

list of float sim_return_param(self, model_info, index)
Return the array of simulation parameter values.

list of int sim_return_selected(self, model_info)
Return the array of selected simulation flags for the spin.

bool skip_function(self, model_info)
Skip certain data.

Class Variables

default_value_doc = ['Model-free default values', '\n _...

eliminate_doc = [['Local tm model elimination rule', '\n ...

return_data_name_doc = ['Model-free data type string matching ...

set_doc = ['Model-free set details', '\n Setting a para...

Method Details

_are_mf_params_set(self, spin)

Test if the model-free parameter values are set.

Parameters:

• spin (SpinContainer instance) - The spin container object.

Returns: str or None

The name of the first parameter in the parameter list in which the corresponding parameter value is None. If all parameters are set, then None is returned.

_assemble_param_names(self, model_type, spin_id=None)

Function for assembling a list of all the model parameter names.

Parameters:

• model_type (str) - The model-free model type. This must be one of 'mf', 'local_tm', 'diff', or 'all'.
• spin_id (str) - The spin identification string.

Returns: list of str

A list containing all the parameters of the model-free model.

_assemble_param_vector(self, spin=None, spin_id=None, sim_index=None, model_type=None)

Assemble the model-free parameter vector (as numpy array).

If the spin argument is supplied, then the spin_id argument will be ignored.

Parameters:

• spin (SpinContainer instance) - The spin data container.
• spin_id (str) - The spin identification string.
• sim_index (int) - The optional MC simulation index.
• model_type (str or None) - The optional model type, one of 'all', 'diff', 'mf', or 'local_tm'.

Returns: numpy array

An array of the parameter values of the model-free model.

_assemble_scaling_matrix(self, num_params, model_type=None, spin=None, spin_id=None, scaling=True)

Create and return the scaling matrix.

If the spin argument is supplied, then the spin_id argument will be ignored.

Parameters:

• num_params (int) - The number of parameters in the model.
• model_type (str) - The model type, one of 'all', 'diff', 'mf', or 'local_tm'.
• spin (SpinContainer instance) - The spin data container.
• spin_id (str) - The spin identification string.

Returns: numpy diagonal matrix

The diagonal and square scaling matrix.

back_calc_ri(self, spin_index=None, ri_id=None, ri_type=None, frq=None)

Back-calculation of relaxation data from the model-free parameter values.

Parameters:

• spin_index (int) - The global spin index.
• ri_id (str) - The relaxation data ID string.
• ri_type (str) - The relaxation data type.
• frq (float) - The field strength.

Returns: float

The back calculated relaxation data value corresponding to the index.

_compare_objects(self, object_from, object_to, pipe_from, pipe_to)

Compare the contents of the two objects and raise RelaxErrors if they are not the same.

Parameters:

• object_from (any object) - The first object.
• object_to (any object) - The second object.
• pipe_from (str) - The name of the data pipe containing the first object.
• pipe_to (str) - The name of the data pipe containing the second object.

_conv_factor_rex(self)

Calculate and return the Rex conversion factor.

Returns: float

The Rex conversion factor.

_create_model(self, model=None, equation=None, params=None, spin_id=None)

Function for creating a custom model-free model.

Parameters:

• model (str) - The name of the model.
• equation (str) - The equation type to use. The 3 allowed types are: 'mf_orig' for the original model-free equations with parameters {s2, te}; 'mf_ext' for the extended model-free equations with parameters {s2f, tf, s2, ts}; and 'mf_ext2' for the extended model-free equations with parameters {s2f, tf, s2s, ts}.
• params (list of str) - A list of the parameters to include in the model. The allowed parameter names includes those for the equation type as well as chemical exchange 'rex', the bond length 'r', and the chemical shift anisotropy 'csa'.
• spin_id (str) - The spin identification string.

_determine_model_type(self)

Determine the global model type.

Returns: str or None

The name of the model type, which will be one of 'all', 'diff', 'mf', or 'local_tm'. If all parameters are fixed (and no spins selected), None is returned.

_model_map(self, model)

Return the equation name and parameter list corresponding to the given model.

Parameters:

• model (str) - The model-free model.

Returns: str, list

The equation type (either 'mf_orig' or 'mf_ext') and the model-free parameter list corresponding to the model.

_model_setup(self, model=None, equation=None, params=None, spin_id=None)

Function for updating various data structures depending on the model selected.

Parameters:

• model (str) - The name of the model.
• equation (str) - The equation type to use. The 3 allowed types are: 'mf_orig' for the original model-free equations with parameters {s2, te}; 'mf_ext' for the extended model-free equations with parameters {s2f, tf, s2, ts}; and 'mf_ext2' for the extended model-free equations with parameters {s2f, tf, s2s, ts}.
• params (list of str) - A list of the parameters to include in the model. The allowed parameter names includes those for the equation type as well as chemical exchange 'rex', the bond length 'r', and the chemical shift anisotropy 'csa'.
• spin_id (str) - The spin identification string.

_remove_tm(self, spin_id=None)

Remove local tm from the set of model-free parameters for the given spins.

Parameters:

• spin_id (str or None) - The spin identification string.

_select_model(self, model=None, spin_id=None)

Function for the selection of a preset model-free model.

Parameters:

• model (str) - The name of the model.
• spin_id (str) - The spin identification string.

_units_rex(self)

Return the units for the Rex parameter.

Returns: str

The field strength dependent Rex units.

create_mc_data(self, data_id=None)

Create the Monte Carlo Ri data.

Parameters:

• data_id (str) - The spin identification string, as yielded by the base_data_loop() generator method.

Returns: list of floats

The Monte Carlo simulation data.

data_init(self, data_cont, sim=False)

Initialise the spin specific data structures.

Parameters:

• data_cont (SpinContainer instance) - The spin data container.
• sim (bool) - The Monte Carlo simulation flag, which if true will initialise the simulation data structure.

data_names(self, set='all', error_names=False, sim_names=False)

Return a list of all spin container specific model-free object names.

Description

The names are as follows:

• 'model', the model-free model name.
• 'equation', the model-free equation type.
• 'params', an array of the model-free parameter names associated with the model.
• 's2', S2.
• 's2f', S2f.
• 's2s', S2s.
• 'local_tm', local tm.
• 'te', te.
• 'tf', tf.
• 'ts', ts.
• 'rex', Rex.
• 'r', bond length.
• 'csa', CSA value.
• 'nucleus', the heteronucleus type.
• 'chi2', chi-squared value.
• 'iter', iterations.
• 'f_count', function count.
• 'g_count', gradient count.
• 'h_count', hessian count.
• 'warning', minimisation warning.

Parameters:

• set (str) - The set of object names to return. This can be set to 'all' for all names, to 'generic' for generic object names, 'params' for model-free parameter names, or to 'min' for minimisation specific object names.
• error_names (bool) - A flag which if True will add the error object names as well.
• sim_names (bool) - A flag which if True will add the Monte Carlo simulation object names as well.

Returns: list of str

The list of object names.

data_type(self, param=None)

Return the type of data, as a string, that the parameter should be.

Parameters:

• param (list of str) - The parameter name.

Returns: str

The type of the parameter, as a string. I.e. 'int', 'float', 'str', 'bool', 'list of str', 'dict of bool', etc.

default_value(self, param)

The default model-free parameter values.

Parameters:

• param (str) - The model-free parameter.

Returns: float

The default value.

deselect(self, model_info, sim_index=None)

Deselect models or simulations.

Parameters:

• model_info (int) - The model index from model_loop(). This is zero for the global models or equal to the global spin index (which covers the molecule, residue, and spin indices).
• sim_index (None or int) - The optional Monte Carlo simulation index. If None, then models will be deselected, otherwise the given simulation will.

duplicate_data(self, pipe_from=None, pipe_to=None, model_info=None, global_stats=False, verbose=True)

Duplicate the data specific to a single model-free model.

Parameters:

• pipe_from (str) - The data pipe to copy the data from.
• pipe_to (str) - The data pipe to copy the data to.
• model_info (int) - The model index from model_loop(). This is zero for the global models or equal to the global spin index (which covers the molecule, residue, and spin indices).
• global_stats (bool) - The global statistics flag.
• verbose (bool) - A flag which if True will cause info about each spin to be printed out as the sequence is generated.

eliminate(self, name, value, model_info, args, sim=None)

Model-free model elimination, parameter by parameter.

Parameters:

• name (str) - The parameter name.
• value (float) - The parameter value.
• model_info (int) - The model index from model_loop(). This is zero for the global models or equal to the global spin index (which covers the molecule, residue, and spin indices).
• args (None or tuple of float) - The c1 and c2 elimination constant overrides.
• sim (int) - The Monte Carlo simulation index.

Returns: bool

True if the model is to be eliminated, False otherwise.

get_param_names(self, model_info=None)

Return a vector of parameter names.

Parameters:

• model_info (int) - The model index from model_loop(). This is zero for the global models or equal to the global spin index (which covers the molecule, residue, and spin indices).

Returns: list of str

The vector of parameter names.

get_param_values(self, model_info=None, sim_index=None)

Return a vector of parameter values.

Parameters:

• model_info (int) - The model index from model_info(). This is zero for the global models or equal to the global spin index (which covers the molecule, residue, and spin indices).
• sim_index (int) - The Monte Carlo simulation index.

Returns: list of str

The vector of parameter values.

is_spin_param(self, name)

Determine whether the given parameter is spin specific.

Unless a diffusion parameter is encountered, this method will return true.

Parameters:

• name (str) - The name of the parameter.

Returns: bool

If the parameter is a diffusion parameter, False I returned. Otherwise True is returned.

map_bounds(self, param, spin_id=None)

Create bounds for the OpenDX mapping function.

Parameters:

• param (str) - The name of the parameter to return the lower and upper bounds of.
• spin_id (str) - The spin identification string.

Returns: list of float

The upper and lower bounds of the parameter.

model_desc(self, model_info)

Return a description of the model.

Parameters:

• model_info (int) - The model index from model_loop(). This is zero for the global models or equal to the global spin index (which covers the molecule, residue, and spin indices).

Returns: str

The model description.

model_loop(self)

Generator method for looping over the models (global or local).

If the model type is 'all' or 'diff', then this yields the single value of zero. Otherwise the global spin index is yielded.

Returns: int

The model index. This is zero for the global models or equal to the global spin index (which covers the molecule, residue, and spin indices).

model_statistics(self, model_info=None, spin_id=None, global_stats=None)

Return the k, n, and chi2 model statistics.

k - number of parameters. n - number of data points. chi2 - the chi-squared value.

Parameters:

• model_info (int) - The model index from model_loop(). This is zero for the global models or equal to the global spin index (which covers the molecule, residue, and spin indices).
• spin_id (None or str) - The spin identification string. Either this or the instance keyword argument must be supplied.
• global_stats (None or bool) - A parameter which determines if global or local statistics are returned. If None, then the appropriateness of global or local statistics is automatically determined.

Returns: tuple of (int, int, float)

The optimisation statistics, in tuple format, of the number of parameters (k), the number of data points (n), and the chi-squared value (chi2).

model_type(self)

Return the type of the model, either being 'local' or 'global'.

Returns: str

The model type, one of 'local' or 'global'.

num_instances(self)

Function for returning the number of instances.

Returns: int

The number of instances used for optimisation. Either the number of spins if the local optimisations are setup ('mf' and 'local_tm'), or 1 for the global models.

return_data_desc(self, name)

Return a description of the spin specific object.

Parameters:

• name (str) - The name of the spin specific object.

Returns: str or None

The object description, or None.

return_data_name(self, param)

Return a unique identifying string for the model-free parameter.

Parameters:

• param (str) - The model-free parameter name.

Returns: str

The unique parameter identifying string.

set_error(self, model_info, index, error)

Set the parameter errors.

Parameters:

• model_info (int) - The model index from model_loop(). This is zero for the global models or equal to the global spin index (which covers the molecule, residue, and spin indices).
• index (int) - The index of the parameter to set the errors for.
• error (float) - The error value.

set_param_values(self, param=None, value=None, spin_id=None, force=True)

Set the model-free parameter values.

Parameters:

• param (list of str) - The parameter name list.
• value (list) - The parameter value list.
• spin_id (None or str) - The spin identification string, only used for spin specific parameters.
• force (bool) - A flag which if True will cause current values to be overwritten. If False, a RelaxError will raised if the parameter value is already set.

set_selected_sim(self, model_info, select_sim)

Set all simulation selection flags.

Parameters:

• model_info (int) - The model index from model_loop(). This is zero for the global models or equal to the global spin index (which covers the molecule, residue, and spin indices).
• select_sim (bool) - The selection flags.

set_update(self, param, spin)

Function to update the other model-free parameters.

Parameters:

• param (str) - The name of the parameter which has been changed.
• spin (SpinContainer) - The SpinContainer object.

sim_return_chi2(self, model_info, index=None)

Return the simulation chi-squared values.

Parameters:

• model_info (int) - The model index from model_loop(). This is zero for the global models or equal to the global spin index (which covers the molecule, residue, and spin indices).
• index (int) - The optional simulation index.

Returns: list of float or float

The list of simulation chi-squared values. If the index is supplied, only a single value will be returned.

sim_return_param(self, model_info, index)

Return the array of simulation parameter values.

Parameters:

• model_info (int) - The model index from model_loop(). This is zero for the global models or equal to the global spin index (which covers the molecule, residue, and spin indices).
• index (int) - The index of the parameter to return the array of values for.

Returns: list of float

The array of simulation parameter values.

sim_return_selected(self, model_info)

Return the array of selected simulation flags for the spin.

Parameters:

• model_info (int) - The model index from model_loop(). This is zero for the global models or equal to the global spin index (which covers the molecule, residue, and spin indices).

Returns: list of int

The array of selected simulation flags.

skip_function(self, model_info)

Skip certain data.

Parameters:

• model_info (int) - The model index from model_loop(). This is zero for the global models or equal to the global spin index (which covers the molecule, residue, and spin indices).

Returns: bool

True if the data should be skipped, False otherwise.

Class Variable Details

default_value_doc

Value:

['Model-free default values',
 '''
        ______________________________________________________________
_________________________
        |                                       |                    |
                        |
        | Data type                             | Object name        |
 Value                  |
...

eliminate_doc

Value:

[['Local tm model elimination rule',
  '''
        The local tm, in some cases, may exceed the value expected for
 a global correlation time. Generally the tm value will be stuck at th
e upper limit defined for the parameter.  These models are eliminated 
using the rule:

            tm >= c
...

return_data_name_doc

Value:

['Model-free data type string matching patterns',
 '''
        _____________________________________________
        |                        |                  |
        | Data type              | Object name      |
        |________________________|__________________|
        |                        |                  |
        | Local tm               | \'local_tm\'       |
...

set_doc

Value:

['Model-free set details',
 '''
        Setting a parameter value may have no effect depending on whic
h model-free model is chosen, for example if S2f values and S2s values
 are set but the run corresponds to model-free model \'m4\' then, beca
use these data values are not parameters of the model, they will have 
no effect.

...