Class Model_free

Parent class containing all the model-free specific functions.

Instance Methods

__init__(self)
Initialise the class by placing API_common methods into the API.

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.

bmrb_read(self, file_path, version=None, sample_conditions=None)
Read the model-free results from a BMRB NMR-STAR v3.1 formatted file.

bmrb_write(self, file_path, version=None)
Write the model-free results to a BMRB NMR-STAR v3.1 formatted file.

calculate(self, spin_id=None, scaling_matrix=None, verbosity=1, sim_index=None)
Calculation of the model-free chi-squared value.

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

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

deselect(self, sim_index=None, model_info=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, args, sim=None, model_info=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.

grid_search(self, lower=None, upper=None, inc=None, scaling_matrix=None, constraints=True, verbosity=1, sim_index=None)
The model-free grid search function.

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

minimise(self, min_algor=None, min_options=None, func_tol=None, grad_tol=None, max_iterations=None, constraints=False, scaling_matrix=None, verbosity=0, sim_index=None, lower=None, upper=None, inc=None)
Model-free minimisation function.

str model_desc(self, model_info=None)
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, data_check=True, verbose=True)
Deselect spins which have insufficient data to support minimisation.

print_model_title(self, prefix=None, model_info=None)
Print out the model title.

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

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

set_selected_sim(self, select_sim, model_info=None)
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, index=None, model_info=None)
Return the simulation chi-squared values.

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

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

bool skip_function(self, model_info=None)
Skip certain data.

Inherited from api_base.API_base: base_data_loop, constraint_algorithm, covariance_matrix, data_names, data_type, default_value, get_model_container, has_errors, is_spin_param, molmol_macro, pymol_macro, return_conversion_factor, return_data, return_data_desc, return_error, return_error_red_chi2, return_grace_string, return_grace_units, return_units, return_value, sim_pack_data

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Inherited from api_common.API_common (private): _base_data_loop_spin, _create_mc_relax_data, _data_init_dummy, _data_init_spin, _deselect_global, _eliminate_false, _get_model_container_cdp, _has_errors_spin, _is_spin_param_false, _is_spin_param_true, _model_loop_single_global, _model_loop_spin, _model_type_global, _model_type_local, _num_instances_spin, _overfit_deselect_dummy, _print_model_title_global, _print_model_title_spin, _return_data_relax_data, _return_error_relax_data, _return_no_conversion_factor, _return_value_general, _set_error_spin, _set_param_values_global, _set_param_values_spin, _set_selected_sim_global, _set_selected_sim_spin, _set_update, _sim_init_values_spin, _sim_pack_relax_data, _sim_return_chi2_spin, _sim_return_param_spin, _sim_return_selected_global, _sim_return_selected_spin

Static Methods

Inherited from api_base.API_base: __new__

Class Variables

instance = Model_free()
hash(x)

Properties

Inherited from object: __class__

Method Details

__init__(self)
(Constructor)

Initialise the class by placing API_common methods into the API.

Overrides: object.__init__

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.

Overrides: api_base.API_base.back_calc_ri

bmrb_read(self, file_path, version=None, sample_conditions=None)

Read the model-free results from a BMRB NMR-STAR v3.1 formatted file.

Parameters:

• file_path (str) - The full file path.
• version (None or str) - The BMRB version to force the reading.
• sample_conditions (None or str) - The sample condition label to read. Only one sample condition can be read per data pipe.

Overrides: api_base.API_base.bmrb_read

bmrb_write(self, file_path, version=None)

Write the model-free results to a BMRB NMR-STAR v3.1 formatted file.

Parameters:

• file_path (str) - The full file path.
• version (str) - The BMRB NMR-STAR dictionary format to output to.

Overrides: api_base.API_base.bmrb_write

calculate(self, spin_id=None, scaling_matrix=None, verbosity=1, sim_index=None)

Calculation of the model-free chi-squared value.

Parameters:

• spin_id (str) - The spin identification string.
• scaling_matrix (list of numpy rank-2, float64 array or list of None) - The per-model list of diagonal and square scaling matrices.
• verbosity (int) - The amount of information to print. The higher the value, the greater the verbosity.
• sim_index (int) - The optional MC simulation index.

Overrides: api_base.API_base.calculate

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.

Overrides: api_base.API_base.create_mc_data

data_init(self, data, sim=False)

Initialise the spin specific data structures.

Parameters:

• data (str) - The spin ID string from the _base_data_loop_spin() method.
• sim (bool) - The Monte Carlo simulation flag, which if true will initialise the simulation data structure.

Overrides: api_base.API_base.data_init

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

Deselect models or simulations.

Parameters:

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

Overrides: api_base.API_base.deselect

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 information from model_loop(). This index 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.

Overrides: api_base.API_base.duplicate_data

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

Model-free model elimination, parameter by parameter.

Parameters:

• name (str) - The parameter name.
• value (float) - The parameter value.
• args (None or tuple of float) - The c1 and c2 elimination constant overrides.
• sim (int) - The Monte Carlo simulation index.
• model_info (int) - The model information from model_loop(). This index 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 model is to be eliminated, False otherwise.

Overrides: api_base.API_base.eliminate

get_param_names(self, model_info=None)

Return a vector of parameter names.

Parameters:

• model_info (int) - The model information from model_loop(). This index 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.

Overrides: api_base.API_base.get_param_names

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

Return a vector of parameter values.

Parameters:

• model_info (int) - The model information from model_loop(). This index 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.

Overrides: api_base.API_base.get_param_values

grid_search(self, lower=None, upper=None, inc=None, scaling_matrix=None, constraints=True, verbosity=1, sim_index=None)

The model-free grid search function.

