PyFoam.ThirdParty.Gnuplot.PlotItems module

PlotItems.py – Objects that can be plotted by Gnuplot.

This module contains several types of PlotItems. PlotItems can be plotted by passing them to a Gnuplot.Gnuplot object. You can derive your own classes from the PlotItem hierarchy to customize their behavior.

PyFoam.ThirdParty.Gnuplot.PlotItems.Data(*data, **keyw)[source]

Create and return a _FileItem representing the data from *data.

Create a ‘_FileItem’ object (which is a type of ‘PlotItem’) out of one or more Float Python numpy arrays (or objects that can be converted to a float numpy array). If the routine is passed a single with multiple dimensions, then the last index ranges over the values comprising a single data point (e.g., [<x>, <y>, <sigma>]) and the rest of the indices select the data point. If passed a single array with 1 dimension, then each point is considered to have only one value (i.e., by default the values will be plotted against their indices). If the routine is passed more than one array, they must have identical shapes, and then each data point is composed of one point from each array. E.g., ‘Data(x,x**2)’ is a ‘PlotItem’ that represents x squared as a function of x. For the output format, see the comments for ‘write_array()’.

How the data are written to gnuplot depends on the ‘inline’ argument and preference settings for the platform in use.

Keyword arguments:

‘cols=<tuple>’ – write only the specified columns from each

data point to the file. Since cols is used by python, the columns should be numbered in the python style (starting from 0), not the gnuplot style (starting from 1).

‘inline=<bool>’ – transmit the data to gnuplot ‘inline’

rather than through a temporary file. The default is the value of gp.GnuplotOpts.prefer_inline_data.

‘filename=<string>’ – save data to a permanent file.

The keyword arguments recognized by ‘_FileItem’ can also be used here.

PyFoam.ThirdParty.Gnuplot.PlotItems.File(filename, **keyw)[source]

Construct a _FileItem object referring to an existing file.

This is a convenience function that just returns a _FileItem that wraps the filename.

<filename> is a string holding the filename of an existing file. The keyword arguments are the same as those of the _FileItem constructor.

class PyFoam.ThirdParty.Gnuplot.PlotItems.Func(function, **keyw)[source]

Bases: PyFoam.ThirdParty.Gnuplot.PlotItems.PlotItem

Represents a mathematical expression to plot.

Func represents a mathematical expression that is to be computed by gnuplot itself, as if you would type for example:

gnuplot> plot sin(x)

into gnuplot itself. The argument to the contructor is a string that should be a mathematical expression. Example:

g.plot(Func('sin(x)', with_='line 3'))

As shorthand, a string passed to the plot method of a Gnuplot object is also treated as a Func:

g.plot('sin(x)')
__init__(function, **keyw)[source]

Construct a ‘PlotItem’.

Keyword options:

‘with_=<string>’ – choose how item will be plotted, e.g.,

with_=’points 3 3’.

‘title=<string>’ – set the title to be associated with the item

in the plot legend.

‘title=None’ – choose ‘notitle’ option (omit item from legend).

Note that omitting the title option is different than setting ‘title=None’; the former chooses gnuplot’s default whereas the latter chooses ‘notitle’.

__module__ = 'PyFoam.ThirdParty.Gnuplot.PlotItems'
get_base_command_string()[source]
PyFoam.ThirdParty.Gnuplot.PlotItems.GridData(data, xvals=None, yvals=None, inline=<class 'PyFoam.ThirdParty.Gnuplot.PlotItems._unset'>, filename=None, **keyw)[source]

Return a _FileItem representing a function of two variables.

‘GridData’ represents a function that has been tabulated on a rectangular grid. The data are written to a file; no copy is kept in memory.

Arguments:

‘data’ – the data to plot: a 2-d array with dimensions

(numx,numy).

‘xvals’ – a 1-d array with dimension ‘numx’

‘yvals’ – a 1-d array with dimension ‘numy’

‘binary=<bool>’ – send data to gnuplot in binary format?

‘inline=<bool>’ – send data to gnuplot “inline”?

‘filename=<string>’ – save data to a permanent file.

Note the unusual argument order! The data are specified before the x and y values. (This inconsistency was probably a mistake; after all, the default xvals and yvals are not very useful.)

‘data’ must be a data array holding the values of a function f(x,y) tabulated on a grid of points, such that ‘data[i,j] == f(xvals[i], yvals[j])’. If ‘xvals’ and/or ‘yvals’ are omitted, integers (starting with 0) are used for that coordinate. The data are written to a temporary file; no copy of the data is kept in memory.

