Author: bugman
Date: Fri Jul 8 16:15:53 2011
New Revision: 13546
URL: http://svn.gna.org/viewcvs/relax?rev=13546&view=rev
Log:
Converted the grace user functions to the new documentation system.
Modified:
branches/gui_testing/prompt/grace.py
Modified: branches/gui_testing/prompt/grace.py
URL:
http://svn.gna.org/viewcvs/relax/branches/gui_testing/prompt/grace.py?rev=13546&r1=13545&r2=13546&view=diff
==============================================================================
--- branches/gui_testing/prompt/grace.py (original)
+++ branches/gui_testing/prompt/grace.py Fri Jul 8 16:15:53 2011
@@ -1,6 +1,6 @@
###############################################################################
#
#
-# Copyright (C) 2004-2005, 2009-2010 Edward d'Auvergne
#
+# Copyright (C) 2004-2011 Edward d'Auvergne
#
#
#
# This file is part of the program relax.
#
#
#
@@ -25,7 +25,7 @@
__docformat__ = 'plaintext'
# relax module imports.
-from base_class import User_fn_class
+from base_class import User_fn_class, _build_doc
import arg_check
from doc_string import docs
from generic_fns import grace, minimise
@@ -39,35 +39,6 @@
"""Class for interfacing with Grace."""
def view(self, file=None, dir='grace', grace_exe='xmgrace'):
- """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')
- """
-
# Function intro text.
if self._exec_info.intro:
text = self._exec_info.ps3 + "grace.view("
@@ -84,64 +55,82 @@
# Execute the functional code.
grace.view(file=file, dir=dir, grace_exe=grace_exe)
+ # The function doc info.
+ view._doc_title = "Visualise the file within Grace."
+ view._doc_title_short = "Grace execution."
+ view._doc_args = [
+ ["file", "The name of the file."],
+ ["dir", "The directory name."],
+ ["grace_exe", "The Grace executable file."]
+ ]
+ view._doc_desc = """
+ 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.
+ """
+ view._doc_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')
+ """
+ _build_doc(view)
+
def write(self, x_data_type='spin', y_data_type=None, spin_id=None,
plot_data='value', file=None, dir='grace', force=False, norm=False):
- """Function for creating a grace '.agr' file.
+ # Function intro text.
+ if self._exec_info.intro:
+ text = self._exec_info.ps3 + "grace.write("
+ text = text + "x_data_type=" + repr(x_data_type)
+ text = text + ", y_data_type=" + repr(y_data_type)
+ text = text + ", spin_id=" + repr(spin_id)
+ text = text + ", plot_data=" + repr(plot_data)
+ text = text + ", file=" + repr(file)
+ text = text + ", dir=" + repr(dir)
+ text = text + ", force=" + repr(force)
+ text = text + ", norm=" + repr(norm) + ")"
+ print(text)
- Keyword Arguments
- ~~~~~~~~~~~~~~~~~
+ # The argument checks.
+ arg_check.is_str(x_data_type, 'x data type')
+ arg_check.is_str(y_data_type, 'y data type')
+ arg_check.is_str(spin_id, 'spin identification string',
can_be_none=True)
+ arg_check.is_str(plot_data, 'plot data')
+ arg_check.is_str(file, 'file name')
+ arg_check.is_str(dir, 'directory name', can_be_none=True)
+ arg_check.is_bool(force, 'force flag')
+ arg_check.is_bool(norm, 'normalisation flag')
- x_data_type: The data type for the X-axis (no regular expression is
allowed).
+ # Execute the functional code.
+ grace.write(x_data_type=x_data_type, y_data_type=y_data_type,
spin_id=spin_id, plot_data=plot_data, file=file, dir=dir, force=force,
norm=norm)
- y_data_type: The data type for the Y-axis (no regular expression is
allowed).
+ # The function doc info.
+ write._doc_title = "Create a grace '.agr' file."
+ write._doc_title_short = "Grace file creation."
+ write._doc_args = [
+ ["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."]
+ ]
+ write._doc_desc = """
+ 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
spin identification string, and an argument for selecting what to actually
plot.
- spin_id: The spin identification string.
+ 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.
- plot_data: The data to use for the plot.
+ 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.
- norm: Flag for the normalisation of series type data.
+ The property which is actually plotted can be controlled by the
'plot_data' argument. It can be one of the following:
- 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 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 spin identification string, 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
- 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
- ~~~~~~~~
-
+ 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.
+ """
+ write._doc_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')
@@ -175,42 +164,12 @@
relax> grace.write(x_data_type='relax_times', y_data_type='ave_int',
file='intensities_norm.agr', force=True,
norm=True)
"""
-
- # Function intro text.
- if self._exec_info.intro:
- text = self._exec_info.ps3 + "grace.write("
- text = text + "x_data_type=" + repr(x_data_type)
- text = text + ", y_data_type=" + repr(y_data_type)
- text = text + ", spin_id=" + repr(spin_id)
- text = text + ", plot_data=" + repr(plot_data)
- text = text + ", file=" + repr(file)
- text = text + ", dir=" + repr(dir)
- text = text + ", force=" + repr(force)
- text = text + ", norm=" + repr(norm) + ")"
- print(text)
-
- # The argument checks.
- arg_check.is_str(x_data_type, 'x data type')
- arg_check.is_str(y_data_type, 'y data type')
- arg_check.is_str(spin_id, 'spin identification string',
can_be_none=True)
- arg_check.is_str(plot_data, 'plot data')
- arg_check.is_str(file, 'file name')
- arg_check.is_str(dir, 'directory name', can_be_none=True)
- arg_check.is_bool(force, 'force flag')
- arg_check.is_bool(norm, 'normalisation flag')
-
- # Execute the functional code.
- grace.write(x_data_type=x_data_type, y_data_type=y_data_type,
spin_id=spin_id, plot_data=plot_data, file=file, dir=dir, force=force,
norm=norm)
-
-
-
- # Docstring modification.
- #########################
-
- # Write function.
- write.__doc__ = write.__doc__ + "\n\n" + docs.regexp.doc + "\n"
- write.__doc__ = write.__doc__ + minimise.return_data_name_doc + "\n\n"
- write.__doc__ = write.__doc__ + Noe.return_data_name_doc + "\n"
- write.__doc__ = write.__doc__ + Relax_fit.return_data_name_doc + "\n"
- write.__doc__ = write.__doc__ + Jw_mapping.return_data_name_doc + "\n\n"
- write.__doc__ = write.__doc__ + Model_free.return_data_name_doc + "\n\n"
+ write._doc_additional = [
+ docs.regexp.doc,
+ minimise.return_data_name_doc,
+ Noe.return_data_name_doc,
+ Relax_fit.return_data_name_doc,
+ Jw_mapping.return_data_name_doc,
+ Model_free.return_data_name_doc
+ ]
+ _build_doc(write)
r13546 - /branches/gui_testing/prompt/grace.py