Class API_base

Base class defining the specific_fns API.

All the methods here are prototype methods. To identify that the method is not available for certain analysis types, if called a RelaxImplementError is raised if called.

Instance Methods

__init__(self)
Set up the specific objects.

float back_calc_ri(self, spin_index=None, ri_id=None, ri_type=None, frq=None)
Back-calculation of relaxation data.

anything base_data_loop(self)
Generator method for looping over the base data of the specific analysis type.

bmrb_read(self, file_path, version=None, sample_conditions=None)
Prototype method for reading the data from a BMRB NMR-STAR formatted file.

bmrb_write(self, file_path, version=None)
Prototype method for writing the data to a BMRB NMR-STAR formatted file.

calculate(self, spin_id=None, verbosity=1, sim_index=None)
Calculate the chi-squared value.

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

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

list of str data_names(self, set='all', scope=None, error_names=False, sim_names=False)
Return a list of names of data structures.

any type data_type(self, param=None)
Return the type of data that the parameter should be.

float default_value(self, param)
Return the default 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.

bool eliminate(self, name, value, model_info, args, sim=None)
Model elimination method.

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, constraints=True, verbosity=1, sim_index=None)
Grid search method.

bool has_errors(self)
Test if errors exist for the current data pipe.

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.

minimise(self, min_algor=None, min_options=None, func_tol=None, grad_tol=None, max_iterations=None, constraints=False, scaling=True, verbosity=0, sim_index=None, lower=None, upper=None, inc=None)
Minimisation method.

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

anything model_loop(self)
Generator method for looping over the models.

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'.

molmol_macro(self, data_type, style=None, colour_start=None, colour_end=None, colour_list=None, spin_id=None)
Create and return an array of Molmol macros.

int num_instances(self)
Return the number of instances (depreciated).

overfit_deselect(self, data_check=True, verbose=True)
Deselect models with insufficient data for minimisation.

pymol_macro(self, data_type, style=None, colour_start=None, colour_end=None, colour_list=None, spin_id=None)
Create and return an array of PyMOL macros.

read_columnar_results(self, file_data, verbosity=1)
Read the columnar formatted results file.

float return_conversion_factor(self, param)
Return the conversion factor.

list of float return_data(self, data_id=None)
Return the data points used in optimisation.

str or None return_data_desc(self, name)
Return a description of the parameter.

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

list of float return_error(self, data_id=None)
Return the error points corresponding to the data points used in optimisation.

str return_grace_string(self, param)
Return the Grace string representation of the parameter.

str return_units(self, param)
Return a string representing the parameters units.

tuple of length 2 of floats or None return_value(self, spin, param, sim=None, bc=False)
Return the value and error corresponding to the parameter.

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

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

set_selected_sim(self, model_info, select_sim)
Set the simulation selection flag.

set_update(self, param, spin)
Update other parameter values.

sim_init_values(self)
Initialise the Monte Carlo parameter values.

sim_pack_data(self, data_id, sim_data)
Pack the Monte Carlo simulation data.

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.

test_grid_ops(self, lower=None, upper=None, inc=None, n=None)
Test that the grid search options are reasonable.

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

Class Variables

default_value_doc = ''

eliminate_doc = ''

return_data_name_doc = ''

set_doc = ''

write_doc = ''

Properties

Inherited from object: __class__

Method Details

__init__(self)
(Constructor)

Set up the specific objects.

Overrides: object.__init__

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

Back-calculation of relaxation data.

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.

base_data_loop(self)

Generator method for looping over the base data of the specific analysis type.

Specific implementations of this generator method are free to yield any type of data. The data which is yielded is then passed into API methods such as return_data(), return_error(), create_mc_data(), pack_sim_data(), etc., so these methods should handle the data thrown at them. If multiple data is yielded, this is caught as a tuple and passed into the dependent methods as a tuple.

Returns: anything

Information concerning the base data of the analysis.

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

