Package prompt :: Module grace :: Class Grace
[hide private]
[frames] | no frames]

Class Grace

source code


Class for interfacing with Grace.

Instance Methods [hide private]
 
view(self, file=None, dir='grace', grace_exe='xmgrace')
Visualise the file within Grace.
source code
 
write(self, x_data_type='spin', y_data_type=None, spin_id=None, plot_data='value', file=None, dir='grace', force=False, norm=False)
Create a grace '.agr' file.
source code

Inherited from base_class.User_fn_class: __init__

Method Details [hide private]

view(self, file=None, dir='grace', grace_exe='xmgrace')

source code 
Visualise the file within Grace.

Keyword Arguments
~~~~~~~~~~~~~~~~~

file:  The name of the file.

dir:  The directory name.

grace_exe:  The Grace executable file.


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

This can be used to view the specified Grace '*.agr' file by opening it with the Grace program.


Examples
~~~~~~~~

To view the file 's2.agr' in the directory 'grace', type:

relax> grace.view(file='s2.agr')
relax> grace.view(file='s2.agr', dir='grace')

write(self, x_data_type='spin', y_data_type=None, spin_id=None, plot_data='value', file=None, dir='grace', force=False, norm=False)

source code 
Create a grace '.agr' file.

Keyword Arguments
~~~~~~~~~~~~~~~~~

x_data_type:  The data type for the X-axis (no regular expression is allowed).

y_data_type:  The data type for the Y-axis (no regular expression is allowed).

spin_id:  The spin identification string.

plot_data:  The data to use for the plot.

norm:  Flag for the normalisation of series type data.

file:  The name of the file.

dir:  The directory name.

force:  A flag which, if set to True, will cause the file to be overwritten.


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

This is designed to be as flexible as possible so that any combination of data can be plotted.  The
output is in the format of a Grace plot (also known as ACE/gr, Xmgr, and xmgrace) which only
supports two dimensional plots.  Three types of keyword arguments can be used to create various
types of plot.  These include the X-axis and Y-axis data types, the spin identification string, and
an argument for selecting what to plot.

The X-axis and Y-axis data type arguments should be plain strings, regular expression is not
allowed.  If the X-axis data type argument is not given, the plot will default to having the spin
sequence along the x-axis.  The two axes of the Grace plot can be absolutely any of the data types
listed in the tables below.  The only limitation, currently anyway, is that the data must belong to
the same data pipe.

The spin identification string can be used to limit which spins are used in the plot.  The default
is that all spins will be used, however, these arguments can be used to select a subset of all
spins, or a single spin for plots of Monte Carlo simulations, etc.

The property which is actually plotted can be controlled by the 'plot_data' argument.  It can be one
of the following:

    'value':  Plot values (with errors if they exist).
    'error':  Plot errors.
    'sims':   Plot the simulation values.

Normalisation is only allowed for series type data, for example the R2 exponential curves, and will
be ignored for all other data types.  If the norm flag is set to True then the y-value of the first
point of the series will be set to 1.  This normalisation is useful for highlighting errors in the
data sets.


Examples
~~~~~~~~

To write the NOE values for all spins to the Grace file 'noe.agr', type one of:

relax> grace.write('spin', 'noe', file='noe.agr')
relax> grace.write(y_data_type='noe', file='noe.agr')
relax> grace.write(x_data_type='spin', y_data_type='noe', file='noe.agr')
relax> grace.write(y_data_type='noe', file='noe.agr', force=True)


To create a Grace file of 's2' vs. 'te' for all spins, type one of:

relax> grace.write('s2', 'te', file='s2_te.agr')
relax> grace.write(x_data_type='s2', y_data_type='te', file='s2_te.agr')
relax> grace.write(x_data_type='s2', y_data_type='te', file='s2_te.agr', force=True)


To create a Grace file of the Monte Carlo simulation values of 'rex' vs. 'te' for residue
123, type one of:

relax> grace.write('rex', 'te', spin_id=':123', plot_data='sims', file='s2_te.agr')
relax> grace.write(x_data_type='rex', y_data_type='te', spin_id=':123',
                   plot_data='sims', file='s2_te.agr')


By plotting the peak intensities, the integrity of exponential relaxation curves can be
checked and anomalies searched for prior to model-free analysis or reduced spectral density
mapping.  For example the normalised average peak intensities can be plotted verses the
relaxation time periods for the relaxation curves of all residues of a protein.  The
normalisation, whereby the initial peak intensity of each residue I(0) is set to 1,
emphasises any problems.  To produce this Grace file, type:

relax> grace.write(x_data_type='relax_times', y_data_type='ave_int',
                   file='intensities_norm.agr', force=True, norm=True)


Regular expression
~~~~~~~~~~~~~~~~~~

The python function 'match', which uses regular expression, is used to determine which data type to
set values to, therefore various data_type strings can be used to select the same data type.
Patterns used for matching for specific data types are listed below.

This is a short description of python regular expression, for more information see the regular
expression syntax section of the Python Library Reference.  Some of the regular expression syntax
used in this function is:

    '[]':  A sequence or set of characters to match to a single character.  For example, '[sS]2'
WILL match both 'S2' and 's2'.

    '^':  Match the start of the string.

    '$':  Match the end of the string.  For example, '^[Ss]2$' will match 's2' but not 'S2f' or
's2s'.

    '.':  Match any character.

    'x*':  Match the character 'x' any number of times, for example 'x' will match, as will 'xxxxx'.

    '.*':  Match any sequence of characters of any length.

Importantly, do not supply a string for the data type containing regular expression.  The regular
expression is implemented so that various strings can be supplied which all match the same data
type.


Minimisation statistic data type string matching patterns
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

____________________________________________________________________________________________
|                        |              |                                                  |
| Data type              | Object name  | Patterns                                         |
|________________________|______________|__________________________________________________|
|                        |              |                                                  |
| Chi-squared statistic  | 'chi2'       | '^[Cc]hi2$' or '^[Cc]hi[-_ ][Ss]quare'           |
|                        |              |                                                  |
| Iteration count        | 'iter'       | '^[Ii]ter'                                       |
|                        |              |                                                  |
| Function call count    | 'f_count'    | '^[Ff].*[ -_][Cc]ount'                           |
|                        |              |                                                  |
| Gradient call count    | 'g_count'    | '^[Gg].*[ -_][Cc]ount'                           |
|                        |              |                                                  |
| Hessian call count     | 'h_count'    | '^[Hh].*[ -_][Cc]ount'                           |
|________________________|______________|__________________________________________________|


NOE calculation data type string matching patterns
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

_________________________________________
|                        |              |
| Data type              | Object name  |
|________________________|______________|
|                        |              |
| Reference intensity    | 'ref'        |
|                        |              |
| Saturated intensity    | 'sat'        |
|                        |              |
| NOE                    | 'noe'        |
|________________________|______________|


Relaxation curve fitting data type string matching patterns
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

____________________________________________________________
|                                   |                      |
| Data type                         | Object name          |
|___________________________________|______________________|
|                                   |                      |
| Relaxation rate                   | 'rx'                 |
|                                   |                      |
| Peak intensities (series)         | 'intensities'        |
|                                   |                      |
| Initial intensity                 | 'i0'                 |
|                                   |                      |
| Intensity at infinity             | 'iinf'               |
|                                   |                      |
| Relaxation period times (series)  | 'relax_times'        |
|___________________________________|______________________|


Reduced spectral density mapping data type string matching patterns
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

_____________________________________________
|                        |                  |
| Data type              | Object name      |
|________________________|__________________|
|                        |                  |
| J(0)                   | 'j0'             |
|                        |                  |
| J(wX)                  | 'jwx'            |
|                        |                  |
| J(wH)                  | 'jwh'            |
|                        |                  |
| Bond length            | 'r'              |
|                        |                  |
| CSA                    | 'csa'            |
|                        |                  |
| Heteronucleus type     | 'heteronuc_type' |
|                        |                  |
| Proton type            | 'proton_type'    |
|________________________|__________________|


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

_____________________________________________
|                        |                  |
| Data type              | Object name      |
|________________________|__________________|
|                        |                  |
| Local tm               | 'local_tm'       |
|                        |                  |
| Order parameter S2     | 's2'             |
|                        |                  |
| Order parameter S2f    | 's2f'            |
|                        |                  |
| Order parameter S2s    | 's2s'            |
|                        |                  |
| Correlation time te    | 'te'             |
|                        |                  |
| Correlation time tf    | 'tf'             |
|                        |                  |
| Correlation time ts    | 'ts'             |
|                        |                  |
| Chemical exchange      | 'rex'            |
|                        |                  |
| Bond length            | 'r'              |
|                        |                  |
| CSA                    | 'csa'            |
|                        |                  |
| Heteronucleus type     | 'heteronuc_type' |
|                        |                  |
| Proton type            | 'proton_type'    |
|________________________|__________________|