Package specific_fns :: Module model_free :: Class Model_free
[hide private]
[frames] | no frames]

Class Model_free

source code


Instance Methods [hide private]
 
__init__(self, relax)
Class containing functions specific to model-free analysis.
source code
 
are_mf_params_set(self, index=None)
Function for testing if the model-free parameter values are set.
source code
 
assemble_param_names(self, index=None)
Function for assembling various pieces of data into a Numeric parameter array.
source code
 
assemble_param_vector(self, index=None, sim_index=None, param_set=None)
Function for assembling various pieces of data into a Numeric parameter array.
source code
 
assemble_scaling_matrix(self, index=None, scaling=1)
Function for creating the scaling matrix.
source code
 
back_calc(self, run=None, index=None, ri_label=None, frq_label=None, frq=None)
Back-calculation of relaxation data from the model-free parameter values.
source code
 
calculate(self, run=None, res_num=None, print_flag=1, sim_index=None)
Calculation of the model-free chi-squared value.
source code
 
copy(self, run1=None, run2=None, sim=None)
Function for copying all model-free data from run1 to run2.
source code
 
create_mc_data(self, run, i)
Function for creating the Monte Carlo Ri data.
source code
 
create_model(self, run=None, model=None, equation=None, params=None, res_num=None)
Function to create a model-free model.
source code
 
data_init(self, data)
Function for initialising the data structures.
source code
 
data_names(self, set='all')
Function for returning a list of names of data structures.
source code
 
default_value(self, param)
Model-free default values ~~~~~~~~~~~~~~~~~~~~~~~~~
source code
 
delete(self, run)
Function for deleting all model-free data.
source code
 
determine_param_set_type(self, run=None)
Determine the type of parameter set.
source code
 
disassemble_param_vector(self, index=None, sim_index=None)
Function for disassembling the parameter vector.
source code
 
duplicate_data(self, new_run=None, old_run=None, instance=None)
Function for duplicating data.
source code
 
eliminate(self, name, value, run, i, args)
Local tm model elimination rule ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
source code
 
get_param_names(self, run, i)
Function for returning a vector of parameter names.
source code
 
get_param_values(self, run, i, sim_index=None)
Function for returning a vector of parameter values.
source code
 
grid_search(self, run, lower, upper, inc, constraints, print_flag, sim_index=None)
The grid search function.
source code
 
grid_search_setup(self, index=None)
The grid search setup function.
source code
 
linear_constraints(self, index=None)
Function for setting up the model-free linear constraint matrices A and b.
source code
 
map_bounds(self, run, param)
The function for creating bounds for the mapping function.
source code
 
minimise(self, run=None, min_algor=None, min_options=None, func_tol=None, grad_tol=None, max_iterations=None, constraints=0, scaling=1, print_flag=0, sim_index=None)
Model-free minimisation.
source code
 
model_setup(self, run=None, model=None, equation=None, params=None, res_num=None)
Function for updating various data structures depending on the model selected.
source code
 
model_statistics(self, run=None, instance=None, min_instances=None, num_instances=None)
Function for returning k, n, and chi2.
source code
 
num_instances(self, run=None)
Function for returning the number of instances.
source code
 
read_columnar_col_numbers(self, header)
Function for sorting the column numbers from the columnar formatted results file.
source code
 
read_columnar_diff_tensor(self)
Function for setting up the diffusion tensor from the columnar formatted results file.
source code
 
read_columnar_find_index(self)
Function for generating the sequence and or returning the residue index.
source code
 
read_columnar_model_free_data(self)
Function for reading the model-free data.
source code
 
read_columnar_param_set(self)
Function for reading the parameter set.
source code
 
read_columnar_pdb(self, print_flag=1)
Function for reading the PDB file.
source code
 
read_columnar_relax_data(self)
Function for reading the relaxation data.
source code
 
read_columnar_results(self, run, file_data, print_flag=1)
Function for reading the results file.
source code
 
read_columnar_sequence(self)
Function for generating the sequence.
source code
 
read_columnar_xh_vect(self)
Function for reading the XH unit vectors.
source code
 
