Source Code for Module prompt.grace

  1  ############################################################################### 
  2  #                                                                             # 
  3  # Copyright (C) 2004-2012 Edward d'Auvergne                                   # 
  4  #                                                                             # 
  5  # This file is part of the program relax.                                     # 
  6  #                                                                             # 
  7  # relax is free software; you can redistribute it and/or modify               # 
  8  # it under the terms of the GNU General Public License as published by        # 
  9  # the Free Software Foundation; either version 2 of the License, or           # 
 10  # (at your option) any later version.                                         # 
 11  #                                                                             # 
 12  # relax is distributed in the hope that it will be useful,                    # 
 13  # but WITHOUT ANY WARRANTY; without even the implied warranty of              # 
 14  # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the               # 
 15  # GNU General Public License for more details.                                # 
 16  #                                                                             # 
 17  # You should have received a copy of the GNU General Public License           # 
 18  # along with relax; if not, write to the Free Software                        # 
 19  # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA   # 
 20  #                                                                             # 
 21  ############################################################################### 
 22   
 23  # Module docstring. 
 24  """Module containing the 'grace' user function class for controlling the Grace data viewing software.""" 
 25  __docformat__ = 'plaintext' 
 26   
 27  # relax module imports. 
 28  from base_class import User_fn_class, _build_doc 
 29  import arg_check 
 30  from doc_string import docs 
 31  from generic_fns import grace, minimise 
 32  from specific_fns.model_free import Model_free 
 33  from specific_fns.jw_mapping import Jw_mapping 
 34  from specific_fns.noe import Noe 
 35  from specific_fns.relax_fit import Relax_fit 
 36   
 37   
 38 -class Grace(User_fn_class): 
 39      """Class for interfacing with Grace.""" 
 40   
 41 -    def view(self, file=None, dir='grace', grace_exe='xmgrace'): 
 42          # Function intro text. 
 43          if self._exec_info.intro: 
 44              text = self._exec_info.ps3 + "grace.view(" 
 45              text = text + "file=" + repr(file) 
 46              text = text + ", dir=" + repr(dir) 
 47              text = text + ", grace_exe=" + repr(grace_exe) + ")" 
 48              print(text) 
 49   
 50          # The argument checks. 
 51          arg_check.is_str(file, 'file name') 
 52          arg_check.is_str(dir, 'directory name', can_be_none=True) 
 53          arg_check.is_str(grace_exe, 'Grace executable file') 
 54   
 55          # Execute the functional code. 
 56          grace.view(file=file, dir=dir, grace_exe=grace_exe) 
 57   
 58      # The function doc info. 
 59      view._doc_title = "Visualise the file within Grace." 
 60      view._doc_title_short = "Grace execution." 
 61      view._doc_args = [ 
 62          ["file", "The name of the file."], 
 63          ["dir", "The directory name."], 
 64          ["grace_exe", "The Grace executable file."] 
 65      ] 
 66      view._doc_desc = """ 
 67          This can be used to view the specified Grace '*.agr' file by opening it with the Grace program. 
 68          """ 
 69      view._doc_examples = """ 
 70          To view the file 's2.agr' in the directory 'grace', type: 
 71   
 72          relax> grace.view(file='s2.agr') 
 73          relax> grace.view(file='s2.agr', dir='grace') 
 74          """ 
 75      _build_doc(view) 
 76   
 77   
 78 -    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): 
 79          # Function intro text. 
 80          if self._exec_info.intro: 
 81              text = self._exec_info.ps3 + "grace.write(" 
 82              text = text + "x_data_type=" + repr(x_data_type) 
 83              text = text + ", y_data_type=" + repr(y_data_type) 
 84              text = text + ", spin_id=" + repr(spin_id) 
 85              text = text + ", plot_data=" + repr(plot_data) 
 86              text = text + ", file=" + repr(file) 
 87              text = text + ", dir=" + repr(dir) 
 88              text = text + ", force=" + repr(force) 
 89              text = text + ", norm=" + repr(norm) + ")" 
 90              print(text) 
 91   
 92          # The argument checks. 
 93          arg_check.is_str(x_data_type, 'x data type') 
 94          arg_check.is_str(y_data_type, 'y data type') 
 95          arg_check.is_str(spin_id, 'spin identification string', can_be_none=True) 
 96          arg_check.is_str(plot_data, 'plot data') 
 97          arg_check.is_str(file, 'file name') 
 98          arg_check.is_str(dir, 'directory name', can_be_none=True) 
 99          arg_check.is_bool(force, 'force flag') 
