hooke/driver/tutorial.py

   1 # Copyright (C) 2010 W. Trevor King <wking@drexel.edu>
   2 #
   3 # This file is part of Hooke.
   4 #
   5 # Hooke is free software: you can redistribute it and/or modify it
   6 # under the terms of the GNU Lesser General Public License as
   7 # published by the Free Software Foundation, either version 3 of the
   8 # License, or (at your option) any later version.
   9 #
  10 # Hooke is distributed in the hope that it will be useful, but WITHOUT
  11 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  12 # or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General
  13 # Public License for more details.
  14 #
  15 # You should have received a copy of the GNU Lesser General Public
  16 # License along with Hooke.  If not, see
  17 # <http://www.gnu.org/licenses/>.
  18
  19 """Tutorial driver for Hooke.
  20
  21 This example driver explains driver construction.
  22 """
  23
  24 """
  25 Here we define a simple file format that is read by this driver. The
  26 file format is as following::
  27
  28     TUTORIAL_FILE
  29     PLOT1
  30     X1
  31     n1   <- ?
  32     n2
  33     ...
  34     nN
  35     Y1
  36     n1
  37     n2
  38     ...
  39     nN
  40     X2
  41     n1
  42     n2
  43     ..
  44     nN
  45     Y2
  46     n1
  47     n2
  48     ..
  49     nN
  50     PLOT2
  51     X1
  52     ...
  53     Y1
  54     ...
  55     X2
  56     ...
  57     Y2
  58     ...
  59     END
  60
  61 that is, two plots with two datasets each.
  62 """
  63
  64 import os.path
  65
  66 # The following are relative imports.  See PEP 328 for details
  67 #   http://www.python.org/dev/peps/pep-0328/
  68 from .. import curve as curve # this module defines data containers.
  69 from .. import experiment as experiment # this module defines expt. types
  70 from ..config import Setting # configurable setting class
  71 from . import Driver as Driver # this is the Driver base class
  72
  73 # The driver must inherit from the parent
  74 # :class:`hooke.driver.Driver` (which we have imported as `Driver`).
  75 class TutorialDriver (Driver):
  76     """Handle simple text data as an example Driver.
  77     """
  78     def __init__(self):
  79         """YOU MUST OVERRIDE Driver.__init__.
  80
  81         Here you set a value for `name` to identify your driver.  It
  82         should match the module name.
  83         """
  84         super(TutorialDriver, self).__init__(name='tutorial')
  85
  86     def default_settings(self):
  87         """Return a list of any configurable settings for your driver.
  88
  89         If your driver does not have any configurable settings, there
  90         is no need to override this method.
  91         """
  92         return [
  93             Setting(section=self.setting_section, help=self.__doc__),
  94             Setting(section=self.setting_section, option='x units', value='nm',
  95                     help='Set the units used for the x data.'),
  96             ]
  97
  98     def is_me(self, path):
  99         """YOU MUST OVERRIDE Driver.is_me.
 100
 101         RETURNS: Boolean (`True` or `False`)
 102
 103         This method is a heuristic that looks at the file content and
 104         decides if the file can be opened by the driver itself.  It
 105         returns `True` if the file opened can be interpreted by the
 106         current driver, `False` otherwise.  Defining this method allows
 107         Hooke to understand what kind of files we're looking at
 108         automatically.
 109         """
 110         if os.path.isdir(path):
 111             return False
 112
 113         f = open(path, 'r')
 114         header = f.readline() # we only need the first line
 115         f.close()
 116
 117         """Our "magic fingerprint" is the TUTORIAL_FILE header. Of
 118         course, depending on the data file, you can have interesting
 119         headers, or patterns, etc. that you can use to guess the data
 120         format. What matters is successful recognition and the boolean
 121         (True/False) return.
 122         """
 123         if header.startswith('TUTORIAL_FILE'):
 124             return True
 125         return False
 126
 127     def read(self, path, info=None):
 128         f = open(path,'r') # open the file for reading
 129         """In this case, we have a data format that is just a list of
 130         ASCII values, so we can just divide that in rows, and generate
 131         a list with each item being a row.  Of course if your data
 132         files are binary, or follow a different approach, do whatever
 133         you need. :)
 134         """
 135         self.data = list(self.filedata)
 136         f.close() # remember to close the file
 137
 138         data = curve.Data()
 139         info = {'filetype':'tutorial', 'experiment':experiment.Experiment}
 140         return (data, info)