If ‘binary=0’ then the data are written to a datafile as ‘x y f(x,y)’ triplets (y changes most rapidly) that can be used by gnuplot’s ‘splot’ command. Blank lines are included each time the value of x changes so that gnuplot knows to plot a surface through the data.

If ‘binary=1’ then the data are written to a file in a binary format that ‘splot’ can understand. Binary format is faster and usually saves disk space but is not human-readable. If your version of gnuplot doesn’t support binary format (it is a recently-added feature), this behavior can be disabled by setting the configuration variable ‘gp.GnuplotOpts.recognizes_binary_splot=0’ in the appropriate gp*.py file.

Thus if you have three arrays in the above format and a Gnuplot instance called g, you can plot your data by typing ‘g.splot(Gnuplot.GridData(data,xvals,yvals))’.

class PyFoam.ThirdParty.Gnuplot.PlotItems.PlotItem(**keyw)[source]

Bases: object

Plotitem represents an item that can be plotted by gnuplot.

For the finest control over the output, you can create ‘PlotItems’ yourself with additional keyword options, or derive new classes from ‘PlotItem’.

The handling of options is complicated by the attempt to allow options and their setting mechanism to be inherited conveniently. Note first that there are some options that can only be set in the constructor then never modified, and others that can be set in the constructor and/or modified using the ‘set_option()’ member function. The former are always processed within ‘__init__’. The latter are always processed within ‘set_option’, which is called by the constructor.

‘set_option’ is driven by a class-wide dictionary called ‘_option_list’, which is a mapping ‘{ <option> : <setter> }’ from option name to the function object used to set or change the option. <setter> is a function object that takes two parameters: ‘self’ (the ‘PlotItem’ instance) and the new value requested for the option. If <setter> is ‘None’, then the option is not allowed to be changed after construction and an exception is raised.

Any ‘PlotItem’ that needs to add options can add to this dictionary within its class definition. Follow one of the examples in this file. Alternatively it could override the ‘set_option’ member function if it needs to do wilder things.

Members:

‘_basecommand’ – a string holding the elementary argument that

must be passed to gnuplot’s `plot’ command for this item; e.g., ‘sin(x)’ or ‘“filename.dat”’.

‘_options’ – a dictionary of (<option>,<string>) tuples

corresponding to the plot options that have been set for this instance of the PlotItem. <option> is the option as specified by the user; <string> is the string that needs to be set in the command line to set that option (or None if no string is needed). Example:

{'title' : ('Data', 'title "Data"'),
 'with' : ('linespoints', 'with linespoints')}
__dict__ = mappingproxy({'__module__': 'PyFoam.ThirdParty.Gnuplot.PlotItems', '__doc__': 'Plotitem represents an item that can be plotted by gnuplot.\n\n For the finest control over the output, you can create \'PlotItems\'\n yourself with additional keyword options, or derive new classes\n from \'PlotItem\'.\n\n The handling of options is complicated by the attempt to allow\n options and their setting mechanism to be inherited conveniently.\n Note first that there are some options that can only be set in the\n constructor then never modified, and others that can be set in the\n constructor and/or modified using the \'set_option()\' member\n function. The former are always processed within \'__init__\'. The\n latter are always processed within \'set_option\', which is called\n by the constructor.\n\n \'set_option\' is driven by a class-wide dictionary called\n \'_option_list\', which is a mapping \'{ <option> : <setter> }\' from\n option name to the function object used to set or change the\n option. <setter> is a function object that takes two parameters:\n \'self\' (the \'PlotItem\' instance) and the new value requested for\n the option. If <setter> is \'None\', then the option is not allowed\n to be changed after construction and an exception is raised.\n\n Any \'PlotItem\' that needs to add options can add to this\n dictionary within its class definition. Follow one of the\n examples in this file. Alternatively it could override the\n \'set_option\' member function if it needs to do wilder things.\n\n Members:\n\n \'_basecommand\' -- a string holding the elementary argument that\n must be passed to gnuplot\'s `plot\' command for this item;\n e.g., \'sin(x)\' or \'"filename.dat"\'.\n\n \'_options\' -- a dictionary of (<option>,<string>) tuples\n corresponding to the plot options that have been set for\n this instance of the PlotItem. <option> is the option as\n specified by the user; <string> is the string that needs to\n be set in the command line to set that option (or None if no\n string is needed). Example::\n\n {\'title\' : (\'Data\', \'title "Data"\'),\n \'with\' : (\'linespoints\', \'with linespoints\')}\n\n ', '_option_list': {'axes': <function PlotItem.<lambda>>, 'with': <function PlotItem.<lambda>>, 'title': <function PlotItem.<lambda>>, 'with_': <function PlotItem.<lambda>>}, '_option_sequence': ['binary', 'index', 'every', 'thru', 'using', 'smooth', 'axes', 'title', 'with'], '__init__': <function PlotItem.__init__>, 'get_option': <function PlotItem.get_option>, 'set_option': <function PlotItem.set_option>, 'set_string_option': <function PlotItem.set_string_option>, 'clear_option': <function PlotItem.clear_option>, 'get_base_command_string': <function PlotItem.get_base_command_string>, 'get_command_option_string': <function PlotItem.get_command_option_string>, 'command': <function PlotItem.command>, 'pipein': <function PlotItem.pipein>, '__dict__': <attribute '__dict__' of 'PlotItem' objects>, '__weakref__': <attribute '__weakref__' of 'PlotItem' objects>})
__init__(**keyw)[source]

