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

Class Grace

source code

Instance Methods [hide private]
 
__init__(self, relax) source code
 
view(self, file=None, dir='grace', grace_exe='xmgrace')
Function for running Grace.
source code
 
write(self, run=None, x_data_type='res', y_data_type=None, res_num=None, res_name=None, plot_data='value', norm=0, file=None, dir='grace', force=0)
Function for creating a grace '.agr' file.
source code
Method Details [hide private]

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

source code 
Function for running Grace.

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

file:  The name of the file.

dir:  The directory name.

grace_exe:  The Grace executable file.


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

This function can be used to execute Grace to view the specified file the Grace '.agr' file
and the execute Grace. If the directory name is set to None, the file will be assumed to be
in the current working directory.


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, run=None, x_data_type='res', y_data_type=None, res_num=None, res_name=None, plot_data='value', norm=0, file=None, dir='grace', force=0)

source code 
Function for creating a grace '.agr' file.

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

run:  The name of the run.

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

res_num:  The residue number (regular expression is allowed).

res_name:  The residue name (regular expression is allowed).

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 1, will cause the file to be overwritten.


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

This function 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 residue number and name selection arguments, and an argument for selecting what to
actually 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
residue number 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 run.

The residue number and name arguments can be used to limit the residues used in the plot.
The default is that all residues will be used, however, these arguments can be used to
select a subset of all residues, or a single residue for plots of Monte Carlo simulations,
etc.  Regular expression is allowed for both the residue number and name, and the number can
either be an integer or a string.

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 one then the
y-value of the first point of the series will be set to 1.  This normalisation is useful for
emphasising errors in the data sets.


Examples
~~~~~~~~

To write the NOE values for all residues from the run 'noe' to the Grace file 'noe.agr',
type:

relax> grace.write('noe', 'res', 'noe', file='noe.agr')
relax> grace.write('noe', y_data_type='noe', file='noe.agr')
relax> grace.write('noe', x_data_type='res', y_data_type='noe', file='noe.agr')
relax> grace.write(run='noe', y_data_type='noe', file='noe.agr', force=1)


To create a Grace file of 'S2' vs. 'te' for all residues, type:

relax> grace.write('m2', 'S2', 'te', file='s2_te.agr')
relax> grace.write('m2', x_data_type='S2', y_data_type='te', file='s2_te.agr')
relax> grace.write(run='m2', x_data_type='S2', y_data_type='te', file='s2_te.agr', force=1)


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

relax> grace.write('m4', 'Rex', 'te', res_num=123, plot_data='sims', file='s2_te.agr')
relax> grace.write(run='m4', x_data_type='Rex', y_data_type='te', res_num=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(name, x_data_type='relax_times', y_data_type='ave_int',
                   norm=1, file='intensities_norm.agr', force=1)




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.


Consistency testing data type string matching patterns
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

____________________________________________________________________________________________
|                       |               |                                                  |
| Data type             | Object name   | Patterns                                         |
|_______________________|_______________|__________________________________________________|
|                       |               |                                                  |
| J(0)                  | 'j0'          | '^[Jj]0$' or '[Jj]\(0\)'                         |
|                       |               |                                                  |
| F_eta                 | 'f_eta'       | '^[Ff]_[Ee][Tt][Aa]$'                            |
|                       |               |                                                  |
| F_R2                  | 'f_r2'        | '^[Ff]_[Rr]2$'                                   |
|                       |               |                                                  |
| Bond length           | 'r'           | '^r$' or '[Bb]ond[ -_][Ll]ength'                 |
|                       |               |                                                  |
| CSA                   | 'csa'         | '^[Cc][Ss][Aa]$'                                 |
|                       |               |                                                  |
| Angle Theta           | 'orientation' | '^[Oo][Rr][Ii][Ee][Nn][Tt][Aa][Tt][Ii][Oo][Nn]$' |
|                       |               |                                                  |
| Correlation time      | 'tc'          | '^[Tt]c$'                                        |
|_______________________|_______________|__________________________________________________|




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  | Patterns                                         |
|________________________|______________|__________________________________________________|
|                        |              |                                                  |
| Reference intensity    | 'ref'        | '^[Rr]ef$' or '[Rr]ef[ -_][Ii]nt'                |
|                        |              |                                                  |
| Saturated intensity    | 'sat'        | '^[Ss]at$' or '[Ss]at[ -_][Ii]nt'                |
|                        |              |                                                  |
| NOE                    | 'noe'        | '^[Nn][Oo][Ee]$'                                 |
|________________________|______________|__________________________________________________|



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

__________________________________________________________________________________________
|                                   |                      |                             |
| Data type                         | Object name          | Patterns                    |
|___________________________________|______________________|_____________________________|
|                                   |                      |                             |
| Relaxation rate                   | 'rx'                 | '^[Rr]x$'                   |
|                                   |                      |                             |
| Average peak intensities (series) | 'ave_intensities'    | '^[Aa]ve[ -_][Ii]nt$'       |
|                                   |                      |                             |
| Initial intensity                 | 'i0'                 | '^[Ii]0$'                   |
|                                   |                      |                             |
| Intensity at infinity             | 'iinf'               | '^[Ii]inf$'                 |
|                                   |                      |                             |
| Relaxation period times (series)  | 'relax_times'        | '^[Rr]elax[ -_][Tt]imes$'   |
|___________________________________|______________________|_____________________________|



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

____________________________________________________________________________________________
|                        |              |                                                  |
| Data type              | Object name  | Patterns                                         |
|________________________|______________|__________________________________________________|
|                        |              |                                                  |
| J(0)                   | 'j0'         | '^[Jj]0$' or '[Jj]\(0\)'                         |
|                        |              |                                                  |
| J(wX)                  | 'jwx'        | '^[Jj]w[Xx]$' or '[Jj]\(w[Xx]\)'                 |
|                        |              |                                                  |
| J(wH)                  | 'jwh'        | '^[Jj]w[Hh]$' or '[Jj]\(w[Hh]\)'                 |
|                        |              |                                                  |
| Bond length            | 'r'          | '^r$' or '[Bb]ond[ -_][Ll]ength'                 |
|                        |              |                                                  |
| CSA                    | 'csa'        | '^[Cc][Ss][Aa]$'                                 |
|________________________|______________|__________________________________________________|




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

____________________________________________________________________________________________
|                        |              |                                                  |
| Data type              | Object name  | Patterns                                         |
|________________________|______________|__________________________________________________|
|                        |              |                                                  |
| Local tm               | 'local_tm'   | '[Ll]ocal[ -_]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]$'                                 |
|________________________|______________|__________________________________________________|