Package specific_analyses :: Module api_base :: Class API_base
[hide private]
[frames] | no frames]

Class API_base

source code


Base class defining the specific_analyses 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 [hide private]
float
back_calc_ri(self, spin_index=None, ri_id=None, ri_type=None, frq=None)
Back-calculation of relaxation data.
source code
anything
base_data_loop(self)
Generator method for looping over the base data of the specific analysis type.
source code
 
bmrb_read(self, file_path, version=None, sample_conditions=None)
Prototype method for reading the data from a BMRB NMR-STAR formatted file.
source code
 
bmrb_write(self, file_path, version=None)
Prototype method for writing the data to a BMRB NMR-STAR formatted file.
source code
 
calculate(self, spin_id=None, scaling_matrix=None, verbosity=1, sim_index=None)
Calculate the chi-squared value.
source code
str
constraint_algorithm(self)
Return the optimisation constraint algorithm, defaulting to the Method of Multipliers.
source code
numpy rank-2 array, numpy rank-2 array
covariance_matrix(self, model_info=None, verbosity=1)
Return the Jacobian and weights required for parameter errors via the covariance matrix.
source code
list of floats
create_mc_data(self, data_id=None)
Create the Monte Carlo data.
source code
 
data_init(self, data, sim=False)
Initialise the data structures.
source code
list of str
data_names(self, set='all', scope=None, error_names=False, sim_names=False)
Return a list of names of data structures.
source code
any type
data_type(self, param=None)
Return the type of data that the parameter should be.
source code
float
default_value(self, param)
Return the default parameter values.
source code
 
deselect(self, sim_index=None, model_info=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.
source code
bool
eliminate(self, name, value, args, sim=None, model_info=None)
Model elimination method.
source code
class instance
get_model_container(self, model_info=None)
Return the data container for the model.
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
 
grid_search(self, lower=None, upper=None, inc=None, scaling_matrix=None, constraints=True, verbosity=1, sim_index=None)
Grid search method.
source code
bool
has_errors(self)
Test if errors exist for the current data pipe.
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
 
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)
Minimisation method.
source code
str
model_desc(self, model_info=None)
Return a description of the model.
source code
anything
model_loop(self)
Generator method for looping over the models.
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
 
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.
source code
int
num_instances(self)
Return the number of instances (depreciated).
source code
 
overfit_deselect(self, data_check=True, verbose=True)
Deselect models with insufficient data for minimisation.
source code
 
print_model_title(self, prefix=None, model_info=None)
Print out the model title.
source code
 
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.
source code
float
return_conversion_factor(self, param)
Return the conversion factor.
source code
list of float
return_data(self, data_id=None)
Return the data points used in optimisation.
source code
str or None
return_data_desc(self, name)
Return a description of the parameter.
source code
list of float
return_error(self, data_id=None)
Return the error points corresponding to the data points used in optimisation.
source code
list of float
return_error_red_chi2(self, data_id=None)
Return the error points corresponding to the overall gauss distribution described by the STD_fit of the goodness of fit, where STD_fit = sqrt(chi2/(N-p)).
source code
str
return_grace_string(self, param)
Return the Grace string representation of the parameter.
source code
str
return_grace_units(self, param)
Return a Grace string representing the parameters units.
source code
str
return_units(self, param)
Return a string representing the parameters units.
source code
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.
source code
 
set_error(self, index, error, model_info=None)
Set the model parameter errors.
source code
 
set_param_values(self, param=None, value=None, index=None, spin_id=None, error=False, force=True)
Set the model parameter values.
source code
 
set_selected_sim(self, select_sim, model_info=None)
Set the simulation selection flag.
source code
 
set_update(self, param, spin)
Update other parameter values.
source code
 
sim_init_values(self)
Initialise the Monte Carlo parameter values.
source code
 
sim_pack_data(self, data_id, sim_data)
Pack the Monte Carlo simulation data.
source code
list of float or float
sim_return_chi2(self, index=None, model_info=None)
Return the simulation chi-squared values.
source code
list of float
sim_return_param(self, index, model_info=None)
Return the array of simulation parameter values.
source code
list of int
sim_return_selected(self, model_info=None)
Return the array of selected simulation flags for the spin.
source code
bool
skip_function(self, model_info=None)
Skip certain data.
source code

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

Static Methods [hide private]
a new object with type S, a subtype of T
__new__(self, *args, **kargs)
Replacement function for implementing the singleton design pattern.
source code
Class Variables [hide private]
  instance = None
hash(x)
Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__new__(self, *args, **kargs)
Static Method

source code 

Replacement function for implementing the singleton design pattern.

Returns: a new object with type S, a subtype of T
Overrides: object.__new__

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

source code 

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)

source code 

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)

source code 

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)

source code 

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, scaling_matrix=None, verbosity=1, sim_index=None)

source code 

Calculate the chi-squared value.

