Source Code for Module gromacs.analysis.plugins.template_plugin

  1  # $Id$ 
  2  # Copyright (c) 2009 Oliver Beckstein <orbeckst@gmail.com> 
  3  # Released under the GNU Public License 3 (or higher, your choice) 
  4  # See the file COPYING for details. 
  5   
  6  """ 
  7  Template for a plugin 
  8  ====================== 
  9   
 10  You can use this file to write plugins that conform to the plugin API. 
 11   
 12  Names that are supposed to be changed to more sensible values have 
 13  *TEMPLATE* in their name. 
 14   
 15   
 16  .. note:: 
 17   
 18     This plugin is the canonical example for how to structure plugins that 
 19     conform to the plugin API (see docs :mod:`gromacs.analysis.core` for 
 20     details). 
 21   
 22  Plugin class 
 23  ------------ 
 24   
 25  .. autoclass:: TEMPLATEplugin 
 26     :members: worker_class 
 27     :undoc-members: 
 28   
 29  Worker class 
 30  ------------ 
 31   
 32  The worker class performs the analysis. 
 33   
 34  .. autoclass:: _TEMPLATEplugin 
 35     :members: 
 36   
 37   
 38  """ 
 39  from __future__ import with_statement 
 40   
 41  __docformat__ = "restructuredtext en" 
 42   
 43  import os.path 
 44  import warnings 
 45   
 46  import gromacs 
 47  from gromacs.utilities import AttributeDict 
 48  from gromacs.analysis.core import Worker, Plugin 
 49   
 50  import logging 
 51  logger = logging.getLogger('gromacs.analysis.plugins.TEMPLATE') 
 52   
 53  # Worker classes that are registered via Plugins (see below) 
 54  # ---------------------------------------------------------- 
 55  # These must be defined before the plugins. 
 56   
 57 -class _TEMPLATEplugin(Worker): 
 58      """TEMPLATE worker class.""" 
 59   
 60 -    def __init__(self,**kwargs): 
 61          """Set up  TEMPLATE analysis. 
 62   
 63          This is the worker class; this is where all the real analysis is done. 
 64   
 65          :Arguments: 
 66             *keyword_1* 
 67                 description 
 68             *keyword_2* 
 69                 description 
 70   
 71          """ 
 72          # specific arguments: take them before calling the super class that 
 73          # does not know what to do with them 
 74          ## x1 = kwargs.pop('keyword_1',None)  
 75          ## x2 = kwargs.pop('keyword_1', 1.234)   # nm 
 76   
 77          # super class init: do this before doing anything else 
 78          # (also sets up self.parameters and self.results) 
 79          super(_TEMPLATEplugin, self).__init__(**kwargs) 
 80   
 81          # process specific parameters now and set instance variables 
 82          # .... 
 83          # self.parameters.filenames = { 'xxx': 'yyy', ....} 
 84          # .... 
 85   
 86          # self.simulation might have been set by the super class 
 87          # already; just leave this snippet at the end. Do all 
 88          # initialization that requires the simulation class in the 
 89          # _register_hook() method. 
 90          if not self.simulation is None: 
 91              self._register_hook() 
 92   
 93 -    def _register_hook(self, **kwargs): 
 94          """Run when registering; requires simulation.""" 
 95   
 96          super(_TEMPLATEplugin, self)._register_hook(**kwargs) 
 97          assert not self.simulation is None 
 98   
 99          # EXAMPLES: 
