monitor/extra/Gnuplot/__init__.py

   1 #! /usr/bin/env python
   2 # $Id: __init__.py 306 2008-05-02 01:09:02Z alford $
   3
   4 # Copyright (C) 1998-2003 Michael Haggerty <mhagger@alum.mit.edu>
   5 #
   6 # This file is licensed under the GNU Lesser General Public License
   7 # (LGPL).  See LICENSE.txt for details.
   8
   9 """Gnuplot -- A pipe-based interface to the gnuplot plotting program.
  10
  11 This is the main module of the Gnuplot package.
  12
  13 Written by "Michael Haggerty", mailto:mhagger@alum.mit.edu.  Inspired
  14 by and partly derived from an earlier version by "Konrad Hinsen",
  15 mailto:hinsen@ibs.ibs.fr.  If you find a problem or have a suggestion,
  16 please "let me know", mailto:mhagger@alum.mit.edu.  Other feedback
  17 would also be appreciated.
  18
  19 The Gnuplot.py home page is at
  20
  21 "Gnuplot.py", http://gnuplot-py.sourceforge.net
  22
  23
  24 For information about how to use this module:
  25
  26 1. Check the README file.
  27
  28 2. Look at the example code in demo.py and try running it by typing
  29    'python demo.py' or 'python __init__.py'.
  30
  31 3. For more details see the extensive documentation strings
  32    throughout the python source files, especially this file,
  33    _Gnuplot.py, PlotItems.py, and gp_unix.py.
  34
  35 4. The docstrings have also been turned into html which can be read
  36    "here", http://gnuplot-py.sourceforge.net/doc.  However, the
  37    formatting is not perfect; when in doubt, double-check the
  38    docstrings.
  39
  40 You should import this file with 'import Gnuplot', not with 'from
  41 Gnuplot import *', because the module and the main class have the same
  42 name, `Gnuplot'.
  43
  44 To obtain the gnuplot plotting program itself, see "the gnuplot FAQ",
  45 ftp://ftp.gnuplot.vt.edu/pub/gnuplot/faq/index.html.  Obviously you
  46 need to have gnuplot installed if you want to use Gnuplot.py.
  47
  48 The old command-based interface to gnuplot (previously supported as
  49 'oldplot.py') has been removed from the package.
  50
  51 Features:
  52
  53  o  Allows the creation of two or three dimensional plots from
  54     python.
  55
  56  o  A gnuplot session is an instance of class 'Gnuplot'.  Multiple
  57     sessions can be open at once.  For example::
  58
  59         g1 = Gnuplot.Gnuplot()
  60         g2 = Gnuplot.Gnuplot()
  61
  62     Note that due to limitations on those platforms, opening multiple
  63     simultaneous sessions on Windows or Macintosh may not work
  64     correctly.  (Feedback?)
  65
  66  o  The implicitly-generated gnuplot commands can be stored to a file
  67     instead of executed immediately::
  68
  69         g = Gnuplot.Gnuplot('commands.txt')
  70
  71     The 'commands.txt' file can then be run later with gnuplot's
  72     'load' command.  Beware, however: the plot commands may depend on
  73     the existence of temporary files, which will probably be deleted
  74     before you use the command file.
  75
  76  o  Can pass arbitrary commands to the gnuplot command interpreter::
  77
  78         g('set pointsize 2')
  79
  80     (If this is all you want to do, you might consider using the
  81     lightweight GnuplotProcess class defined in gp.py.)
  82
  83  o  A Gnuplot object knows how to plot objects of type 'PlotItem'.
  84     Any PlotItem can have optional 'title' and/or 'with' suboptions.
  85     Builtin PlotItem types:
  86
  87     * 'Data(array1)' -- data from a Python list or NumPy array
  88                         (permits additional option 'cols' )
  89
  90     * 'File('filename')' -- data from an existing data file (permits
  91                             additional option 'using' )
  92
  93     * 'Func('exp(4.0 * sin(x))')' -- functions (passed as a string,
  94                                      evaluated by gnuplot)
  95
  96     * 'GridData(m, x, y)' -- data tabulated on a grid of (x,y) values
  97                              (usually to be plotted in 3-D)
  98
  99     See the documentation strings for those classes for more details.
 100
 101  o  PlotItems are implemented as objects that can be assigned to
 102     variables and plotted repeatedly.  Most of their plot options can
 103     also be changed with the new 'set_option()' member functions then
 104     they can be replotted with their new options.
 105
 106  o  Communication of commands to gnuplot is via a one-way pipe.
 107     Communication of data from python to gnuplot is via inline data
 108     (through the command pipe) or via temporary files.  Temp files are
 109     deleted automatically when their associated 'PlotItem' is deleted.
 110     The PlotItems in use by a Gnuplot object at any given time are
 111     stored in an internal list so that they won't be deleted
 112     prematurely.
 113
 114  o  Can use 'replot' method to add datasets to an existing plot.
 115
 116  o  Can make persistent gnuplot windows by using the constructor option
 117     'persist=1'.  Such windows stay around even after the gnuplot
 118     program is exited.  Note that only newer version of gnuplot support
 119     this option.
 120
 121  o  Can plot either directly to a postscript printer or to a
 122     postscript file via the 'hardcopy' method.
 123
 124  o  Grid data for the splot command can be sent to gnuplot in binary
 125     format, saving time and disk space.
 126
 127  o  Should work under Unix, Macintosh, and Windows.
 128
 129 Restrictions:
 130
 131  -  Relies on the numpy Python extension.  This can be obtained from
 132     the Scipy group at <http://www.scipy.org/Download>.  If you're
 133     interested in gnuplot, you would probably also want numpy anyway.
 134
 135  -  Only a small fraction of gnuplot functionality is implemented as
 136     explicit method functions.  However, you can give arbitrary
 137     commands to gnuplot manually::
 138
 139         g = Gnuplot.Gnuplot()
 140         g('set data style linespoints')
 141         g('set pointsize 5')
 142
 143  -  There is no provision for missing data points in array data (which
 144     gnuplot allows via the 'set missing' command).
 145
 146 Bugs:
 147
 148  -  No attempt is made to check for errors reported by gnuplot.  On
 149     unix any gnuplot error messages simply appear on stderr.  (I don't
 150     know what happens under Windows.)
 151
 152  -  All of these classes perform their resource deallocation when
 153     '__del__' is called.  Normally this works fine, but there are
 154     well-known cases when Python's automatic resource deallocation
 155     fails, which can leave temporary files around.
 156
 157 """
 158
 159 __version__ = '1.8'
 160
 161 # Other modules that should be loaded for 'from Gnuplot import *':
 162 __all__ = ['utils', 'funcutils', ]
 163
 164 from gp import GnuplotOpts, GnuplotProcess, test_persist
 165 from Errors import Error, OptionError, DataError
 166 from PlotItems import PlotItem, Func, File, Data, GridData
 167 from _Gnuplot import Gnuplot
 168
 169
 170 if __name__ == '__main__':
 171     import demo
 172     demo.demo()
 173
 174