Prototype method for reading the data from a BMRB NMR-STAR formatted file.

Parameters:

• file_path (str) - The full file path.

bmrb_write(self, file_path, version=None)

Prototype method for writing the data to a BMRB NMR-STAR formatted file.

Parameters:

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

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

Calculate the chi-squared value.

Parameters:

• spin_id (None or str) - The spin identification string.
• verbosity (int) - The amount of information to print. The higher the value, the greater the verbosity.
• sim_index (None or int) - The optional MC simulation index.

create_mc_data(self, data_id=None)

Create the Monte Carlo data.

Parameters:

• data_id (anything) - The data identification information, 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 data structures.

Parameters:

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

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

Return a list of names of data structures.

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 analysis specific parameter names, or to 'min' for minimisation specific object names.
• scope (str or None) - The scope of the parameter to return. If not set, then all will be returned. If set to 'global' or 'spin', then only the parameters within that scope will be returned.
• 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 that the parameter should be.

This basic method will first search for a global parameter and, if not found, then a spin parameter.

Parameters:

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

Returns: any type

The type of the parameter. I.e. the special Python type objects of int, float, str, bool, [str], {bool}, etc.

default_value(self, param)

Return the default parameter values.

This basic method will first search for a global parameter and, if not found, then a spin parameter.

Parameters:

• param (str) - The specific analysis 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_info().
• 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.

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_info().
• global_stats (bool) - The global statistics flag.
• verbose (bool) - A flag which if True will cause info to be printed out.

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

Model elimination method.

Parameters:

• name (str) - The parameter name.
• value (float) - The parameter value.
• model_info (int) - The model index from model_info().
• args (None or tuple of float) - The 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_info().

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().
• sim_index (int) - The optional Monte Carlo simulation index.

Returns: list of str

The vector of parameter values.

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

Grid search method.

Parameters:

• lower (array of numbers) - The lower bounds of the grid search which must be equal to the number of parameters in the model.
• upper (array of numbers) - The upper bounds of the grid search which must be equal to the number of parameters in the model.
• inc (array of int) - The 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.
• 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.

has_errors(self)

Test if errors exist for the current data pipe.

Returns: bool

The answer to the question of whether errors exist.

is_spin_param(self, name)

Determine whether the given parameter is spin specific.

Parameters:

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

Returns: bool

True if the parameter is spin specific, False otherwise.

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 (None or str) - The spin identification string.

Returns: list of float

The upper and lower bounds of the parameter.

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

Minimisation method.

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 (bool) - If True, diagonal scaling is enabled during optimisation to allow the problem to be better conditioned.
• 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 (array of numbers) - The 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 (array of numbers) - The 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 (array of int) - The 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.

model_desc(self, model_info)

Return a description of the model.

Parameters:

• model_info (int) - The model index from model_info().

Returns: str

The model description.

model_loop(self)

Generator method for looping over the models.

Returns: anything

Information identifying the model.

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 (None or int) - The model index from model_info().
• spin_id (None or str) - The spin identification string. This is ignored in the N-state model.
• global_stats (None or bool) - A parameter which determines if global or local statistics are returned. For the N-state model, this argument is ignored.

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'.

molmol_macro(self, data_type, style=None, colour_start=None, colour_end=None, colour_list=None, spin_id=None)

Create and return an array of Molmol macros.

Parameters:

• data_type (str) - The parameter name or data type.
• style (None or str) - The Molmol style.
• colour_start (str) - The starting colour (must be a MOLMOL or X11 name).
• colour_end (str) - The ending colour (must be a MOLMOL or X11 name).
• colour_list (str) - The colour list used, either 'molmol' or 'x11'.
• spin_id (str) - The spin identification string.

num_instances(self)

Return the number of instances (depreciated).

Returns: int

The number of instances.

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

Deselect models with insufficient data for 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.