100          # filename of the index file that we generate for the cysteines 
101          ## self.parameters.ndx = self.plugindir('cys.ndx') 
102          # output filenames for g_dist, indexed by Cys resid 
103          ## self.parameters.filenames = dict(\ 
104          ##    [(resid, self.plugindir('Cys%d_OW_dist.txt.bz2' % resid)) 
105          ##     for resid in self.parameters.cysteines]) 
106          # default filename for the combined plot 
107          ## self.parameters.figname = self.figdir('mindist_S_OW') 
108   
109   
110      # override 'API' methods of base class 
111           
112 -    def run(self, cutoff=None, force=False, **gmxargs): 
113          """Short description of what is performed. 
114   
115          The run method typically processes trajectories and writes data files. 
116          """ 
117          # filename = self.parameters.filenames['XXXX'] 
118          # if not self.check_file_exists(filename, resolve='warning') or force: 
119          #    logger.info("Analyzing TEMPLATE...") 
120   
121          pass 
122   
123   
124 -    def analyze(self,**kwargs): 
125          """Short description of postprocessing. 
126   
127          The analyze method typically postprocesses the data files 
128          generated by run. Splitting the complete analysis task into 
129          two parts (*run* and *analyze*) is advantageous because in 
130          this way parameters of postprocessing steps can be easily 
131          changed without having to rerun the time consuming trajectory 
132          analysis. 
133   
134          :Keywords: 
135            *kw1* 
136               description 
137          :Returns:  a dictionary of the results and also sets ``self.results``. 
138          """         
139          from gromacs.utilities import XVG 
140   
141          results = AttributeDict() 
142   
143          # - Do postprocessing here. 
144          # - Store results of calculation in results[key] where key can be chosen freely 
145          #   but *must* be provided so that other functions can uniformly access results. 
146          # - You are encouraged to store class instances with a plot() method; if you do 
147          #   this then you can just don't have to change the plot() method below. 
148          #   For instance you can use gromacs.formats.XVG(filename) to create 
149          #   a object from a xvg file that knows how to plot itself. 
150   
151          self.results = results 
152          return results 
153   
154 -    def plot(self, **kwargs): 
155          """Plot all results in one graph, labelled by the result keys. 
156   
157          :Keywords: 
158             figure 
159                 - ``True``: save figures in the given formats 
160                 - "name.ext": save figure under this filename (``ext`` -> format) 
161                 - ``False``: only show on screen 
162             formats : sequence 
163                 sequence of all formats that should be saved [('png', 'pdf')] 
164             plotargs     
165                 keyword arguments for pylab.plot() 
166          """ 
167   
168          import pylab 
169          figure = kwargs.pop('figure', False) 
170          extensions = kwargs.pop('formats', ('pdf','png')) 
171          for name,result in self.results.items(): 
172              kwargs['label'] = name 
173              try: 
174                  result.plot(**kwargs)      # This requires result classes with a plot() method!! 
175              except AttributeError: 
176                  warnings.warn("Sorry, plotting of result %(name)r is not implemented" % vars(), 
177                                category=UserWarning)                 
178          pylab.legend(loc='best') 
179          if figure is True: 
180              for ext in extensions: 
181                  self.savefig(ext=ext) 
182          elif figure: 
183              self.savefig(filename=figure) 
184   
185       
186   
187   
188  # Public classes that register the worker classes 
189  #------------------------------------------------ 
190   
191 -class TEMPLATEplugin(Plugin): 
192      """*TEMPLATE* plugin. 
193       
194      Describe the plugin in detail here. This is what the user will 
195      see. Add citations etc. 
196   
197      # explicitly describe the call/init signature of the plugin here; 
198      # note that *all* arguments are technically keyword arguments 
199      # (this is a requirement of the API) but if there are required 
200      # parameters feel free to write them without square brackets in 
201      # the call signature as done for parameter_1 below. 
202      # 
203      # The name and simulation parameters are always present. 
204   
205      .. class:: TEMPLATEplugin(parameter_1[, kwparameter_2[, name[, simulation]]]) 
206       
207      :Arguments: 
208          *parameter_1* 
209              required, otherwise the plugin won't be able to do anything 
210          *kwparameter_2* 
211              this optional parameter tunes the frobbnification 
212          *name* : string 
213              plugin name (used to access it) 
214          *simulation* : instance 
215              The :class:`gromacs.analysis.Simulation` instance that owns the plugin. 
216   
217      """ 
218      worker_class = _TEMPLATEplugin 
219