Module Gnuplot

submodule demo # demo.py -- Demonstrate the Gnuplot python module.
submodule oldplot # oldplot.py -- Obsolete functional interface to Gnuplot.
submodule test # test.py -- Exercise the Gnuplot.py module.
class AnyFile # Representation of any kind of file to be used by gnuplot.
class ArrayFile(AnyFile) # A file to which, upon creation, an array is written.
class Data(PlotItem) # Represents data from memory to be plotted with Gnuplot.
class DataException(Exception) # Raised for data in the wrong format
class File(PlotItem) # A PlotItem representing a file that contains gnuplot data.
class Func(PlotItem) # Represents a mathematical expression to plot.
class Gnuplot # Interface to a gnuplot program.
class GridData(PlotItem) # Holds data representing a function of two variables, for use in splot.
class GridFunc(GridData) # Holds data representing a function of two variables, for use in splot.
class OptionException(Exception) # Raised for unrecognized option(s)
class PlotItem # Plotitem represents an item that can be plotted by gnuplot.
class TempArrayFile(ArrayFile, TempFile) # An ArrayFile that is deleted automatically.
class TempFile(AnyFile) # A file that is automatically deleted.
class _unset # Used to represent unset keyword arguments.
def float_array(m) # Return the argument as a Numeric array of type at least 'Float32'.
def grid_function(f, xvals, yvals, typecode=None, ufunc=0) # Evaluate and tabulate a function on a grid.
def test_persist() # Determine whether gnuplot recognizes the option '-persist'.
def write_array(f, set, item_sep=' ', nest_prefix='', nest_suffix='\012', nest_sep='') # Write an array of arbitrary dimension to a file.
None CVS = None
list __all__ = ['oldplot']
string __cvs_version__ = '$Revision: 2.69 $'
string __file__ = '/home/mhagger/lib/python/Gnuplot/__init__.pyc'
list __path__ = ['/home/mhagger/lib/python/Gnuplot']
string __version__ = '1.3'
string _default_lpr = '| lpr'
string _default_term = 'x11'
string _gnuplot_command = 'gnuplot'
int _prefer_inline_data = 0
int _recognizes_binary_splot = 1
None _recognizes_persist = None

Description

This is the main module of the Gnuplot package.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details; it is available at <http://www.fsf.org/copyleft/gpl.html>, or by writing to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Written by Michael Haggerty <mhagger@blizzard.harvard.edu>. Inspired by and partly derived from an earlier version by Konrad Hinsen <hinsen@ibs.ibs.fr>. If you find a problem or have a suggestion, please let me know at <mhagger@blizzard.harvard.edu>. Other feedback would also be appreciated.

For information about how to use this module:

Check the README file. 2. Look at the test code in demo.py and try running it by typing python demo.py or python __init__.py. 3a. For more details see the extensive documentation strings throughout this file. 3b. The docstrings have also been turned into html which can be read at <http://monsoon.harvard.edu/~mhagger/Gnuplot/Gnuplot-doc/>. However, the formatting is not perfect; when in doubt, double-check the docstrings.

You should import this file with import Gnuplot, not with 'from Gnuplot import *', because the module and the main class have the same name, `Gnuplot'.

To obtain the gnuplot plotting program itself, see <ftp://ftp.gnuplot.vt.edu/pub/gnuplot/faq/index.html>. Obviously you need to have gnuplot installed if you want to use Gnuplot.py.

The old command-based interface to gnuplot has been separated out into a separate module, oldplot.py. If you are still using that interface you should import Gnuplot.oldplot; otherwise you should stick to the more flexible object-oriented interface contained here.

Features:

Allows the creation of two or three dimensional plots from python.
A gnuplot session is an instance of class Gnuplot. Multiple sessions can be open at once.
Example:
```
        g1 = Gnuplot.Gnuplot()
        g2 = Gnuplot.Gnuplot()
```
Note that due to a limitation in pgnuplot, opening multiple simultaneous sessions under Windows may not work correctly.
The implicitly-generated gnuplot commands can be stored to a file instead of executed immediately.
Example:
```
        g = Gnuplot.Gnuplot('commands.gnuplot')
```
The file can then be run later with gnuplot's load command. Beware, however: if the plot commands depend on the existence of temporary files, they will probably be deleted before you use the command file.
Can pass arbitrary commands to the gnuplot command interpreter.
Example:
```
        g('set pointsize 2')