pymol_macro(self, data_type, style=None, colour_start=None, colour_end=None, colour_list=None, spin_id=None)

Create and return an array of PyMOL macros.

Parameters:

• data_type (str) - The parameter name or data type.
• style (None or str) - The PyMOL style.
• colour_start (str) - The starting colour (must be a MOLMOL or X11 name).
• colour_end (str) - The ending colour (must be a MOLMOL or X11 name).
• colour_list (str) - The colour list used, either 'molmol' or 'x11'.
• spin_id (str) - The spin identification string.

read_columnar_results(self, file_data, verbosity=1)

Read the columnar formatted results file.

Parameters:

• file_data (list of lists of str) - The processed results file data.
• verbosity (int) - The amount of information to print. The higher the value, the greater the verbosity.

return_conversion_factor(self, param)

Return the conversion factor.

Parameters:

• param (str) - The parameter name.

Returns: float

A conversion factor of 1.0.

return_data(self, data_id=None)

Return the data points used in optimisation.

Parameters:

• data_id (anything) - The data identification information, as yielded by the base_data_loop() generator method.

Returns: list of float

The array of data values.

return_data_desc(self, name)

Return a description of the parameter.

This basic method will first search for a global parameter and, if not found, then a spin parameter.

Parameters:

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

Returns: str or None

The object description, or None.

return_data_name(self, param)

Return a unique identifying string for the given parameter.

Parameters:

• param (str) - The parameter name.

Returns: str

The unique parameter identifying string.

return_error(self, data_id=None)

Return the error points corresponding to the data points used in optimisation.

Parameters:

• data_id (anything) - The data identification information, as yielded by the base_data_loop() generator method.

Returns: list of float

The array of data error values.

return_grace_string(self, param)

Return the Grace string representation of the parameter.

This is used for axis labelling.

Parameters:

• param (str) - The specific analysis parameter.

Returns: str

The Grace string representation of the parameter.

return_units(self, param)

Return a string representing the parameters units.

Parameters:

• param (str) - The name of the parameter to return the units string for.

Returns: str

The parameter units string.

return_value(self, spin, param, sim=None, bc=False)

Return the value and error corresponding to the parameter.

If sim is set to an integer, return the value of the simulation and None.

Parameters:

• spin (SpinContainer) - The SpinContainer object.
• param (str) - The name of the parameter to return values for.
• sim (None or int) - The Monte Carlo simulation index.
• bc (bool) - The back-calculated data flag. If True, then the back-calculated data will be returned rather than the actual data.

Returns: tuple of length 2 of floats or None

The value and error corresponding to

set_error(self, model_info, index, error)

Set the model parameter errors.

Parameters:

• model_info (unknown) - The model information originating from model_loop().
• 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 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 the simulation selection flag.

Parameters:

• model_info (unknown) - The model information originating from model_loop().
• select_sim (bool) - The selection flag for the simulations.

set_update(self, param, spin)

Update other parameter values.

Parameters:

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

sim_pack_data(self, data_id, sim_data)

Pack the Monte Carlo simulation data.

Parameters:

• data_id (anything) - The data identification information, as yielded by the base_data_loop() generator method.
• sim_data (list of float) - The Monte Carlo simulation data.

sim_return_chi2(self, model_info, index=None)

Return the simulation chi-squared values.

Parameters:

• model_info (unknown) - The model information originating from model_loop().
• 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 (unknown) - The model information originating from model_loop().
• 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 (unknown) - The model information originating from model_loop().

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().

Returns: bool

True if the data should be skipped, False otherwise.

test_grid_ops(self, lower=None, upper=None, inc=None, n=None)

Test that the grid search options are reasonable.

Parameters:

• lower (array of numbers) - The lower bounds of the grid search which must be equal to the number of parameters in the model.
• upper (array of numbers) - The upper bounds of the grid search which must be equal to the number of parameters in the model.
• inc (array of int) - The 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.
• n (int) - The number of parameters in the model.