remove_tm(self, run, res_num)
Function for removing the local tm parameter from the model-free parameters.
source code
 
return_conversion_factor(self, param)
Function for returning the factor of conversion between different parameter units.
source code
 
return_data_name(self, name)
Model-free data type string matching patterns ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
source code
 
return_grace_string(self, param)
Function for returning the Grace string representing the parameter for axis labelling.
source code
 
return_units(self, param)
Function for returning a string representing the parameters units.
source code
 
return_value(self, run, i, param, sim=None)
Function for returning the value and error corresponding to 'param'.
source code
 
select_model(self, run=None, model=None, res_num=None)
Function for the selection of a preset model-free model.
source code
 
set(self, run=None, value=None, error=None, param=None, scaling=1.0, index=None)
Model-free set details ~~~~~~~~~~~~~~~~~~~~~~
source code
 
set_error(self, run, instance, index, error)
Function for setting parameter errors.
source code
 
sim_init_values(self, run)
Function for initialising Monte Carlo parameter values.
source code
 
sim_return_chi2(self, run, instance)
Function for returning the array of simulation chi-squared values.
source code
 
sim_return_param(self, run, instance, index)
Function for returning the array of simulation parameter values.
source code
 
sim_return_selected(self, run, instance)
Function for returning the array of selected simulation flags.
source code
 
sim_set_selected(self, run, instance, select_sim)
Function for returning the array of selected simulation flags.
source code
 
skip_function(self, run=None, instance=None, min_instances=None, num_instances=None)
Function for skiping certain data.
source code
 
unselect(self, run, i, sim_index=None)
Function for unselecting models or simulations.
source code
 
write_columnar_line(self, file=None, num=None, name=None, select=None, select_sim=None, data_set=None, nucleus=None, model=None, equation=None, params=None, param_set=None, s2=None, s2f=None, s2s=None, local_tm=None, te=None, tf=None, ts=None, rex=None, r=None, csa=None, chi2=None, i=None, f=None, g=None, h=None, warn=None, diff_type=None, diff_params=None, pdb=None, pdb_model=None, pdb_heteronuc=None, pdb_proton=None, xh_vect=None, ri_labels=None, remap_table=None, frq_labels=None, frq=None, ri=None, ri_error=None)
Function for printing a single line of the columnar formatted results.
source code
 
write_columnar_results(self, file, run)
Function for printing the results into a file.
source code

Inherited from base_class.Common_functions: return_data, return_error, sim_pack_data

Method Details [hide private]

__init__(self, relax)
(Constructor)

source code 

Class containing functions specific to model-free analysis.

Overrides: base_class.Common_functions.__init__

data_names(self, set='all')

source code 
Function for returning a list of names of data structures.

Description
~~~~~~~~~~~

The names are as follows:

model: The model-free model name.

equation:  The model-free equation type.

params:  An array of the model-free parameter names associated with the model.

s2:  S2.

s2f:  S2f.

s2s:  S2s.

tm:  tm.

te:  te.

tf:  tf.

ts:  ts.

rex:  Rex.

r:  Bond length.

csa:  CSA value.

chi2:  Chi-squared value.

iter:  Iterations.

f_count:  Function count.

g_count:  Gradient count.

h_count:  Hessian count.

warning:  Minimisation warning.

default_value(self, param)

source code 

Model-free default values
~~~~~~~~~~~~~~~~~~~~~~~~~

_______________________________________________________________________________________
|                                       |                    |                        |
| Data type                             | Object name        | Value                  |
|_______________________________________|____________________|________________________|
|                                       |                    |                        |
| Local tm                              | 'tm'               | 10 * 1e-9              |
|                                       |                    |                        |
| Order parameters S2, S2f, and S2s     | 's2', 's2f', 's2s' | 0.8                    |
|                                       |                    |                        |
| Correlation time te                   | 'te'               | 100 * 1e-12            |
|                                       |                    |                        |
| Correlation time tf                   | 'tf'               | 10 * 1e-12             |
|                                       |                    |                        |
| Correlation time ts                   | 'ts'               | 1000 * 1e-12           |
|                                       |                    |                        |
| Chemical exchange relaxation          | 'rex'              | 0.0                    |
|                                       |                    |                        |
| Bond length                           | 'r'                | 1.02 * 1e-10           |
|                                       |                    |                        |
| CSA                                   | 'csa'              | -170 * 1e-6            |
|_______________________________________|____________________|________________________|

