Class Relax_fit

Class containing functions for relaxation curve fitting.

Instance Methods

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

numpy array _assemble_param_vector(self, spin=None, sim_index=None)
Assemble the exponential curve parameter vector (as a numpy array).

numpy diagonal matrix _assemble_scaling_matrix(self, spin=None, scaling=True)
Create and return the scaling matrix.

float _back_calc(self, spin=None, relax_time_id=None)
Back-calculation of peak intensity for the given relaxation time.

_disassemble_param_vector(self, param_vector=None, spin=None, sim_index=None)
Disassemble the parameter vector.

float _func(self, params)
Wrapper function for the C module, for converting numpy arrays.

_dfunc(self, params)
Wrapper function for the C module, for converting numpy arrays.

_d2func(self, params)
Wrapper function for the C module, for converting numpy arrays.

(int, list of lists [int, float, float]) _grid_search_setup(self, spin=None, param_vector=None, lower=None, upper=None, inc=None, scaling_matrix=None)
The grid search setup function.

_linear_constraints(self, spin=None, scaling_matrix=None)
Set up the relaxation curve fitting linear constraint matrices A and b.

_model_setup(self, model, params)
Update various model specific data structures.

_relax_time(self, time=0.0, spectrum_id=None)
Set the relaxation time period associated with a given spectrum.

_select_model(self, model='exp')
Function for selecting the model of the exponential curve.

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

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

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

grid_search(self, lower=None, upper=None, inc=None, constraints=True, verbosity=1, sim_index=None)
The exponential curve fitting grid search method.

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 curve fitting minimisation method.

overfit_deselect(self)
Deselect spins which have insufficient data to support minimisation.

list of float return_data(self, spin)
Function for returning the peak intensity data structure.

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

None return_units(self, param)
Dummy method which returns None as the stats have no units.

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

Inherited from api_base.API_base: back_calc_ri, base_data_loop, bmrb_read, bmrb_write, calculate, data_type, default_value, deselect, duplicate_data, eliminate, get_param_names, get_param_values, has_errors, is_spin_param, map_bounds, model_desc, model_loop, model_statistics, model_type, molmol_macro, num_instances, pymol_macro, read_columnar_results, return_conversion_factor, return_data_desc, return_data_name, return_grace_string, return_value, set_error, set_param_values, set_selected_sim, set_update, sim_init_values, sim_return_chi2, sim_return_param, sim_return_selected, skip_function, test_grid_ops

Inherited from api_common.API_common (private): _base_data_loop_spin, _create_mc_relax_data, _data_init_dummy, _default_value_spin, _eliminate_false, _has_errors_spin, _is_spin_param_true, _model_loop_single_global, _model_loop_spin, _num_instances_spin, _overfit_deselect_dummy, _return_conversion_factor_spin, _return_data_desc_spin, _return_data_name, _return_data_name_global, _return_data_name_spin, _return_data_relax_data, _return_error_relax_data, _return_grace_string_spin, _return_no_conversion_factor, _return_units_global, _return_units_spin, _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, _test_grid_ops_general

Class Variables

