Class Frame_order

Class containing the specific methods of the Frame Order theories.

Instance Methods

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

numpy rank-1 array, numpy rank-1 array _assemble_limit_arrays(self)
Assemble and return the limit vectors.

numpy rank-1 array _assemble_param_vector(self, sim_index=None)
Assemble and return the parameter vector.

numpy array _back_calc(self)
Back-calculation of the reduced alignment tensor.

_cone_pdb(self, size=30.0, file=None, dir=None, inc=40, force=False)
Create a PDB file containing a geometric object representing the Frame Order cone models.

_domain_to_pdb(self, domain=None, pdb=None)
Match domains to PDB files.

list of float _grid_row(self, incs, lower, upper, dist_type=None, end_point=True)
Set up a row of the grid search for a given parameter.

tuple of 3 numpy nx5D, rank-1 arrays _minimise_setup_tensors(self, sim_index=None)
Set up the data structures for optimisation using alignment tensors as base data sets.

_pivot(self, pivot=None)
Set the pivot point for the 2 body motion.

_ref_domain(self, ref=None)
Set the reference domain for the frame order, multi-domain models.

_select_model(self, model=None)
Select the Frame Order model.

_store_bc_tensors(self, target_fn)
Store the back-calculated reduced alignment tensors.

(int, AlignTensorData instance) _tensor_loop(self, red=False)
Generator method for looping over the full or reduced tensors.

_update_model(self)
Update the model parameters as necessary.

_unpack_opt_results(self, results, sim_index=None)
Unpack and store the Frame Order optimisation results.

None base_data_loop(self)
Generator method for looping nothing.

calculate(self, spin_id=None, verbosity=1, sim_index=None)
Calculate the chi-squared value for the current parameter values.

list of floats create_mc_data(self, data_id=None)
Create the Monte Carlo data by back calculating the reduced tensor data.

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

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, constraints=False, verbosity=0, sim_index=None)
Perform a grid search.

bool is_spin_param(self, name)
State that the parameter is not spin specific.

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=True, verbosity=0, sim_index=None, lower=None, upper=None, inc=None)
Minimisation function.

SpinContainer instance model_loop(self)
Dummy generator method.

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.

list of float return_error(self, data_id)
Return the alignment tensor error structure.

str return_units(self, param)
Return a string representing the parameters units.

set_error(self, model_info, index, error)
Set the parameter errors.

set_selected_sim(self, model_info, select_sim)
Set the simulation selection flag for the spin.

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, model_info, index)
Return the array of simulation parameter values.

list of int sim_return_selected(self, model_info)
Return the array of selected simulation flags for the spin.

Inherited from api_base.API_base: back_calc_ri, bmrb_read, bmrb_write, data_init, data_type, default_value, deselect, duplicate_data, eliminate, has_errors, model_desc, model_type, molmol_macro, num_instances, overfit_deselect, pymol_macro, read_columnar_results, return_conversion_factor, return_data, return_data_desc, return_data_name, return_grace_string, return_value, set_param_values, set_update, sim_return_chi2, 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

Inherited from api_base.API_base: GLOBAL_PARAMS, SPIN_PARAMS, default_value_doc, eliminate_doc, return_data_name_doc, set_doc

Method Details

_assemble_limit_arrays(self)

Assemble and return the limit vectors.

Returns: numpy rank-1 array, numpy rank-1 array

The lower and upper limit vectors.

_assemble_param_vector(self, sim_index=None)

Assemble and return the parameter vector.

Parameters:

• sim_index (int) - The Monte Carlo simulation index.

Returns: numpy rank-1 array

The parameter vector.

_back_calc(self)

Back-calculation of the reduced alignment tensor.

Returns: numpy array

The reduced alignment tensors.

_cone_pdb(self, size=30.0, file=None, dir=None, inc=40, force=False)

Create a PDB file containing a geometric object representing the Frame Order cone models.

Parameters:

• size (float) - The size of the geometric object in Angstroms.
• inc (int) - The number of increments for the filling of the cone objects.
• file (str) - The name of the PDB file to create.
• dir (str) - The name of the directory to place the PDB file into.
• force (bool) - Flag which if set to True will cause any pre-existing file to be overwritten.

_domain_to_pdb(self, domain=None, pdb=None)

Match domains to PDB files.

Parameters:

• domain (str) - The domain to associate the PDB file to.
• pdb (str) - The PDB file to associate the domain to.

_grid_row(self, incs, lower, upper, dist_type=None, end_point=True)

Set up a row of the grid search for a given parameter.

Parameters:

• incs (int) - The number of increments.
• lower (float) - The lower bounds.
• upper (float) - The upper bounds.
• dist_type (None or str) - The spacing or distribution type between grid nodes. If None, then a linear grid row is returned. If 'acos', then an inverse cos distribution of points is returned (e.g. for uniform sampling in angular space).
• end_point (bool) - A flag which if False will cause the end point to be removed.

Returns: list of float

The row of the grid.

_minimise_setup_tensors(self, sim_index=None)

Set up the data structures for optimisation using alignment tensors as base data sets.

Parameters:

• sim_index (None or int) - The simulation index. This should be None if normal optimisation is desired.

Returns: tuple of 3 numpy nx5D, rank-1 arrays

The assembled data structures for using alignment tensors as the base data for optimisation. These include:

• full_tensors, the full tensors as concatenated arrays.
• red_tensors, the reduced tensors as concatenated arrays.
• red_err, the reduced tensor errors as concatenated arrays.

_pivot(self, pivot=None)

Set the pivot point for the 2 body motion.

Parameters:

• pivot (list of num) - The pivot point of the two bodies (domains, etc.) in the structural coordinate system.

_ref_domain(self, ref=None)

Set the reference domain for the frame order, multi-domain models.

Parameters:

• ref (str) - The reference domain.

_select_model(self, model=None)

Select the Frame Order model.

Parameters:

• model (str) - The Frame Order model. This can be one of 'pseudo-ellipse', 'pseudo-ellipse, torsionless', 'pseudo-ellipse, free rotor', 'iso cone', 'iso cone, torsionless', 'iso cone, free rotor', 'line', 'line, torsionless', 'line, free rotor', 'rotor', 'rigid', 'free rotor'.

_store_bc_tensors(self, target_fn)

Store the back-calculated reduced alignment tensors.

Parameters:

• target_fn (class instance) - The frame-order target function class.

_tensor_loop(self, red=False)

Generator method for looping over the full or reduced tensors.

Parameters:

• red (bool) - A flag which if True causes the reduced tensors to be returned, and if False the full tensors are returned.

Returns: (int, AlignTensorData instance)

The tensor index and the tensor.

_unpack_opt_results(self, results, sim_index=None)

Unpack and store the Frame Order optimisation results.

Parameters:

• results (tuple) - The results tuple returned by the minfx generic_minimise() function.
• sim_index (None or int) - The index of the simulation to optimise. This should be None for normal optimisation.

base_data_loop(self)

Generator method for looping nothing.

The loop essentially consists of a single element.

Returns: None

Nothing.

Overrides: api_base.API_base.base_data_loop

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

Calculate the chi-squared value for the current parameter values.

Parameters:

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

Overrides: api_base.API_base.calculate

create_mc_data(self, data_id=None)

Create the Monte Carlo data by back calculating the reduced tensor data.

Parameters:

• data_id (None) - Unused.

Returns: list of floats

The Monte Carlo simulation data.

Overrides: api_base.API_base.create_mc_data

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

Function for returning a list of names of data structures.

Description

The names are as follows:

• 'params', an array of the parameter names associated with the model.
• 'chi2', chi-squared value.
• 'iter', iterations.
• 'f_count', function count.
• 'g_count', gradient count.
• 'h_count', hessian count.
• 'warning', minimisation warning.

The isotropic cone specific model parameters are:

• 'axis_theta', the cone axis polar angle (for the isotropic cone model).
• 'axis_phi', the cone axis azimuthal angle (for the isotropic cone model).
• 'cone_s1', the isotropic cone order parameter.

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 the Frame Order 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

get_param_names(self, model_info=None)

Return a vector of parameter names.

Parameters:

• model_info (int) - The model index from model_info().

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 (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=False, verbosity=0, sim_index=None)

Perform a grid search.

Parameters:

• lower (list of float) - The lower bounds of the grid search which must be equal to the number of parameters in the model.
• upper (list of float) - The upper bounds of the grid search which must be equal to the number of parameters in the model.
• inc (int or list 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 (None or int) - The Monte Carlo simulation index.

Overrides: api_base.API_base.grid_search

is_spin_param(self, name)

State that the parameter is not spin specific.

Parameters:

• name (str) - The name of the parameter.

Returns: bool

False.

Overrides: api_base.API_base.is_spin_param

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

Minimisation 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) - A flag specifying 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_loop(self)

Dummy generator method.

In this case only a single model per spin system is assumed. Hence the yielded data is the spin container object.

Returns: SpinContainer instance

Information about the model which for this analysis is the spin container.

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 (None) - Unused.
• spin_id (None) - The spin identification string (unused).
• global_stats (None) - Unused.

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

return_error(self, data_id)

Return the alignment tensor error structure.

Parameters:

• data_id (None) - The information yielded by the base_data_loop() generator method.

Returns: list of float

The array of tensor error values.

Overrides: api_base.API_base.return_error

return_units(self, param)

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.

Overrides: api_base.API_base.return_units

set_error(self, model_info, index, error)

Set the parameter errors.

Parameters:

• model_info (None) - The model information originating from model_loop() (unused).
• 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)

Set the simulation selection flag for the spin.

Parameters:

• model_info (None) - The model information originating from model_loop() (unused).
• select_sim (bool) - The selection flag for the simulations.

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

sim_return_param(self, model_info, index)

Return the array of simulation parameter values.

Parameters:

• model_info (None) - The model information originating from model_loop() (unused).
• 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)

Return the array of selected simulation flags for the spin.

Parameters:

• model_info (None) - The model information originating from model_loop() (unused).

Returns: list of int

The array of selected simulation flags.

Overrides: api_base.API_base.sim_return_selected