Construct a ‘PlotItem’.

Keyword options:

‘with_=<string>’ – choose how item will be plotted, e.g.,

with_=’points 3 3’.

‘title=<string>’ – set the title to be associated with the item

in the plot legend.

‘title=None’ – choose ‘notitle’ option (omit item from legend).

Note that omitting the title option is different than setting ‘title=None’; the former chooses gnuplot’s default whereas the latter chooses ‘notitle’.

__module__ = 'PyFoam.ThirdParty.Gnuplot.PlotItems'
__weakref__

list of weak references to the object (if defined)

_option_list = {'axes': <function PlotItem.<lambda>>, 'title': <function PlotItem.<lambda>>, 'with': <function PlotItem.<lambda>>, 'with_': <function PlotItem.<lambda>>}
_option_sequence = ['binary', 'index', 'every', 'thru', 'using', 'smooth', 'axes', 'title', 'with']
clear_option(name)[source]

Clear (unset) a plot option. No error if option was not set.

command()[source]

Build the plot command to be sent to gnuplot.

Build and return the plot command, with options, necessary to display this item. If anything else needs to be done once per plot, it can be done here too.

get_base_command_string()[source]
get_command_option_string()[source]
get_option(name)[source]

Return the setting of an option. May be overridden.

pipein(f)[source]

Pipe necessary inline data to gnuplot.

If the plot command requires data to be put on stdin (i.e., ‘plot “-“’), this method should put that data there. Can be overridden in derived classes.

set_option(**keyw)[source]

Set or change a plot option for this PlotItem.

See documentation for ‘__init__’ for information about allowed options. This function can be overridden by derived classes to allow additional options, in which case those options will also be allowed by ‘__init__’ for the derived class. However, it is easier to define a new ‘_option_list’ variable for the derived class.

set_string_option(option, value, default, fmt)[source]

Set an option that takes a string value.

class PyFoam.ThirdParty.Gnuplot.PlotItems._FIFOFileItem(content, **keyw)[source]

Bases: PyFoam.ThirdParty.Gnuplot.PlotItems._FileItem

A _FileItem based on a FIFO (named pipe).

This class depends on the availablity of os.mkfifo(), which only exists under Unix.

__init__(content, **keyw)[source]

Represent a PlotItem that gnuplot treates as a file.

This class holds the information that is needed to construct the plot command line, including options that are specific to file-like gnuplot input.

<filename> is a string representing the filename to be passed to gnuplot within quotes. It may be the name of an existing file, ‘-‘ for inline data, or the name of a named pipe.

Keyword arguments:

‘using=<int>’ – plot that column against line number

‘using=<tuple>’ – plot using a:b:c:d etc. Elements in

the tuple that are None are output as the empty string.

