class Gnuplot - Interface to a gnuplot program.

Declared in module Gnuplot

Synopsis

class Gnuplot:
    def __call__(self, s) # Send a command string to gnuplot.
    def __del__(self) # Disconnect from the gnuplot process (causing it to exit).
    def __init__(self, filename=None, persist=0, debug=0) # Create a Gnuplot object.
    def _add_to_queue(self, items) # Add a list of items to the itemlist (but don't plot them).
    def _clear_queue(self) # Clear the PlotItems from the queue.
    def clear(self) # Clear the plot window (without affecting the current itemlist).
    def hardcopy(self, filename=None, eps=0, color=0, enhanced=1) # Create a hardcopy of the current plot.
    def interact(self) # Allow user to type arbitrary commands to gnuplot.
    def load(self, filename) # Load a file using gnuplot's 'load' command.
    def plot(self, *items) # Draw a new plot.
    def refresh(self) # Refresh the plot, using the current PlotItems.
    def replot(self, *items) # Replot the data, possibly adding new PlotItems.
    def reset(self) # Reset all gnuplot settings to their defaults and clear itemlist.
    def save(self, filename) # Save the current plot commands using gnuplot's 'save' command.
    def set_string(self, option, s=None) # Set a string option, or if s is omitted, unset the option.
    def splot(self, *items) # Draw a new three-dimensional plot.
    def title(self, s=None) # Set the plot's title.
    def xlabel(self, s=None) # Set the plot's xlabel.
    def ylabel(self, s=None) # Set the plot's ylabel.

Description

A Gnuplot represents a running gnuplot program and a pipe to communicate with it. It can plot 'PlotItem's, which represent each thing to be plotted on the current graph. It keeps a reference to each of the PlotItems used in the current plot, so that they (and their associated temporary files) are not deleted prematurely. The communication is one-way; gnuplot's text output just goes to stdout with no attempt to check it for error messages.

Members:

gnuplot: the pipe to gnuplot or a file gathering the commands
itemlist: a list of the PlotItems that are associated with the current plot. These are deleted whenever a new plot command is issued via the `plot' method.
debug: if this flag is set, commands sent to gnuplot will also be echoed to stderr.
plotcmd: plot or splot, depending on what was the last plot command.

Methods:

__init__: if a filename argument is specified, the commands will be written to that file instead of being piped to gnuplot.
plot: clear the old plot and old PlotItems, then plot the arguments in a fresh plot command. Arguments can be: a PlotItem, which is plotted along with its internal options; a string, which is plotted as a Func; or anything else, which is plotted as a Data.
splot: like plot, except for 3-d plots.
hardcopy: replot the plot to a postscript file (if filename argument is specified) or pipe it to the printer as postscript othewise. If the option `color' is set to true, then output color postscript.
replot: replot the old items, adding any arguments as additional items as in the plot method.
refresh: issue (or reissue) the plot command using the current PlotItems.
__call__: pass an arbitrary string to the gnuplot process, followed by a newline.
xlabel, ylabel, title: set corresponding plot attribute.
interact: read lines from stdin and send them, one by one, to the gnuplot interpreter. Basically you can type commands directly to the gnuplot command processor.
load: load a file (using the gnuplot `load' command).
save: save gnuplot commands to a file (using gnuplot `save' command) If any of the PlotItems is a temporary file, it will be deleted at the usual time and the save file will be pretty useless :-).
clear: clear the plot window (but not the itemlist).
reset: reset all gnuplot settings to their defaults and clear the current itemlist.
set_string: set or unset a gnuplot option whose value is a string.
_clear_queue: clear the current PlotItem list.
_add_to_queue: add the specified items to the current PlotItem list.

call(self, s)

Send a command string to gnuplot.

Send the string s as a command to gnuplot, followed by a newline and flush. All communication with the gnuplot process (except for inline data) is through this method.

init(self, filename=None, persist=0, debug=0)

Create a Gnuplot object.

Create a Gnuplot object. By default, this starts a gnuplot process and prepares to write commands to it.

Keyword arguments:

filename=<string>: if a filename is specified, the commands are instead written to that file (e.g., for later use using 'load').
persist=1: start gnuplot with the -persist option (which creates a new plot window for each plot command). (This option is not available on older versions of gnuplot.)
debug=1: echo the gnuplot commands to stderr as well as sending them to gnuplot.

_add_to_queue(self, items)

Add a list of items to the itemlist (but don't plot them).

items is a sequence of items, each of which should be a PlotItem of some kind, a string (interpreted as a function string for gnuplot to evaluate), or a Numeric array (or something that can be converted to a Numeric array).

hardcopy(self, filename=None, eps=0, color=0, enhanced=1)

Create a hardcopy of the current plot.

Create a postscript hardcopy of the current plot.

Keyword arguments:

filename=<string>: if a filename is specified, save the output in that file; otherwise print it immediately using the _default_lpr command.
eps=<bool>: if eps is set, generate encapsulated postscript using gnuplot's set term post eps.
color=<bool>: if color is set, create a plot with color.
enhanced=<bool>: if enhanced is set (the default), then generate enhanced postscript, which allows extra features like font-switching in axis labels. (Some old gnuplot versions do not support enhanced postscript; if this is the case set enhanced=0.)

Note that this command will return immediately even though it might take gnuplot a while to actually finish working. Be sure to pause briefly before issuing another command that might cause the temporary files to be deleted.

interact(self)

Allow user to type arbitrary commands to gnuplot.

Read stdin, line by line, and send each line as a command to gnuplot. End by typing C-d.

plot(self, *items)

Draw a new plot.

Clear the current plot and create a new 2-d plot containing the specified items. Each arguments should be of the following types:

PlotItem (e.g., Data, File, 'Func'): This is the most flexible way to call plot because the PlotItems can contain suboptions. Moreover, PlotItems can be saved to variables so that their lifetime is longer than one plot command; thus they can be replotted with minimal overhead.
string (e.g., 'sin(x)'): The string is interpreted as Func(string) (a function that is computed by gnuplot).
Anything else: The object, which should be convertible to an array, is converted to a Data item, and thus plotted as data. If the conversion fails, an exception is raised.

refresh(self)

Refresh the plot, using the current PlotItems.

Refresh the current plot by reissuing the gnuplot plot command corresponding to the current itemlist.

replot(self, *items)

Replot the data, possibly adding new PlotItems.

Replot the existing graph, using the items in the current itemlist. If arguments are specified, they are interpreted as additional items to be plotted alongside the existing items on the same graph. See plot for details.

splot(self, *items)

Draw a new three-dimensional plot.

Clear the current plot and create a new 3-d plot containing the specified items. Arguments can be of the following types:

PlotItem (e.g., Data, File, Func, GridData ): This is the most flexible way to call plot because the PlotItems can contain suboptions. Moreover, PlotItems can be saved to variables so that their lifetime is longer than one plot command--thus they can be replotted with minimal overhead.
string (e.g., 'sin(x*y)'): The string is interpreted as a Func() (a function that is computed by gnuplot).
Anything else: The object is converted to a Data() item, and thus plotted as data. Note that each data point should normally have at least three values associated with it (i.e., x, y, and z). If the conversion fails, an exception is raised.