eliminate(self, name, value, run, i, args)

source code 

Local tm model elimination rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The local tm, in some cases, may exceed the value expected for a global correlation time.
Generally the tm value will be stuck at the upper limit defined for the parameter.  These
models are eliminated using the rule:

    tm >= c

The default value of c is 50 ns, although this can be overridden by supplying the value (in
seconds) as the first element of the args tuple.


Internal correlation times {te, tf, ts} model elimination rules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

These parameters may experience the same problem as the local tm in that the model fails and
the parameter value is stuck at the upper limit.  These parameters are constrained using the
formula (te, tf, ts <= 2tm).  These failed models are eliminated using the rule:

    te, tf, ts >= c . tm

The default value of c is 1.5.  Because of round-off errors and the constraint algorithm,
setting c to 2 will result in no models being eliminated as the minimised parameters will
always be less than 2tm.  The value can be changed by supplying the value as the second
element of the tuple.


Arguments
~~~~~~~~~

The 'args' argument must be a tuple of length 2, the elements of which must be numbers.  For
example, to eliminate models which have a local tm value greater than 25 ns and models with
internal correlation times greater than 1.5 times tm, set 'args' to (25 * 1e-9, 1.5).

linear_constraints(self, index=None)

source code 
Function for setting up the model-free linear constraint matrices A and b.

Standard notation
~~~~~~~~~~~~~~~~~

The order parameter constraints are:

    0 <= S2 <= 1
    0 <= S2f <= 1
    0 <= S2s <= 1

By substituting the formula S2 = S2f.S2s into the above inequalities, the additional two
inequalities can be derived:

    S2 <= S2f
    S2 <= S2s

Correlation time constraints are:

    te >= 0
    tf >= 0
    ts >= 0

    tf <= ts

    te, tf, ts <= 2 * tm

Additional constraints used include:

    Rex >= 0
    0.9e-10 <= r <= 2e-10
    -300e-6 <= CSA <= 0


Rearranged notation
~~~~~~~~~~~~~~~~~~~
The above ineqality constraints can be rearranged into:

    S2 >= 0
    -S2 >= -1
    S2f >= 0
    -S2f >= -1
    S2s >= 0
    -S2s >= -1
    S2f - S2 >= 0
    S2s - S2 >= 0
    te >= 0
    tf >= 0
    ts >= 0
    ts - tf >= 0
    Rex >= 0
    r >= 0.9e-10
    -r >= -2e-10
    CSA >= -300e-6
    -CSA >= 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  0  0  0  0  0  0 |                  |    0    |
    |                           |                  |         |
    |-1  0  0  0  0  0  0  0  0 |                  |   -1    |
    |                           |                  |         |
    | 0  1  0  0  0  0  0  0  0 |                  |    0    |
    |                           |                  |         |
    | 0 -1  0  0  0  0  0  0  0 |                  |   -1    |
    |                           |                  |         |
    | 0  0  1  0  0  0  0  0  0 |     | S2  |      |    0    |
    |                           |     |     |      |         |
    | 0  0 -1  0  0  0  0  0  0 |     | S2f |      |   -1    |
    |                           |     |     |      |         |
    |-1  1  0  0  0  0  0  0  0 |     | S2s |      |    0    |
    |                           |     |     |      |         |
    |-1  0  1  0  0  0  0  0  0 |     | te  |      |    0    |
    |                           |     |     |      |         |
    | 0  0  0  1  0  0  0  0  0 |  .  | tf  |  >=  |    0    |
    |                           |     |     |      |         |
    | 0  0  0  0  1  0  0  0  0 |     | ts  |      |    0    |
    |                           |     |     |      |         |
    | 0  0  0  0  0  1  0  0  0 |     | Rex |      |    0    |
    |                           |     |     |      |         |
    | 0  0  0  0 -1  1  0  0  0 |     |  r  |      |    0    |
    |                           |     |     |      |         |
    | 0  0  0  0  0  0  1  0  0 |     | CSA |      |    0    |
    |                           |                  |         |
    | 0  0  0  0  0  0  0  1  0 |                  | 0.9e-10 |
    |                           |                  |         |
    | 0  0  0  0  0  0  0 -1  0 |                  | -2e-10  |
    |                           |                  |         |
    | 0  0  0  0  0  0  0  0  1 |                  | -300e-6 |
    |                           |                  |         |
    | 0  0  0  0  0  0  0  0 -1 |                  |    0    |

