1 # $Id: PlotItems.py 299 2007-03-30 12:52:17Z mhagger $
3 # Copyright (C) 1998-2003 Michael Haggerty <mhagger@alum.mit.edu>
5 # This file is licensed under the GNU Lesser General Public License
6 # (LGPL). See LICENSE.txt for details.
8 """PlotItems.py -- Objects that can be plotted by Gnuplot.
10 This module contains several types of PlotItems. PlotItems can be
11 plotted by passing them to a Gnuplot.Gnuplot object. You can derive
12 your own classes from the PlotItem hierarchy to customize their
17 import os
, string
, tempfile
, types
20 from cStringIO
import StringIO
22 from StringIO
import StringIO
26 import gp
, utils
, Errors
30 """Used to represent unset keyword arguments."""
36 """Plotitem represents an item that can be plotted by gnuplot.
38 For the finest control over the output, you can create 'PlotItems'
39 yourself with additional keyword options, or derive new classes
42 The handling of options is complicated by the attempt to allow
43 options and their setting mechanism to be inherited conveniently.
44 Note first that there are some options that can only be set in the
45 constructor then never modified, and others that can be set in the
46 constructor and/or modified using the 'set_option()' member
47 function. The former are always processed within '__init__'. The
48 latter are always processed within 'set_option', which is called
51 'set_option' is driven by a class-wide dictionary called
52 '_option_list', which is a mapping '{ <option> : <setter> }' from
53 option name to the function object used to set or change the
54 option. <setter> is a function object that takes two parameters:
55 'self' (the 'PlotItem' instance) and the new value requested for
56 the option. If <setter> is 'None', then the option is not allowed
57 to be changed after construction and an exception is raised.
59 Any 'PlotItem' that needs to add options can add to this
60 dictionary within its class definition. Follow one of the
61 examples in this file. Alternatively it could override the
62 'set_option' member function if it needs to do wilder things.
66 '_basecommand' -- a string holding the elementary argument that
67 must be passed to gnuplot's `plot' command for this item;
68 e.g., 'sin(x)' or '"filename.dat"'.
70 '_options' -- a dictionary of (<option>,<string>) tuples
71 corresponding to the plot options that have been set for
72 this instance of the PlotItem. <option> is the option as
73 specified by the user; <string> is the string that needs to
74 be set in the command line to set that option (or None if no
75 string is needed). Example::
77 {'title' : ('Data', 'title "Data"'),
78 'with' : ('linespoints', 'with linespoints')}
82 # For _option_list explanation, see docstring for PlotItem.
84 'axes' : lambda self
, axes
: self
.set_string_option(
85 'axes', axes
, None, 'axes %s'),
86 'with' : lambda self
, with_
: self
.set_string_option(
87 'with', with_
, None, 'with %s'),
88 'title' : lambda self
, title
: self
.set_string_option(
89 'title', title
, 'notitle', 'title "%s"'),
91 _option_list
['with_'] = _option_list
['with']
93 # order in which options need to be passed to gnuplot:
96 'index', 'every', 'thru', 'using', 'smooth',
97 'axes', 'title', 'with'
100 def __init__(self
, **keyw
):
101 """Construct a 'PlotItem'.
105 'with_=<string>' -- choose how item will be plotted, e.g.,
108 'title=<string>' -- set the title to be associated with the item
111 'title=None' -- choose 'notitle' option (omit item from legend).
113 Note that omitting the title option is different than setting
114 'title=None'; the former chooses gnuplot's default whereas the
115 latter chooses 'notitle'.
120 self
.set_option(**keyw
)
122 def get_option(self
, name
):
123 """Return the setting of an option. May be overridden."""
126 return self
._options
[name
][0]
128 raise KeyError('option %s is not set!' % name
)
130 def set_option(self
, **keyw
):
131 """Set or change a plot option for this PlotItem.
133 See documentation for '__init__' for information about allowed
134 options. This function can be overridden by derived classes
135 to allow additional options, in which case those options will
136 also be allowed by '__init__' for the derived class. However,
137 it is easier to define a new '_option_list' variable for the
142 for (option
, value
) in keyw
.items():
144 setter
= self
._option
_list
[option
]
146 raise Errors
.OptionError('%s=%s' % (option
,value
))
148 raise Errors
.OptionError(
149 'Cannot modify %s option after construction!', option
)
153 def set_string_option(self
, option
, value
, default
, fmt
):
154 """Set an option that takes a string value."""
157 self
._options
[option
] = (value
, default
)
158 elif type(value
) is types
.StringType
:
159 self
._options
[option
] = (value
, fmt
% value
)
161 Errors
.OptionError('%s=%s' % (option
, value
,))
163 def clear_option(self
, name
):
164 """Clear (unset) a plot option. No error if option was not set."""
167 del self
._options
[name
]
171 def get_base_command_string(self
):
172 raise NotImplementedError()
174 def get_command_option_string(self
):
176 for opt
in self
._option
_sequence
:
177 (val
,str) = self
._options
.get(opt
, (None,None))
180 return string
.join(cmd
)
183 """Build the plot command to be sent to gnuplot.
185 Build and return the plot command, with options, necessary to
186 display this item. If anything else needs to be done once per
187 plot, it can be done here too.
192 self
.get_base_command_string(),
193 self
.get_command_option_string(),
197 """Pipe necessary inline data to gnuplot.
199 If the plot command requires data to be put on stdin (i.e.,
200 'plot "-"'), this method should put that data there. Can be
201 overridden in derived classes.
208 class Func(PlotItem
):
209 """Represents a mathematical expression to plot.
211 Func represents a mathematical expression that is to be computed by
212 gnuplot itself, as if you would type for example::
216 into gnuplot itself. The argument to the contructor is a string
217 that should be a mathematical expression. Example::
219 g.plot(Func('sin(x)', with_='line 3'))
221 As shorthand, a string passed to the plot method of a Gnuplot
222 object is also treated as a Func::
228 def __init__(self
, function
, **keyw
):
229 PlotItem
.__init
__(self
, **keyw
)
230 self
.function
= function
232 def get_base_command_string(self
):
236 class _FileItem(PlotItem
):
237 """A PlotItem representing a file that contains gnuplot data.
239 This class is not meant for users but rather as a base class for
240 other types of FileItem.
244 _option_list
= PlotItem
._option
_list
.copy()
245 _option_list
.update({
246 'binary' : lambda self
, binary
: self
.set_option_binary(binary
),
247 'index' : lambda self
, value
: self
.set_option_colonsep('index', value
),
248 'every' : lambda self
, value
: self
.set_option_colonsep('every', value
),
249 'using' : lambda self
, value
: self
.set_option_colonsep('using', value
),
250 'smooth' : lambda self
, smooth
: self
.set_string_option(
251 'smooth', smooth
, None, 'smooth %s'
255 def __init__(self
, filename
, **keyw
):
256 """Represent a PlotItem that gnuplot treates as a file.
258 This class holds the information that is needed to construct
259 the plot command line, including options that are specific to
260 file-like gnuplot input.
262 <filename> is a string representing the filename to be passed
263 to gnuplot within quotes. It may be the name of an existing
264 file, '-' for inline data, or the name of a named pipe.
268 'using=<int>' -- plot that column against line number
270 'using=<tuple>' -- plot using a:b:c:d etc. Elements in
271 the tuple that are None are output as the empty
274 'using=<string>' -- plot `using <string>' (allows gnuplot's
275 arbitrary column arithmetic)
277 'every=<value>' -- plot 'every <value>'. <value> is
278 formatted as for 'using' option.
280 'index=<value>' -- plot 'index <value>'. <value> is
281 formatted as for 'using' option.
283 'binary=<boolean>' -- data in the file is in binary format
284 (this option is only allowed for grid data for splot).
286 'smooth=<string>' -- smooth the data. Option should be
287 'unique', 'csplines', 'acsplines', 'bezier', or
290 The keyword arguments recognized by 'PlotItem' can also be
293 Note that the 'using' option is interpreted by gnuplot, so
294 columns must be numbered starting with 1.
296 By default, gnuplot uses the name of the file plus any 'using'
297 option as the dataset title. If you want another title, set
298 it explicitly using the 'title' option.
302 self
.filename
= filename
304 PlotItem
.__init
__(self
, **keyw
)
306 def get_base_command_string(self
):
307 return gp
.double_quote_string(self
.filename
)
309 def set_option_colonsep(self
, name
, value
):
311 self
.clear_option(name
)
312 elif type(value
) in [types
.StringType
, types
.IntType
]:
313 self
._options
[name
] = (value
, '%s %s' % (name
, value
,))
314 elif type(value
) is types
.TupleType
:
320 subopts
.append(str(subopt
))
321 self
._options
[name
] = (
323 '%s %s' % (name
, string
.join(subopts
, ':'),),
326 raise Errors
.OptionError('%s=%s' % (name
, value
,))
328 def set_option_binary(self
, binary
):
330 if not gp
.GnuplotOpts
.recognizes_binary_splot
:
331 raise Errors
.OptionError(
332 'Gnuplot.py is currently configured to reject binary data')
333 self
._options
['binary'] = (1, 'binary')
335 self
._options
['binary'] = (0, None)
338 class _NewFileItem(_FileItem
):
339 def __init__(self
, content
, filename
=None, **keyw
):
341 binary
= keyw
.get('binary', 0)
348 # This is a permanent file
350 f
= open(filename
, mode
)
353 if hasattr(tempfile
, 'mkstemp'):
354 # Use the new secure method of creating temporary files:
355 (fd
, filename
,) = tempfile
.mkstemp(
356 suffix
='.gnuplot', text
=(not binary
)
358 f
= os
.fdopen(fd
, mode
)
360 # for backwards compatibility to pre-2.3:
361 filename
= tempfile
.mktemp()
362 f
= open(filename
, mode
)
367 # If the user hasn't specified a title, set it to None so
368 # that the name of the temporary file is not used:
369 if self
.temp
and 'title' not in keyw
:
372 _FileItem
.__init
__(self
, filename
, **keyw
)
376 os
.unlink(self
.filename
)
379 class _InlineFileItem(_FileItem
):
380 """A _FileItem that actually indicates inline data.
384 def __init__(self
, content
, **keyw
):
385 # If the user hasn't specified a title, set it to None so that
387 if 'title' not in keyw
:
390 if keyw
.get('binary', 0):
391 raise Errors
.OptionError('binary inline data is not supported')
393 _FileItem
.__init
__(self
, '-', **keyw
)
395 if content
[-1] == '\n':
396 self
.content
= content
398 self
.content
= content
+ '\n'
401 f
.write(self
.content
+ 'e\n')
404 if gp
.GnuplotOpts
.support_fifo
:
407 class _FIFOWriter(threading
.Thread
):
408 """Create a FIFO (named pipe), write to it, then delete it.
410 The writing takes place in a separate thread so that the main
411 thread is not blocked. The idea is that once the writing is
412 finished we know that gnuplot is done with the data that were in
413 the file so we can delete the file. This technique removes the
414 ambiguity about when the temporary files should be deleted.
416 Since the tempfile module does not provide an easy, secure way
417 to create a FIFO without race conditions, we instead create a
418 temporary directory using mkdtemp() then create the FIFO
419 within that directory. When the writer thread has written the
420 full information to the FIFO, it deletes both the FIFO and the
421 temporary directory that contained it.
425 def __init__(self
, content
, mode
='w'):
426 self
.content
= content
428 if hasattr(tempfile
, 'mkdtemp'):
429 # Make the file within a temporary directory that is
431 self
.dirname
= tempfile
.mkdtemp(suffix
='.gnuplot')
432 self
.filename
= os
.path
.join(self
.dirname
, 'fifo')
434 # For backwards compatibility pre-2.3, just use
435 # mktemp() to create filename:
437 self
.filename
= tempfile
.mktemp()
438 threading
.Thread
.__init
__(
440 name
=('FIFO Writer for %s' % (self
.filename
,)),
442 os
.mkfifo(self
.filename
)
446 f
= open(self
.filename
, self
.mode
)
447 f
.write(self
.content
)
449 os
.unlink(self
.filename
)
450 if self
.dirname
is not None:
451 os
.rmdir(self
.dirname
)
454 class _FIFOFileItem(_FileItem
):
455 """A _FileItem based on a FIFO (named pipe).
457 This class depends on the availablity of os.mkfifo(), which only
462 def __init__(self
, content
, **keyw
):
463 # If the user hasn't specified a title, set it to None so that
464 # the name of the temporary FIFO is not used:
465 if 'title' not in keyw
:
468 _FileItem
.__init
__(self
, '', **keyw
)
469 self
.content
= content
470 if keyw
.get('binary', 0):
475 def get_base_command_string(self
):
476 """Create the gnuplot command for plotting this item.
478 The basecommand is different each time because each FIFOWriter
483 # Create a new FIFO and a thread to write to it. Retrieve the
484 # filename of the FIFO to be used in the basecommand.
485 fifo
= _FIFOWriter(self
.content
, self
.mode
)
486 return gp
.double_quote_string(fifo
.filename
)
489 def File(filename
, **keyw
):
490 """Construct a _FileItem object referring to an existing file.
492 This is a convenience function that just returns a _FileItem that
495 <filename> is a string holding the filename of an existing file.
496 The keyword arguments are the same as those of the _FileItem
501 if type(filename
) is not types
.StringType
:
502 raise Errors
.OptionError(
503 'Argument (%s) must be a filename' % (filename
,)
505 return _FileItem(filename
, **keyw
)
508 def Data(*data
, **keyw
):
509 """Create and return a _FileItem representing the data from *data.
511 Create a '_FileItem' object (which is a type of 'PlotItem') out of
512 one or more Float Python numpy arrays (or objects that can be
513 converted to a float numpy array). If the routine is passed a
514 single with multiple dimensions, then the last index ranges over
515 the values comprising a single data point (e.g., [<x>, <y>,
516 <sigma>]) and the rest of the indices select the data point. If
517 passed a single array with 1 dimension, then each point is
518 considered to have only one value (i.e., by default the values
519 will be plotted against their indices). If the routine is passed
520 more than one array, they must have identical shapes, and then
521 each data point is composed of one point from each array. E.g.,
522 'Data(x,x**2)' is a 'PlotItem' that represents x squared as a
523 function of x. For the output format, see the comments for
526 How the data are written to gnuplot depends on the 'inline'
527 argument and preference settings for the platform in use.
531 'cols=<tuple>' -- write only the specified columns from each
532 data point to the file. Since cols is used by python, the
533 columns should be numbered in the python style (starting
534 from 0), not the gnuplot style (starting from 1).
536 'inline=<bool>' -- transmit the data to gnuplot 'inline'
537 rather than through a temporary file. The default is the
538 value of gp.GnuplotOpts.prefer_inline_data.
540 'filename=<string>' -- save data to a permanent file.
542 The keyword arguments recognized by '_FileItem' can also be used
548 # data was passed as a single structure
549 data
= utils
.float_array(data
[0])
551 # As a special case, if passed a single 1-D array, then it is
552 # treated as one value per point (by default, plotted against
554 if len(data
.shape
) == 1:
555 data
= data
[:,numpy
.newaxis
]
557 # data was passed column by column (for example,
558 # Data(x,y)); pack it into one big array (this will test
559 # that sizes are all the same):
560 data
= utils
.float_array(data
)
563 dims
= len(data
.shape
)
564 # transpose so that the last index selects x vs. y:
565 data
= numpy
.transpose(data
, (dims
-1,) + tuple(range(dims
-1)))
569 if isinstance(cols
, types
.IntType
):
571 data
= numpy
.take(data
, cols
, -1)
573 if 'filename' in keyw
:
574 filename
= keyw
['filename'] or None
580 inline
= keyw
['inline']
582 if inline
and filename
:
583 raise Errors
.OptionError(
584 'cannot pass data both inline and via a file'
587 inline
= (not filename
) and gp
.GnuplotOpts
.prefer_inline_data
589 # Output the content into a string:
591 utils
.write_array(f
, data
)
592 content
= f
.getvalue()
594 return _InlineFileItem(content
, **keyw
)
596 return _NewFileItem(content
, filename
=filename
, **keyw
)
597 elif gp
.GnuplotOpts
.prefer_fifo_data
:
598 return _FIFOFileItem(content
, **keyw
)
600 return _NewFileItem(content
, **keyw
)
604 data
, xvals
=None, yvals
=None, inline
=_unset
, filename
=None, **keyw
606 """Return a _FileItem representing a function of two variables.
608 'GridData' represents a function that has been tabulated on a
609 rectangular grid. The data are written to a file; no copy is kept
614 'data' -- the data to plot: a 2-d array with dimensions
617 'xvals' -- a 1-d array with dimension 'numx'
619 'yvals' -- a 1-d array with dimension 'numy'
621 'binary=<bool>' -- send data to gnuplot in binary format?
623 'inline=<bool>' -- send data to gnuplot "inline"?
625 'filename=<string>' -- save data to a permanent file.
627 Note the unusual argument order! The data are specified *before*
628 the x and y values. (This inconsistency was probably a mistake;
629 after all, the default xvals and yvals are not very useful.)
631 'data' must be a data array holding the values of a function
632 f(x,y) tabulated on a grid of points, such that 'data[i,j] ==
633 f(xvals[i], yvals[j])'. If 'xvals' and/or 'yvals' are omitted,
634 integers (starting with 0) are used for that coordinate. The data
635 are written to a temporary file; no copy of the data is kept in
638 If 'binary=0' then the data are written to a datafile as 'x y
639 f(x,y)' triplets (y changes most rapidly) that can be used by
640 gnuplot's 'splot' command. Blank lines are included each time the
641 value of x changes so that gnuplot knows to plot a surface through
644 If 'binary=1' then the data are written to a file in a binary
645 format that 'splot' can understand. Binary format is faster and
646 usually saves disk space but is not human-readable. If your
647 version of gnuplot doesn't support binary format (it is a
648 recently-added feature), this behavior can be disabled by setting
649 the configuration variable
650 'gp.GnuplotOpts.recognizes_binary_splot=0' in the appropriate
653 Thus if you have three arrays in the above format and a Gnuplot
654 instance called g, you can plot your data by typing
655 'g.splot(Gnuplot.GridData(data,xvals,yvals))'.
659 # Try to interpret data as an array:
660 data
= utils
.float_array(data
)
662 (numx
, numy
) = data
.shape
664 raise Errors
.DataError('data array must be two-dimensional')
667 xvals
= numpy
.arange(numx
)
669 xvals
= utils
.float_array(xvals
)
670 if xvals
.shape
!= (numx
,):
671 raise Errors
.DataError(
672 'The size of xvals must be the same as the size of '
673 'the first dimension of the data array')
676 yvals
= numpy
.arange(numy
)
678 yvals
= utils
.float_array(yvals
)
679 if yvals
.shape
!= (numy
,):
680 raise Errors
.DataError(
681 'The size of yvals must be the same as the size of '
682 'the second dimension of the data array')
684 # Binary defaults to true if recognizes_binary_plot is set;
685 # otherwise it is forced to false.
686 binary
= keyw
.get('binary', 1) and gp
.GnuplotOpts
.recognizes_binary_splot
687 keyw
['binary'] = binary
691 (not binary
) and (not filename
)
692 and gp
.GnuplotOpts
.prefer_inline_data
694 elif inline
and filename
:
695 raise Errors
.OptionError(
696 'cannot pass data both inline and via a file'
699 # xvals, yvals, and data are now all filled with arrays of data.
702 raise Errors
.OptionError('binary inline data not supported')
704 # write file in binary format
706 # It seems that the gnuplot documentation for binary mode
707 # disagrees with its actual behavior (as of v. 3.7). The
708 # documentation has the roles of x and y exchanged. We ignore
709 # the documentation and go with the code.
711 mout
= numpy
.zeros((numy
+ 1, numx
+ 1), numpy
.float32
)
713 mout
[0,1:] = xvals
.astype(numpy
.float32
)
714 mout
[1:,0] = yvals
.astype(numpy
.float32
)
716 # try copying without the additional copy implied by astype():
717 mout
[1:,1:] = numpy
.transpose(data
)
719 # if that didn't work then downcasting from double
721 mout
[1:,1:] = numpy
.transpose(data
.astype(numpy
.float32
))
723 content
= mout
.tostring()
724 if (not filename
) and gp
.GnuplotOpts
.prefer_fifo_data
:
725 return _FIFOFileItem(content
, **keyw
)
727 return _NewFileItem(content
, filename
=filename
, **keyw
)
729 # output data to file as "x y f(x)" triplets. This
730 # requires numy copies of each x value and numx copies of
731 # each y value. First reformat the data:
732 set = numpy
.transpose(
734 (numpy
.transpose(numpy
.resize(xvals
, (numy
, numx
))),
735 numpy
.resize(yvals
, (numx
, numy
)),
738 # Now output the data with the usual routine. This will
739 # produce data properly formatted in blocks separated by blank
740 # lines so that gnuplot can connect the points into a grid.
742 utils
.write_array(f
, set)
743 content
= f
.getvalue()
746 return _InlineFileItem(content
, **keyw
)
748 return _NewFileItem(content
, filename
=filename
, **keyw
)
749 elif gp
.GnuplotOpts
.prefer_fifo_data
:
750 return _FIFOFileItem(content
, **keyw
)
752 return _NewFileItem(content
, **keyw
)