Package specific_analyses :: Package relax_disp :: Module api :: Class Relax_disp
[hide private]
[frames] | no frames]

Class Relax_disp

source code


Class containing functions for relaxation dispersion curve fitting.

Instance Methods [hide private]
 
__init__(self)
Initialise the class by placing API_common methods into the API.
source code
numpy rank-1 float array
_back_calc_peak_intensities(self, spin=None, exp_type=None, frq=None, offset=None, point=None)
Back-calculation of peak intensity for the given relaxation time.
source code
 
_calculate_r2eff(self)
Calculate the R2eff values for fixed relaxation time period data.
source code
 
_cluster(self, cluster_id=None, spin_id=None)
Define spin clustering.
source code
list of str
_cluster_ids(self)
Return the current list of cluster ID strings.
source code
 
_minimise_r2eff(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)
Optimise the R2eff model by fitting the 2-parameter exponential curves.
source code
 
_model_setup(self, model, params)
Update various model specific data structures.
source code
 
_select_model(self, model='R2eff')
Set up the model for the relaxation dispersion analysis.
source code
(tuple of SpinContainer instance and float) or (SpinContainer instance and str)
base_data_loop(self)
Custom generator method for looping over the base data.
source code
 
calculate(self, spin_id=None, verbosity=1, sim_index=None)
Calculate the model chi-squared value or the R2eff values for fixed time period data.
source code
str
constraint_algorithm(self)
Return the 'Log barrier' optimisation constraint algorithm.
source code
list of floats
create_mc_data(self, data_id)
Create the Monte Carlo peak intensity data.
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.
source code
bool
eliminate(self, name, value, model_info, args, sim=None)
Relaxation dispersion 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
 
grid_search(self, lower=None, upper=None, inc=None, constraints=True, verbosity=1, sim_index=None)
The relaxation dispersion curve fitting grid search function.
source code
 
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)
Relaxation dispersion curve fitting function.
source code
str
model_desc(self, model_info)
Return a description of the model.
source code
tuple of list of SpinContainer instances and list of spin IDs
model_loop(self)
Loop over the spin groupings for one model applied to multiple spins.
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
 
overfit_deselect(self, data_check=True, verbose=True)
Deselect spins which have insufficient data to support minimisation.
source code
list of float
return_data(self, data_id=None)
Return the peak intensity data structure.
source code
list of float
return_error(self, data_id=None)
Return the standard deviation data structure.
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, model_info, index, error)
Set the parameter errors.
source code
 
set_selected_sim(self, model_info, select_sim)
Set the simulation selection flag.
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
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.
source code

Inherited from api_base.API_base: back_calc_ri, bmrb_read, bmrb_write, data_init, data_names, data_type, default_value, has_errors, is_spin_param, map_bounds, model_type, molmol_macro, num_instances, pymol_macro, read_columnar_results, return_conversion_factor, return_data_desc, return_data_name, return_grace_string, return_units, set_param_values, set_update, sim_return_chi2, skip_function, test_grid_ops

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