minimise(self, run=None, min_algor=None, min_options=None, func_tol=None, grad_tol=None, max_iterations=None, constraints=0, scaling=1, print_flag=0, sim_index=None)

source code 
Model-free minimisation.

Three types of parameter sets exist for which minimisation is different.  These are:
    'mf' - Model-free parameters for single residues.
    'diff' - Diffusion tensor parameters.
    'all' - All model-free and all diffusion tensor parameters.

model_statistics(self, run=None, instance=None, min_instances=None, num_instances=None)

source code 

Function for returning k, n, and chi2.

k - number of parameters. n - number of data points. chi2 - the chi-squared value.

return_conversion_factor(self, param)

source code 

Function for returning the factor of conversion between different parameter units.

For example, the internal representation of te is in seconds, whereas the external representation is in picoseconds, therefore this function will return 1e-12 for te.

return_data_name(self, name)

source code 

Model-free data type string matching patterns
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

____________________________________________________________________________________________
|                        |              |                                                  |
| Data type              | Object name  | Patterns                                         |
|________________________|______________|__________________________________________________|
|                        |              |                                                  |
| Local tm               | 'tm'         | '^tm$'                                           |
|                        |              |                                                  |
| Order parameter S2     | 's2'         | '^[Ss]2$'                                        |
|                        |              |                                                  |
| Order parameter S2f    | 's2f'        | '^[Ss]2f$'                                       |
|                        |              |                                                  |
| Order parameter S2s    | 's2s'        | '^[Ss]2s$'                                       |
|                        |              |                                                  |
| Correlation time te    | 'te'         | '^te$'                                           |
|                        |              |                                                  |
| Correlation time tf    | 'tf'         | '^tf$'                                           |
|                        |              |                                                  |
| Correlation time ts    | 'ts'         | '^ts$'                                           |
|                        |              |                                                  |
| Chemical exchange      | 'rex'        | '^[Rr]ex$' or '[Cc]emical[ -_][Ee]xchange'       |
|                        |              |                                                  |
| Bond length            | 'r'          | '^r$' or '[Bb]ond[ -_][Ll]ength'                 |
|                        |              |                                                  |
| CSA                    | 'csa'        | '^[Cc][Ss][Aa]$'                                 |
|________________________|______________|__________________________________________________|

return_units(self, param)

source code 

Function for returning a string representing the parameters units.

For example, the internal representation of te is in seconds, whereas the external representation is in picoseconds, therefore this function will return the string 'picoseconds' for te.

return_value(self, run, i, param, sim=None)

source code 

Function for returning the value and error corresponding to 'param'.

If sim is set to an integer, return the value of the simulation and None.

set(self, run=None, value=None, error=None, param=None, scaling=1.0, index=None)

source code 

Model-free set details
~~~~~~~~~~~~~~~~~~~~~~

Setting a parameter value may have no effect depending on which model-free model is chosen,
for example if S2f values and S2s values are set but the run corresponds to model-free model
'm4' then, because these data values are not parameters of the model, they will have no
effect.

Note that the Rex values are scaled quadratically with field strength and should be supplied
as a field strength independent value.  Use the following formula to get the correct value:

    value = Rex / (2.0 * pi * frequency) ** 2

where:
    Rex is the chemical exchange value for the current frequency.
    pi is in the namespace of relax, ie just type 'pi'.
    frequency is the proton frequency corresponding to the data.