Package specific_fns :: Module relax_fit :: Class Relax_fit
[hide private]
[frames] | no frames]

Class Relax_fit

source code


Class containing functions for relaxation curve fitting.

Instance Methods [hide private]
 
__init__(self)
Initialise the class by placing API_common methods into the API.
source code
numpy array
_assemble_param_vector(self, spin=None, sim_index=None)
Assemble the exponential curve parameter vector (as a numpy array).
source code
numpy diagonal matrix
_assemble_scaling_matrix(self, spin=None, scaling=True)
Create and return the scaling matrix.
source code
float
_back_calc(self, spin=None, relax_time_id=None)
Back-calculation of peak intensity for the given relaxation time.
source code
 
_disassemble_param_vector(self, param_vector=None, spin=None, sim_index=None)
Disassemble the parameter vector.
source code
float
_func(self, params)
Wrapper function for the C module, for converting numpy arrays.
source code
 
_dfunc(self, params)
Wrapper function for the C module, for converting numpy arrays.
source code
 
_d2func(self, params)
Wrapper function for the C module, for converting numpy arrays.
source code
(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.
source code
 
_linear_constraints(self, spin=None, scaling_matrix=None)
Set up the relaxation curve fitting linear constraint matrices A and b.
source code
 
_model_setup(self, model, params)
Update various model specific data structures.
source code
 
_relax_time(self, time=0.0, spectrum_id=None)
Set the relaxation time period associated with a given spectrum.
source code
 
_select_model(self, model='exp')
Function for selecting the model of the exponential curve.
source code
list of floats
create_mc_data(self, data_id=None)
Create the Monte Carlo peak intensity data.
source code
 
data_init(self, data_cont, sim=False)
Initialise the spin specific data structures.
source code
list of str
data_names(self, set='all', error_names=False, sim_names=False)
Return a list of names of data structures.
source code
 
grid_search(self, lower=None, upper=None, inc=None, constraints=True, verbosity=1, sim_index=None)
The exponential curve fitting grid search method.
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 curve fitting minimisation method.
source code
 
overfit_deselect(self)
Deselect spins which have insufficient data to support minimisation.
source code
list of float
return_data(self, spin)
Function for returning the peak intensity data structure.
source code
list of float
return_error(self, data_id)
Return the standard deviation data structure.
source code
None
return_units(self, param)
Dummy method which returns None as the stats have no units.
source code
 
sim_pack_data(self, data_id, sim_data)
Pack the Monte Carlo simulation data.
source code

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

Class Variables [hide private]
  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 [hide private]

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

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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

The currently does nothing.

_d2func(self, params)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

Deselect spins which have insufficient data to support minimisation.

Overrides: api_base.API_base.overfit_deselect

return_data(self, spin)

source code 

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)

source code 

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)

source code 

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)

source code 

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 [hide private]

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