Class Variables [hide private]
  default_value_doc = Desc_container("Relaxation dispersion defa...
  return_data_name_doc = Desc_container("Relaxation dispersion c...
  _table = uf_tables.add_table(label= "table: dispersion curve-f...
  set_doc = Desc_container("Relaxation dispersion curve fitting ...

Inherited from api_base.API_base: eliminate_doc, write_doc

Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self)
(Constructor)

source code 

Initialise the class by placing API_common methods into the API.

Overrides: object.__init__

_back_calc_peak_intensities(self, spin=None, exp_type=None, frq=None, offset=None, point=None)

source code 

Back-calculation of peak intensity for the given relaxation time.

Parameters:
  • spin (SpinContainer instance) - The specific spin data container.
  • exp_type (str) - The experiment type.
  • frq (float) - The spectrometer frequency.
  • offset (None or float) - For R1rho-type data, the spin-lock offset value in ppm.
  • point (float) - The dispersion point data (either the spin-lock field strength in Hz or the nu_CPMG frequency in Hz).
Returns: numpy rank-1 float array
The back-calculated peak intensities for the given exponential curve.

_cluster(self, cluster_id=None, spin_id=None)

source code 

Define spin clustering.

Parameters:
  • cluster_id (str) - The cluster ID string.
  • spin_id (str) - The spin ID string for the spin or group of spins to add to the cluster.

_cluster_ids(self)

source code 

Return the current list of cluster ID strings.

Returns: list of str
The list of cluster IDs.

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

source code 

Optimise the R2eff model by fitting the 2-parameter exponential curves.

This mimics the R1 and R2 relax_fit analysis.

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_setup(self, model, params)

source code 

Update various model specific data structures.

Parameters:
  • model (str) - The relaxation dispersion curve type.
  • params (list of str) - A list consisting of the model parameters.

_select_model(self, model='R2eff')

source code 

Set up the model for the relaxation dispersion analysis.

Parameters:
  • model (str) - The relaxation dispersion analysis type.

base_data_loop(self)

source code 

Custom generator method for looping over the base data.

For the R2eff model, the base data is the peak intensity data defining a single exponential curve. For all other models, the base data is the R2eff/R1rho values for individual spins.

Returns: (tuple of SpinContainer instance and float) or (SpinContainer instance and str)
For the R2eff model, a tuple of the spin container and the exponential curve identifying key (the CPMG frequency or R1rho spin-lock field strength). For all other models, the spin container and ID from the spin loop.
Overrides: api_base.API_base.base_data_loop

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

source code 

Calculate the model chi-squared value or the R2eff values for fixed time period data.

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) - The MC simulation index (unused).
Overrides: api_base.API_base.calculate

constraint_algorithm(self)

source code 

Return the 'Log barrier' optimisation constraint algorithm.

Returns: str
The 'Log barrier' constraint algorithm.
Overrides: api_base.API_base.constraint_algorithm

create_mc_data(self, data_id)

source code 

Create the Monte Carlo peak intensity data.

Parameters:
  • data_id (SpinContainer instance and float) - The tuple of the spin container and the exponential curve identifying key, 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

deselect(self, model_info, sim_index=None)

source code 

Deselect models or simulations.

Parameters:
  • model_info (int) - The spin ID list from the model_loop() API method.
  • sim_index (None or int) - The optional Monte Carlo simulation index. If None, then models will be deselected, otherwise the given simulation will.
Overrides: api_base.API_base.deselect

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 (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.
Overrides: api_base.API_base.duplicate_data

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

source code 

Relaxation dispersion model elimination, parameter by parameter.

Parameters:
  • name (str) - The parameter name.
  • value (float) - The parameter value.
  • model_info (int) - The list of spin IDs from the model_loop() API method.
  • 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.
Overrides: api_base.API_base.eliminate

get_param_names(self, model_info=None)

source code 

Return a vector of parameter names.

Parameters:
  • model_info (list of str) - The list spin ID strings from the model_loop() API method.
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)

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.
Overrides: api_base.API_base.get_param_values

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

source code 

The relaxation dispersion curve fitting grid search function.

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.
Overrides: api_base.API_base.grid_search

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)

source code 

Relaxation dispersion curve fitting function.

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.
Overrides: api_base.API_base.minimise

model_desc(self, model_info)

source code 

Return a description of the model.

Parameters:
  • model_info (int) - The model index from model_info().
Returns: str
The model description.
Overrides: api_base.API_base.model_desc

model_loop(self)

source code 

Loop over the spin groupings for one model applied to multiple spins.

Returns: tuple of list of SpinContainer instances and list of spin IDs
The list of spins per block will be yielded, as well as the list of spin IDs.
Overrides: api_base.API_base.model_loop

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 (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).
Overrides: api_base.API_base.model_statistics

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

source code 

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

return_data(self, data_id=None)

source code 

Return the peak intensity data structure.

Parameters:
  • data_id (str) - The spin ID string, as yielded by the base_data_loop() generator method.
Returns: list of float
The peak intensity data structure.
Overrides: api_base.API_base.return_data

return_error(self, data_id=None)

source code 

Return the standard deviation data structure.

Parameters:
  • data_id (SpinContainer instance and float) - The tuple of the spin container and the exponential curve identifying key, as yielded by the base_data_loop() generator method.
Returns: list of float
The standard deviation data structure.
Overrides: api_base.API_base.return_error

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
Overrides: api_base.API_base.return_value

set_error(self, model_info, index, error)

source code 

Set the parameter errors.

Parameters:
  • model_info (unknown) - The spin container originating from model_loop().
  • index (int) - The index of the parameter to set the errors for.
  • error (float) - The error value.
Overrides: api_base.API_base.set_error

set_selected_sim(self, model_info, select_sim)

source code 

Set the simulation selection flag.

Parameters:
  • model_info (tuple of list of SpinContainer instances and list of spin IDs) - The list of spins and spin IDs per cluster originating from model_loop().
  • select_sim (bool) - The selection flag for the simulations.
Overrides: api_base.API_base.set_selected_sim

sim_init_values(self)

source code 

Initialise the Monte Carlo parameter values.

Overrides: api_base.API_base.sim_init_values

sim_pack_data(self, data_id, sim_data)

source code 

Pack the Monte Carlo simulation data.

Parameters:
  • data_id (SpinContainer instance and float) - The tuple of the spin container and the exponential curve identifying key, as yielded by the base_data_loop() generator method.
  • sim_data (list of float) - The Monte Carlo simulation data.
Overrides: api_base.API_base.sim_pack_data

sim_return_param(self, model_info, index)

source code 

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.
Overrides: api_base.API_base.sim_return_param

sim_return_selected(self, model_info)

source code 

Return the array of selected simulation flags.

Parameters:
  • model_info (tuple of list of SpinContainer instances and list of spin IDs) - The list of spins and spin IDs per cluster originating from model_loop().
Returns: list of int
The array of selected simulation flags.
Overrides: api_base.API_base.sim_return_selected

Class Variable Details [hide private]

default_value_doc

Value:
Desc_container("Relaxation dispersion default values")

return_data_name_doc

Value:
Desc_container("Relaxation dispersion curve fitting data type string m\
atching patterns")

_table

Value:
uf_tables.add_table(label= "table: dispersion curve-fit data type patt\
erns", caption= "Relaxation dispersion curve fitting data type string \
matching patterns.")

set_doc

Value:
Desc_container("Relaxation dispersion curve fitting set details")