Class Relax_disp

Class containing functions for relaxation dispersion curve fitting.

Instance Methods

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

(tuple of SpinContainer instance and float) or (SpinContainer instance and str) base_data_loop(self)
Custom generator method for looping over the base data.

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)
Calculate the model chi-squared value or the R2eff values for fixed time period data.

str constraint_algorithm(self)
Return the 'Log barrier' optimisation constraint algorithm.

list of floats create_mc_data(self, data_id)
Create the Monte Carlo peak intensity data.

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.

bool eliminate(self, name, value, args, sim=None, model_info=None)
Relaxation dispersion 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 relaxation dispersion curve fitting 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)
Relaxation dispersion curve fitting function.

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

tuple of list of SpinContainer instances and list of str model_loop(self)
Loop over the spin groupings for one model applied to multiple spins.

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.

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.

list of float return_data(self, data_id=None)
Return the peak intensity data structure.

list of float return_error(self, data_id=None)
Return the standard deviation data structure.

list of float return_error_red_chi2(self, data_id=None)
Return the standard deviation data structure, where standard deviation is from the overall gauss distribution described by the STD_fit of the goodness of fit, where STD_fit = sqrt(chi2/(N-p))

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, 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 spin specific parameter values.

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

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

Inherited from api_base.API_base: back_calc_ri, bmrb_read, covariance_matrix, data_init, data_names, data_type, default_value, get_model_container, has_errors, is_spin_param, model_type, molmol_macro, num_instances, pymol_macro, return_conversion_factor, return_data_desc, return_grace_string, return_grace_units, return_units, set_update, sim_return_chi2, skip_function

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 = Relax_disp()
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__

base_data_loop(self)

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

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)

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.
• 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) - The MC simulation index (unused).

Overrides: api_base.API_base.calculate

constraint_algorithm(self)

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)

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, 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 (list of SpinContainer instances, list of str) - The list of spins and spin IDs per cluster originating from model_loop().

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.

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 (list of SpinContainer instances, list of str) - The list of spins and spin IDs per cluster originating from model_loop().
• 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, args, sim=None, model_info=None)

Relaxation dispersion 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 (list of SpinContainer instances, list of str) - The list of spins and spin IDs per cluster originating from model_loop().

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 (list of SpinContainer instances, list of str) - The list of spins and spin IDs per cluster originating from model_loop().

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 (list of SpinContainer instances, list of str) - The list of spins and spin IDs per cluster originating from model_loop().
• 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 relaxation dispersion curve fitting grid search function.

Parameters:

• lower (list of list 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 list 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 list 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 (None) - The spin identification string (unused).

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)

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_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 list 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 list 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 list 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 (list of SpinContainer instances, list of str) - The list of spins and spin IDs per cluster originating from model_loop().

Returns: str

The model description.

Overrides: api_base.API_base.model_desc

model_loop(self)

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

Returns: tuple of list of SpinContainer instances and list of str

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)

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 (list of SpinContainer instances, list of str) - The list of spins and spin IDs per cluster originating 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).

Overrides: api_base.API_base.model_statistics

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 (list of SpinContainer instances, list of str) - The list of spins and spin IDs per cluster originating from model_loop().

Overrides: api_base.API_base.print_model_title

return_data(self, data_id=None)

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)

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

Return the standard deviation data structure, where standard deviation is from the overall gauss distribution described by the STD_fit of the goodness of fit, where STD_fit = sqrt(chi2/(N-p))

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_red_chi2

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

Overrides: api_base.API_base.return_value

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 (list of SpinContainer instances, list of str) - The list of spins and spin IDs per cluster originating from model_loop().

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 spin specific 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.
• 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 the simulation selection flag.

Parameters:

• select_sim (bool) - The selection flag for the simulations.
• model_info (list of SpinContainer instances, list of str) - The list of spins and spin IDs per cluster originating from model_loop().

Overrides: api_base.API_base.set_selected_sim

sim_init_values(self)

Initialise the Monte Carlo parameter values.

Overrides: api_base.API_base.sim_init_values

sim_pack_data(self, data_id, sim_data)

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, 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 (list of SpinContainer instances, list of str) - The list of spins and spin IDs per cluster originating from model_loop().

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.

Parameters:

• model_info (list of SpinContainer instances, list of str) - 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