100          arg_check.is_bool(norm, 'normalisation flag') 
101   
102          # Execute the functional code. 
103          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) 
104   
105      # The function doc info. 
106      write._doc_title = "Create a grace '.agr' file." 
107      write._doc_title_short = "Grace file creation." 
108      write._doc_args = [ 
109          ["x_data_type", "The data type for the X-axis (no regular expression is allowed)."], 
110          ["y_data_type", "The data type for the Y-axis (no regular expression is allowed)."], 
111          ["spin_id", "The spin identification string."], 
112          ["plot_data", "The data to use for the plot."], 
113          ["norm", "Flag for the normalisation of series type data."], 
114          ["file", "The name of the file."], 
115          ["dir", "The directory name."], 
116          ["force", "A flag which, if set to True, will cause the file to be overwritten."] 
117      ] 
118      write._doc_desc = """ 
119          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. 
120   
121          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. 
122   
123          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. 
124   
125          The property which is actually plotted can be controlled by the 'plot_data' argument.  It can be one of the following: 
126   
127              'value':  Plot values (with errors if they exist). 
128              'error':  Plot errors. 
129              'sims':   Plot the simulation values. 
130   
131          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. 
132          """ 
133      write._doc_examples = """ 
134          To write the NOE values for all spins to the Grace file 'noe.agr', type one of: 
135   
136          relax> grace.write('spin', 'noe', file='noe.agr') 
137          relax> grace.write(y_data_type='noe', file='noe.agr') 
138          relax> grace.write(x_data_type='spin', y_data_type='noe', file='noe.agr') 
139          relax> grace.write(y_data_type='noe', file='noe.agr', force=True) 
140   
141   
142          To create a Grace file of 's2' vs. 'te' for all spins, type one of: 
143   
144          relax> grace.write('s2', 'te', file='s2_te.agr') 
145          relax> grace.write(x_data_type='s2', y_data_type='te', file='s2_te.agr') 
146          relax> grace.write(x_data_type='s2', y_data_type='te', file='s2_te.agr', force=True) 
147   
148   
149          To create a Grace file of the Monte Carlo simulation values of 'rex' vs. 'te' for residue 
150          123, type one of: 
151   
152          relax> grace.write('rex', 'te', spin_id=':123', plot_data='sims', file='s2_te.agr') 
153          relax> grace.write(x_data_type='rex', y_data_type='te', spin_id=':123', 
154                             plot_data='sims', file='s2_te.agr') 
155   
156   
157          By plotting the peak intensities, the integrity of exponential relaxation curves can be 
158          checked and anomalies searched for prior to model-free analysis or reduced spectral density 
159          mapping.  For example the normalised average peak intensities can be plotted verses the 
160          relaxation time periods for the relaxation curves of all residues of a protein.  The 
161          normalisation, whereby the initial peak intensity of each residue I(0) is set to 1, 
162          emphasises any problems.  To produce this Grace file, type: 
163   
164          relax> grace.write(x_data_type='relax_times', y_data_type='ave_int', 
165                             file='intensities_norm.agr', force=True, norm=True) 
166          """ 
167      write._doc_additional = [ 
168          docs.regexp.doc, 
169          minimise.return_data_name_doc, 
170          Noe.return_data_name_doc, 
171          Relax_fit.return_data_name_doc, 
172          Jw_mapping.return_data_name_doc, 
173          Model_free.return_data_name_doc 
174      ] 
175      _build_doc(write) 
176