Package specific_fns :: Package model_free :: Module main :: Class Model_free_main
[hide private]
[frames] | no frames]

Class Model_free_main

source code


Class containing functions specific to model-free analysis.

Instance Methods [hide private]
str or None
_are_mf_params_set(self, spin)
Test if the model-free parameter values are set.
source code
list of str
_assemble_param_names(self, model_type, spin_id=None)
Function for assembling a list of all the model parameter names.
source code
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).
source code
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.
source code
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.
source code
 
_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.
source code
float
_conv_factor_rex(self)
Calculate and return the Rex conversion factor.
source code
 
_create_model(self, model=None, equation=None, params=None, spin_id=None)
Function for creating a custom model-free model.
source code
 
_delete(self)
Delete all the model-free data.
source code
str or None
_determine_model_type(self)
Determine the global model type.
source code
str, list
_model_map(self, model)
Return the equation name and parameter list corresponding to the given model.
source code
 
_model_setup(self, model=None, equation=None, params=None, spin_id=None)
Function for updating various data structures depending on the model selected.
source code
 
_remove_tm(self, spin_id=None)
Remove local tm from the set of model-free parameters for the given spins.
source code
 
_select_model(self, model=None, spin_id=None)
Function for the selection of a preset model-free model.
source code
str
_units_rex(self)
Return the units for the Rex parameter.
source code
list of floats
create_mc_data(self, data_id=None)
Create the Monte Carlo Ri data.
source code
 
data_init(self, data_cont, sim=False)
Initialise the spin specific data structures.
source code
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.
source code
str
data_type(self, param=None)
Return the type of data, as a string, that the parameter should be.
source code
float
default_value(self, param)
The default model-free parameter values.
source code
 
deselect(self, model_info, sim_index=None)
Deselect models or simulations.
source code
 
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.
source code
bool
eliminate(self, name, value, model_info, args, sim=None)
Model-free model elimination, parameter by parameter.
source code
list of str
get_param_names(self, model_info=None)
Return a vector of parameter names.
source code
list of str
get_param_values(self, model_info=None, sim_index=None)
Return a vector of parameter values.
source code
bool
is_spin_param(self, name)
Determine whether the given parameter is spin specific.
source code
list of float
map_bounds(self, param, spin_id=None)
Create bounds for the OpenDX mapping function.
source code
str
model_desc(self, model_info)
Return a description of the model.
source code
int
model_loop(self)
Generator method for looping over the models (global or local).
source code
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.
source code
str
model_type(self)
Return the type of the model, either being 'local' or 'global'.
source code
int
num_instances(self)
Function for returning the number of instances.
source code
 
overfit_deselect(self)
Deselect spins which have insufficient data to support minimisation.
source code
str or None
return_data_desc(self, name)
Return a description of the spin specific object.
source code
str
return_data_name(self, param)
Return a unique identifying string for the model-free parameter.
source code
 
set_error(self, model_info, index, error)
Set the parameter errors.
source code
 
set_param_values(self, param=None, value=None, spin_id=None, force=True)
Set the model-free parameter values.
source code
 
set_selected_sim(self, model_info, select_sim)
Set all simulation selection flags.
source code
 
set_update(self, param, spin)
Function to update the other model-free parameters.
source code
 
sim_init_values(self)
Initialise the Monte Carlo parameter values.
source code
list of float or float
sim_return_chi2(self, model_info, index=None)
Return the simulation chi-squared values.
source code
list of float
sim_return_param(self, model_info, index)
Return the array of simulation parameter values.
source code
list of int
sim_return_selected(self, model_info)
Return the array of selected simulation flags for the spin.
source code
bool
skip_function(self, model_info)
Skip certain data.
source code
Class Variables [hide private]
  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 [hide private]

_are_mf_params_set(self, spin)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

Return the units for the Rex parameter.

Returns: str
The field strength dependent Rex units.

create_mc_data(self, data_id=None)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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

Returns: str
The model type, one of 'local' or 'global'.

num_instances(self)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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 [hide private]

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.

...