‘using=<string>’ – plot `using <string>’ (allows gnuplot’s

arbitrary column arithmetic)

‘every=<value>’ – plot ‘every <value>’. <value> is

formatted as for ‘using’ option.

‘index=<value>’ – plot ‘index <value>’. <value> is

formatted as for ‘using’ option.

‘binary=<boolean>’ – data in the file is in binary format

(this option is only allowed for grid data for splot).

‘smooth=<string>’ – smooth the data. Option should be

‘unique’, ‘csplines’, ‘acsplines’, ‘bezier’, or ‘sbezier’.

The keyword arguments recognized by ‘PlotItem’ can also be used here.

Note that the ‘using’ option is interpreted by gnuplot, so columns must be numbered starting with 1.

By default, gnuplot uses the name of the file plus any ‘using’ option as the dataset title. If you want another title, set it explicitly using the ‘title’ option.

__module__ = 'PyFoam.ThirdParty.Gnuplot.PlotItems'
get_base_command_string()[source]

Create the gnuplot command for plotting this item.

The basecommand is different each time because each FIFOWriter creates a new FIFO.

class PyFoam.ThirdParty.Gnuplot.PlotItems._FIFOWriter(content, mode='w')[source]

Bases: threading.Thread

Create a FIFO (named pipe), write to it, then delete it.

The writing takes place in a separate thread so that the main thread is not blocked. The idea is that once the writing is finished we know that gnuplot is done with the data that were in the file so we can delete the file. This technique removes the ambiguity about when the temporary files should be deleted.

Since the tempfile module does not provide an easy, secure way to create a FIFO without race conditions, we instead create a temporary directory using mkdtemp() then create the FIFO within that directory. When the writer thread has written the full information to the FIFO, it deletes both the FIFO and the temporary directory that contained it.

__init__(content, mode='w')[source]

This constructor should always be called with keyword arguments. Arguments are:

group should be None; reserved for future extension when a ThreadGroup class is implemented.

target is the callable object to be invoked by the run() method. Defaults to None, meaning nothing is called.

name is the thread name. By default, a unique name is constructed of the form “Thread-N” where N is a small decimal number.

args is the argument tuple for the target invocation. Defaults to ().

kwargs is a dictionary of keyword arguments for the target invocation. Defaults to {}.

If a subclass overrides the constructor, it must make sure to invoke the base class constructor (Thread.__init__()) before doing anything else to the thread.

__module__ = 'PyFoam.ThirdParty.Gnuplot.PlotItems'
run()[source]

Method representing the thread’s activity.

You may override this method in a subclass. The standard run() method invokes the callable object passed to the object’s constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.

class PyFoam.ThirdParty.Gnuplot.PlotItems._FileItem(filename, **keyw)[source]

Bases: PyFoam.ThirdParty.Gnuplot.PlotItems.PlotItem

A PlotItem representing a file that contains gnuplot data.

This class is not meant for users but rather as a base class for other types of FileItem.

__init__(filename, **keyw)[source]

Represent a PlotItem that gnuplot treates as a file.

This class holds the information that is needed to construct the plot command line, including options that are specific to file-like gnuplot input.

<filename> is a string representing the filename to be passed to gnuplot within quotes. It may be the name of an existing file, ‘-‘ for inline data, or the name of a named pipe.

Keyword arguments:

‘using=<int>’ – plot that column against line number

‘using=<tuple>’ – plot using a:b:c:d etc. Elements in

the tuple that are None are output as the empty string.

‘using=<string>’ – plot `using <string>’ (allows gnuplot’s

arbitrary column arithmetic)

‘every=<value>’ – plot ‘every <value>’. <value> is

formatted as for ‘using’ option.

‘index=<value>’ – plot ‘index <value>’. <value> is

formatted as for ‘using’ option.

‘binary=<boolean>’ – data in the file is in binary format

(this option is only allowed for grid data for splot).

‘smooth=<string>’ – smooth the data. Option should be

‘unique’, ‘csplines’, ‘acsplines’, ‘bezier’, or ‘sbezier’.

The keyword arguments recognized by ‘PlotItem’ can also be used here.

Note that the ‘using’ option is interpreted by gnuplot, so columns must be numbered starting with 1.

By default, gnuplot uses the name of the file plus any ‘using’ option as the dataset title. If you want another title, set it explicitly using the ‘title’ option.

__module__ = 'PyFoam.ThirdParty.Gnuplot.PlotItems'
_option_list = {'axes': <function PlotItem.<lambda>>, 'binary': <function _FileItem.<lambda>>, 'every': <function _FileItem.<lambda>>, 'index': <function _FileItem.<lambda>>, 'smooth': <function _FileItem.<lambda>>, 'title': <function PlotItem.<lambda>>, 'using': <function _FileItem.<lambda>>, 'with': <function PlotItem.<lambda>>, 'with_': <function PlotItem.<lambda>>}
get_base_command_string()[source]
set_option_binary(binary)[source]
set_option_colonsep(name, value)[source]
class PyFoam.ThirdParty.Gnuplot.PlotItems._InlineFileItem(content, **keyw)[source]