Parameters:
  • spin_id (None or str) - The spin ID 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 (None or int) - The optional MC simulation index.

constraint_algorithm(self)

source code 

Return the optimisation constraint algorithm, defaulting to the Method of Multipliers.

This can return one of:

  • 'Method of Multipliers',
  • 'Log barrier'.
Returns: str
The constraint algorithm to use (one of 'Method of Multipliers' or 'Log barrier').

covariance_matrix(self, model_info=None, verbosity=1)

source code 

Return the Jacobian and weights required for parameter errors via the covariance matrix.

Parameters:
  • model_info (unknown) - The model information from model_loop().
  • verbosity (int) - The amount of information to print. The higher the value, the greater the verbosity.
Returns: numpy rank-2 array, numpy rank-2 array
The Jacobian and weight matrices for the given model.

create_mc_data(self, data_id=None)

source code 

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, sim=False)

source code 

Initialise the data structures.

Parameters:
  • data (unknown) - The data from the base_data_loop() method.
  • 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)

source code 

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)

source code 

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)

source code 

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, sim_index=None, model_info=None)

source code 

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

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.

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 (unknown) - The model information from model_loop().
  • 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, args, sim=None, model_info=None)

source code 

Model elimination method.

Parameters:
  • name (str) - The parameter name.
  • value (float) - The parameter value.
  • args (None or tuple of float) - The elimination constant overrides.
  • sim (int) - The Monte Carlo simulation index.
  • model_info (unknown) - The model information from model_loop().
Returns: bool
True if the model is to be eliminated, False otherwise.

get_model_container(self, model_info=None)

source code 

Return the data container for the model.

Parameters:
  • model_info (unknown) - The model information from model_loop().
Returns: class instance
The data container corresponding to the model.

get_param_names(self, model_info=None)

source code 

Return a vector of parameter names.

Parameters:
  • model_info (unknown) - The model information from model_loop().
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 (unknown) - The model information from model_loop().
  • 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, scaling_matrix=None, constraints=True, verbosity=1, sim_index=None)

source code 

Grid search method.

Parameters:
  • lower (list of lists of floats) - 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 floats) - 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.

has_errors(self)

source code 

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)

source code 

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)

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 (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_matrix=None, verbosity=0, sim_index=None, lower=None, upper=None, inc=None)

source code 

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_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 float) - 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 float) - 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.

model_desc(self, model_info=None)

source code 

Return a description of the model.

Parameters:
  • model_info (unknown) - The model information from model_loop().
Returns: str
The model description.

model_loop(self)

source code 

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)

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 (unknown) - The model information from model_loop().
  • spin_id (None or str) - The spin ID string to override the model_info argument. 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)

source code 

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)

source code 

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)

source code 

Return the number of instances (depreciated).

Returns: int
The number of instances.

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

source code 

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.

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

source code 

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

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

source code 

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.

return_conversion_factor(self, param)

source code 

Return the conversion factor.

Parameters:
  • param (str) - The parameter name.
Returns: float
A conversion factor of 1.0.

return_data(self, data_id=None)

source code 

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)

source code 

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_error(self, data_id=None)

source code 

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_error_red_chi2(self, data_id=None)

source code 

Return the error points corresponding to the overall gauss distribution described by the STD_fit of the goodness of fit, where STD_fit = sqrt(chi2/(N-p)).

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)

source code 

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_grace_units(self, param)

source code 

Return a Grace string representing the parameters units.

Parameters:
  • param (str) - The name of the parameter to return the units string for.
Returns: str
The Grace formatted parameter units string.

return_units(self, param)

source code 

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)

source code 

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, index, error, model_info=None)

source code 

Set the model parameter errors.

Parameters:
  • index (int) - The index of the parameter to set the errors for.
  • error (float) - The error value.
  • model_info (unknown) - The model information from model_loop().

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

source code 

Set the model 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 ignored for all other types.
  • 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.

set_selected_sim(self, select_sim, model_info=None)

source code 

Set the simulation selection flag.

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

set_update(self, param, spin)

source code 

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)

source code 

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, index=None, model_info=None)

source code 

Return the simulation chi-squared values.

Parameters:
  • index (int) - The optional simulation index.
  • model_info (unknown) - The model information from model_loop().
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, index, model_info=None)

source code 

Return the array of simulation parameter values.

Parameters:
  • index (int) - The index of the parameter to return the array of values for.
  • model_info (unknown) - The model information from model_loop().
Returns: list of float
The array of simulation parameter values.

sim_return_selected(self, model_info=None)

source code 

Return the array of selected simulation flags for the spin.

Parameters:
  • model_info (unknown) - The model information from model_loop().
Returns: list of int
The array of selected simulation flags.

skip_function(self, model_info=None)

source code 

Skip certain data.

Parameters:
  • model_info (unknown) - The model information from model_loop().
Returns: bool
True if the data should be skipped, False otherwise.