default_value_doc = ['Relaxation curve fitting default values'...

return_data_name_doc = ['Relaxation curve fitting data type st...

set_doc = ['Relaxation curve fitting set details', '\n ...

Inherited from api_base.API_base: GLOBAL_PARAMS, SPIN_PARAMS, eliminate_doc

Method Details

_assemble_param_vector(self, spin=None, sim_index=None)

Assemble the exponential curve parameter vector (as a numpy array).

Parameters:

• spin (SpinContainer instance) - The spin data container.
• sim_index (int) - The optional MC simulation index.

Returns: numpy array

An array of the parameter values of the exponential model.

_assemble_scaling_matrix(self, spin=None, scaling=True)

Create and return the scaling matrix.

Parameters:

• spin (SpinContainer instance) - The spin data container.
• scaling (bool) - A flag which if false will cause the identity matrix to be returned.

Returns: numpy diagonal matrix

The diagonal and square scaling matrix.

_back_calc(self, spin=None, relax_time_id=None)

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

Parameters:

• spin (SpinContainer instance) - The spin container.
• relax_time_id (str) - The ID string for the desired relaxation time.

Returns: float

The peak intensity for the desired relaxation time.

_disassemble_param_vector(self, param_vector=None, spin=None, sim_index=None)

Disassemble the parameter vector.

Parameters:

• param_vector (numpy array) - The parameter vector.
• spin (SpinContainer instance) - The spin data container.
• sim_index (int) - The optional MC simulation index.

_func(self, params)

Wrapper function for the C module, for converting numpy arrays.

Parameters:

• params (numpy array) - The parameter array from the minimisation code.

Returns: float

The function value generated by the C module.

_dfunc(self, params)

Wrapper function for the C module, for converting numpy arrays.

The currently does nothing.

_d2func(self, params)

Wrapper function for the C module, for converting numpy arrays.

The currently does nothing.

_grid_search_setup(self, spin=None, param_vector=None, lower=None, upper=None, inc=None, scaling_matrix=None)

The grid search setup function.

Parameters:

• spin (SpinContainer instance) - The spin data container.
• param_vector (numpy array) - The parameter vector.
• 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.
• scaling_matrix (numpy diagonal matrix) - The scaling matrix.

Returns: (int, list of lists [int, float, float])

A tuple of the grid size and the minimisation options. For the minimisation options, the first dimension corresponds to the model parameter. The second dimension is a list of the number of increments, the lower bound, and upper bound.

_linear_constraints(self, spin=None, scaling_matrix=None)

Set up the relaxation curve fitting linear constraint matrices A and b.

Standard notation

The relaxation rate constraints are:

   Rx >= 0

The intensity constraints are:

   I0 >= 0
   Iinf >= 0

Matrix notation

In the notation A.x >= b, where A is an matrix of coefficients, x is an array of parameter values, and b is a vector of scalars, these inequality constraints are:

   | 1  0  0 |     |  Rx  |      |    0    |
   |         |     |      |      |         |
   | 1  0  0 |  .  |  I0  |  >=  |    0    |
   |         |     |      |      |         |
   | 1  0  0 |     | Iinf |      |    0    |

Parameters:

• spin (SpinContainer instance) - The spin data container.
• scaling_matrix (numpy diagonal matrix) - The diagonal, square scaling matrix.

_model_setup(self, model, params)

Update various model specific data structures.

Parameters:

• model (str) - The exponential curve type.
• params (list of str) - A list consisting of the model parameters.

_relax_time(self, time=0.0, spectrum_id=None)

Set the relaxation time period associated with a given spectrum.

Parameters:

• time (float) - The time, in seconds, of the relaxation period.
• spectrum_id (str) - The spectrum identification string.

_select_model(self, model='exp')

Function for selecting the model of the exponential curve.

Parameters:

• model (str) - The exponential curve type. Can be one of 'exp' or 'inv'.

create_mc_data(self, data_id=None)

Create the Monte Carlo peak intensity 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_cont, sim=False)

Initialise the spin specific data structures.

Parameters:

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

Overrides: api_base.API_base.data_init

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

Return a list of names of data structures.

Description

The names are as follows:

• 'params', an array of the parameter names associated with the model.
• 'rx', either the R1 or R2 relaxation rate.
• 'i0', the initial intensity.
• 'iinf', the intensity at infinity.
• 'chi2', chi-squared value.
• 'iter', iterations.
• 'f_count', function count.
• 'g_count', gradient count.
• 'h_count', hessian count.
• 'warning', minimisation warning.

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

Overrides: api_base.API_base.data_names

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

The exponential curve fitting 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.

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)

Relaxation curve fitting 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.

Overrides: api_base.API_base.minimise

overfit_deselect(self)

Deselect spins which have insufficient data to support minimisation.

Overrides: api_base.API_base.overfit_deselect

return_data(self, spin)

Function for returning the peak intensity data structure.

Parameters:

• spin (SpinContainer instance) - The spin container.

Returns: list of float

The peak intensity data structure.

Overrides: api_base.API_base.return_data

return_error(self, data_id)

Return the standard deviation data structure.

Parameters:

• data_id (str) - The spin identification string, 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_units(self, param)

Dummy method which returns None as the stats have no units.

Parameters:

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

Returns: None

Nothing.

Overrides: api_base.API_base.return_units

sim_pack_data(self, data_id, sim_data)

Pack the Monte Carlo simulation data.

Parameters:

• data_id (str) - The spin identification string, 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

Class Variable Details

default_value_doc

Value:

['Relaxation curve fitting default values',
 '''
        These values are completely arbitrary as peak heights (or volu
mes) are extremely variable and the Rx value is a compensation for bot
h the R1 and R2 values.
        ______________________________________________________________
_____
        |                        |               |                    
...

return_data_name_doc

Value:

['Relaxation curve fitting data type string matching patterns',
 '''
        ____________________________________________________________
        |                                   |                      |
        | Data type                         | Object name          |
        |___________________________________|______________________|
        |                                   |                      |
        | Relaxation rate                   | \'rx\'                 |
...

set_doc

Value:

['Relaxation curve fitting set details',
 '''
        Only three parameters can be set, the relaxation rate (Rx), th
e initial intensity (I0), and the intensity at infinity (Iinf).  Setti
ng the parameter Iinf has no effect if the chosen model is that of the
 exponential curve which decays to zero.
        ''']