Bases: PyFoam.ThirdParty.Gnuplot.PlotItems._FileItem

A _FileItem that actually indicates inline data.

__init__(content, **keyw)[source]

Represent a PlotItem that gnuplot treates as a file.

This class holds the information that is needed to construct the plot command line, including options that are specific to file-like gnuplot input.

<filename> is a string representing the filename to be passed to gnuplot within quotes. It may be the name of an existing file, ‘-‘ for inline data, or the name of a named pipe.

Keyword arguments:

‘using=<int>’ – plot that column against line number

‘using=<tuple>’ – plot using a:b:c:d etc. Elements in

the tuple that are None are output as the empty string.

‘using=<string>’ – plot `using <string>’ (allows gnuplot’s

arbitrary column arithmetic)

‘every=<value>’ – plot ‘every <value>’. <value> is

formatted as for ‘using’ option.

‘index=<value>’ – plot ‘index <value>’. <value> is

formatted as for ‘using’ option.

‘binary=<boolean>’ – data in the file is in binary format

(this option is only allowed for grid data for splot).

‘smooth=<string>’ – smooth the data. Option should be

‘unique’, ‘csplines’, ‘acsplines’, ‘bezier’, or ‘sbezier’.

The keyword arguments recognized by ‘PlotItem’ can also be used here.

Note that the ‘using’ option is interpreted by gnuplot, so columns must be numbered starting with 1.

By default, gnuplot uses the name of the file plus any ‘using’ option as the dataset title. If you want another title, set it explicitly using the ‘title’ option.

__module__ = 'PyFoam.ThirdParty.Gnuplot.PlotItems'
pipein(f)[source]

Pipe necessary inline data to gnuplot.

If the plot command requires data to be put on stdin (i.e., ‘plot “-“’), this method should put that data there. Can be overridden in derived classes.

class PyFoam.ThirdParty.Gnuplot.PlotItems._NewFileItem(content, filename=None, **keyw)[source]

Bases: PyFoam.ThirdParty.Gnuplot.PlotItems._FileItem

__del__()[source]
__init__(content, filename=None, **keyw)[source]

Represent a PlotItem that gnuplot treates as a file.

This class holds the information that is needed to construct the plot command line, including options that are specific to file-like gnuplot input.

<filename> is a string representing the filename to be passed to gnuplot within quotes. It may be the name of an existing file, ‘-‘ for inline data, or the name of a named pipe.

Keyword arguments:

‘using=<int>’ – plot that column against line number

‘using=<tuple>’ – plot using a:b:c:d etc. Elements in

the tuple that are None are output as the empty string.

‘using=<string>’ – plot `using <string>’ (allows gnuplot’s

arbitrary column arithmetic)

‘every=<value>’ – plot ‘every <value>’. <value> is

formatted as for ‘using’ option.

‘index=<value>’ – plot ‘index <value>’. <value> is

formatted as for ‘using’ option.

‘binary=<boolean>’ – data in the file is in binary format

(this option is only allowed for grid data for splot).

‘smooth=<string>’ – smooth the data. Option should be

‘unique’, ‘csplines’, ‘acsplines’, ‘bezier’, or ‘sbezier’.

The keyword arguments recognized by ‘PlotItem’ can also be used here.

Note that the ‘using’ option is interpreted by gnuplot, so columns must be numbered starting with 1.

By default, gnuplot uses the name of the file plus any ‘using’ option as the dataset title. If you want another title, set it explicitly using the ‘title’ option.

__module__ = 'PyFoam.ThirdParty.Gnuplot.PlotItems'
class PyFoam.ThirdParty.Gnuplot.PlotItems._unset[source]

Bases: object

Used to represent unset keyword arguments.

__dict__ = mappingproxy({'__module__': 'PyFoam.ThirdParty.Gnuplot.PlotItems', '__doc__': 'Used to represent unset keyword arguments.', '__dict__': <attribute '__dict__' of '_unset' objects>, '__weakref__': <attribute '__weakref__' of '_unset' objects>})
__module__ = 'PyFoam.ThirdParty.Gnuplot.PlotItems'
__weakref__

list of weak references to the object (if defined)