Parameters:

• lower (list of lists of numbers) - The per-model lower bounds of the grid search which must be equal to the number of parameters in the model.
• upper (list of lists of numbers) - The per-model upper bounds of the grid search which must be equal to the number of parameters in the model.
• inc (list of lists of int) - The per-model increments for each dimension of the space for the grid search. The number of elements in the array must equal to the number of parameters in the model.
• scaling_matrix (list of numpy rank-2, float64 array or list of None) - The per-model list of diagonal and square scaling matrices.
• constraints (bool) - If True, constraints are applied during the grid search (eliminating parts of the grid). If False, no constraints are used.
• verbosity (int) - A flag specifying the amount of information to print. The higher the value, the greater the verbosity.
• sim_index (int) - The index of the simulation to apply the grid search to. If None, the normal model is optimised.

Overrides: api_base.API_base.grid_search

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.

Overrides: api_base.API_base.map_bounds

minimise(self, min_algor=None, min_options=None, func_tol=None, grad_tol=None, max_iterations=None, constraints=False, scaling_matrix=None, verbosity=0, sim_index=None, lower=None, upper=None, inc=None)

Model-free minimisation function.

Three categories of models exist for which the approach to minimisation is different. These are:

Single spin optimisations: The 'mf' and 'local_tm' model types which are the model-free parameters for single spins, optionally with a local tm parameter. These models have no global parameters.

Diffusion tensor optimisations: The 'diff' diffusion tensor model type. No spin specific parameters exist.

Optimisation of everything: The 'all' model type consisting of all model-free and all diffusion tensor parameters.

Parameters:

• min_algor (str) - The minimisation algorithm to use.
• min_options (array of str) - An array of options to be used by the minimisation algorithm.
• func_tol (None or float) - The function tolerance which, when reached, terminates optimisation. Setting this to None turns of the check.
• grad_tol (None or float) - The gradient tolerance which, when reached, terminates optimisation. Setting this to None turns of the check.
• max_iterations (int) - The maximum number of iterations for the algorithm.
• constraints (bool) - If True, constraints are used during optimisation.
• scaling_matrix (list of numpy rank-2, float64 array or list of None) - The per-model list of diagonal and square scaling matrices.
• verbosity (int) - The amount of information to print. The higher the value, the greater the verbosity.
• sim_index (None or int) - The index of the simulation to optimise. This should be None if normal optimisation is desired.
• lower (list of lists of numbers) - The per-model lower bounds of the grid search which must be equal to the number of parameters in the model. This optional argument is only used when doing a grid search.
• upper (list of lists of numbers) - The per-model upper bounds of the grid search which must be equal to the number of parameters in the model. This optional argument is only used when doing a grid search.
• inc (list of lists of int) - The per-model increments for each dimension of the space for the grid search. The number of elements in the array must equal to the number of parameters in the model. This argument is only used when doing a grid search.

Overrides: api_base.API_base.minimise

model_desc(self, model_info=None)

Return a description of the model.

Parameters:

• model_info (int) - The model information from model_loop(). This index 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.

Overrides: api_base.API_base.model_desc

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 index is zero for the global models or equal to the global spin index (which covers the molecule, residue, and spin indices).

Overrides: api_base.API_base.model_loop

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 information from model_loop(). This index 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).

Overrides: api_base.API_base.model_statistics

model_type(self)

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

Returns: str

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

Overrides: api_base.API_base.model_type

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.

Overrides: api_base.API_base.num_instances

overfit_deselect(self, data_check=True, verbose=True)

Deselect spins which have insufficient data to support minimisation.

Parameters:

• data_check (bool) - A flag to signal if the presence of base data is to be checked for.
• verbose (bool) - A flag which if True will allow printouts.

Overrides: api_base.API_base.overfit_deselect

print_model_title(self, prefix=None, model_info=None)

Print out the model title.

Parameters:

• prefix (str) - The starting text of the title. This should be printed out first, followed by the model information text.
• model_info (unknown) - The model information from model_loop().

Overrides: api_base.API_base.print_model_title

set_error(self, index, error, model_info=None)

Set the parameter errors.

Parameters:

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

Overrides: api_base.API_base.set_error

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

Set the model-free parameter values.

Parameters:

• param (list of str) - The parameter name list.
• value (list) - The parameter value list.
• index (None or int) - The index for parameters which are of the list-type. This is unused.
• spin_id (None or str) - The spin identification string, only used for spin specific parameters.
• error (bool) - A flag which if True will allow the parameter errors to be set instead of the values.
• 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.

Overrides: api_base.API_base.set_param_values

set_selected_sim(self, select_sim, model_info=None)

Set all simulation selection flags.

Parameters:

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

Overrides: api_base.API_base.set_selected_sim

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.

Overrides: api_base.API_base.set_update

sim_init_values(self)

Initialise the Monte Carlo parameter values.

Overrides: api_base.API_base.sim_init_values

sim_return_chi2(self, index=None, model_info=None)

Return the simulation chi-squared values.

Parameters:

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

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.

Overrides: api_base.API_base.sim_return_chi2

sim_return_param(self, index, model_info=None)

Return the array of simulation parameter values.

Parameters:

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

Returns: list of float

The array of simulation parameter values.

Overrides: api_base.API_base.sim_return_param

sim_return_selected(self, model_info=None)

Return the array of selected simulation flags for the spin.

Parameters:

• model_info (int) - The model information from model_loop(). This index 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.

Overrides: api_base.API_base.sim_return_selected

skip_function(self, model_info=None)

Skip certain data.

Parameters:

• model_info (int) - The model information from model_loop(). This index 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.

Overrides: api_base.API_base.skip_function