```
A Gnuplot object knows how to plot objects of type PlotItem. Any PlotItem can have optional title and/or with suboptions. Builtin PlotItem types:
- Data(array1) -- data from a Python list or NumPy array (permits additional option cols )
- File('filename') -- data from an existing data file (permits additional option using )
- Func('exp(4.0 * sin(x))') -- functions (passed as a string, evaluated by gnuplot)
- GridData(m, x, y) -- data tabulated on a grid of (x,y) values (usually to be plotted in 3-D)
- GridFunc(f, xvals, yvals) -- a function f which is to be tabulated on a grid of (x,y) pairs.
See the documentation strings for those classes for more details.
PlotItems are implemented as objects that can be assigned to variables and plotted repeatedly. Most of their plot options can also be changed with the new set_option() member functions then they can be replotted with their new options.
Communication of commands to gnuplot is via a one-way pipe. Communication of data from python to gnuplot is via inline data (through the command pipe) or via temporary files. Temp files are deleted automatically when their associated PlotItem is deleted. The PlotItems in use by a Gnuplot object at any given time are stored in an internal list so that they won't be deleted prematurely.
Can use replot method to add datasets to an existing plot.
Can make persistent gnuplot windows by using the constructor option persist=1. Such windows stay around even after the gnuplot program is exited. Note that only newer version of gnuplot support this option.
Can plot either directly to a postscript printer or to a postscript file via the hardcopy method.
Grid data for the splot command can be sent to gnuplot in binary format, saving time and disk space.
Should work under either unix or Windows.

Restrictions:

Relies on the Numeric Python extension. This can be obtained from LLNL (See ftp://ftp-icf.llnl.gov/pub/python/README.html). If you're interested in gnuplot, you would probably also want NumPy anyway.
Only a small fraction of gnuplot functionality is implemented as explicit method functions. However, you can give arbitrary commands to gnuplot manually.
Example:
```
        g = Gnuplot.Gnuplot()
        g('set data style linespoints')
        g('set pointsize 5')
```
I might add a more organized way of setting arbitrary options, but there doesn't seem to be a pressing need for it.
There is no provision for missing data points in array data (which gnuplot would allow by specifying ? as a data point). I'm thinking about implementing this as an optional mask argument to the Data PlotItem. (Comments?)

Bugs:

No attempt is made to check for errors reported by gnuplot. On unix any gnuplot error messages simply appear on stderr. (I don't know what happens under Windows.)
All of these classes perform their resource deallocation when __del__ is called. Normally this works fine, but there are well-known cases when Python's automatic resource deallocation fails, which can leave temporary files around.

float_array(m)

Return the argument as a Numeric array of type at least 'Float32'.

Leave Float64 unchanged, but upcast all other types to Float32. Allow also for the possibility that the argument is a python native type that can be converted to a Numeric array using Numeric.asarray(), but in that case don't worry about downcasting to single-precision float.

grid_function(f, xvals, yvals, typecode=None, ufunc=0)

Evaluate and tabulate a function on a grid.

xvals and yvals should be 1-D arrays listing the values of x and y at which f should be tabulated. f should be a function taking two floating point arguments. The return value is a matrix M where M[i,j] = f(xvals[i],yvals[j]), which can for example be used in the GridData constructor.If ufunc=0, then f is evaluated at each pair of points using a Python loop. This can be slow if the number of points is large. If speed is an issue, you should write f in terms of Numeric ufuncs and use the ufunc=1 feature described next.If called with ufunc=1, then f should be a function that is composed entirely of ufuncs (i.e., a function that can operate element-by-element on whole matrices). It will be passed the xvals and yvals as rectangular matrices.

test_persist()

Determine whether gnuplot recognizes the option '-persist'.

If the configuration variable _recognizes_persist is set (i.e., to something other than 'None'), return that value. Otherwise, try to determine whether the installed version of gnuplot recognizes the -persist option. (If it doesn't, it should emit an error message with -persist in the first line.) Then set _recognizes_persist accordingly for future reference.

write_array(f, set, item_sep=' ', nest_prefix='', nest_suffix='\012', nest_sep='')

Write an array of arbitrary dimension to a file.

A general recursive array writer. The last four parameters allow a great deal of freedom in choosing the output format of the array. The defaults for those parameters give output that is gnuplot-readable. But using '(",", "{", "}", ", ")' would output an array in a format that Mathematica could read. item_sep should not contain % (or if it does, it should be escaped to '%%') since it is put into a format string.

The default 2-d file organization is, for example:

    set[0,0] set[0,1] ...
    set[1,0] set[1,1] ...

The 3-d format is, for example:

    set[0,0,0] set[0,0,1] ...
    set[0,1,0] set[0,1,1] ...    set[1,0,0] set[1,0,1] ...
    set[1,1,0] set[1,1,1] ...

Module Gnuplot

Description

Features:

Example:

Example:

Example:

Restrictions:

Example:

Bugs:

float_array(m)

grid_function(f, xvals, yvals, typecode=None, ufunc=0)

test_persist()

write_array(f, set, item_sep=' ', nest_prefix='', nest_suffix='\012', nest_sep='')

The default 2-d file organization is, for example:

The 3-d format is, for example: