NAME¶
PDL::Graphics::Gnuplot - Gnuplot-based plotting for PDL
SYNOPSIS¶
pdl> use PDL::Graphics::Gnuplot;
pdl> $x = sequence(101) - 50;
pdl> gplot($x**2);
pdl> gplot($x**2,{xr=>[0,50]});
pdl> gplot( {title => 'Parabola with error bars'},
with => 'xyerrorbars', legend => 'Parabola',
$x**2 * 10, abs($x)/10, abs($x)*5 );
pdl> $xy = zeroes(21,21)->ndcoords - pdl(10,10);
pdl> $z = inner($xy, $xy);
pdl> gplot({title => 'Heat map',
trid => 1,
view => [0,0]
},
with => 'image', xvals($z),yvals($z),zeroes($z),$z*2
);
pdl> $w = gpwin(); # constructor
pdl> $pi = 3.14159;
pdl> $theta = zeroes(200)->xlinvals(0, 6*$pi);
pdl> $z = zeroes(200)->xlinvals(0, 5);
pdl> $w->plot3d(cos($theta), sin($theta), $z);
pdl> $w->terminfo(); # get information
DESCRIPTION¶
This module allows PDL data to be plotted using Gnuplot as a backend for 2D and
3D plotting and image display. Gnuplot (not affiliated with the Gnu project)
is a venerable, open-source program that produces both interactive and
publication-quality plots on many different output devices. It is available
through most Linux repositories, on MacOS, and from its website
<
http://www.gnuplot.info>.
It is not necessary to understand the gnuplot syntax to generate basic, or even
complex, plots - though the full syntax is available for advanced users who
want the full flexibility of the Gnuplot backend.
Gnuplot recognizes both hard-copy and interactive plotting devices, and on
interactive devices (like X11) it is possible to pan, scale, and rotate both
2-D and 3-D plots interactively. You can also enter graphical data through
mouse clicks on the device window. On some hardcopy devices (e.g.
"PDF") that support multipage output, it is necessary to close the
device after plotting to ensure a valid file is written out.
"PDL::Graphics::Gnuplot" exports two routines by default: a
constructor, "gpwin()" and a general purpose plot routine,
"gplot()". Depending on options, "gplot()" can produce
line plots, scatterplots, error boxes, "candlesticks", images, or
any overlain combination of these elements; or perspective views of 3-D
renderings such as surface plots.
A call to "gplot()" looks like:
gplot({temp_plot_options}, # optional hash ref
curve_options, data, data, ... ,
curve_options, data, data, ... );
The data entries are columns to be plotted. They are normally an optional
ordinate and a required abscissa, but some plot modes can use more columns
than that. The collection of columns is called a "tuple". Each
column must be a separate PDL or an ARRAY ref. If all the columns are PDLs,
you can add extra dimensions to make threaded collections of curves.
PDL::Graphics::Gnuplot also implements an object oriented interface. Plot
objects track individual gnuplot subprocesses. Direct calls to
"gplot()" are tracked through a global object that stores globally
set configuration variables.
The "gplot()" sub (or the "plot()" method) collects two
kinds of options hash:
plot options, which describe the overall
structure of the plot being produced (e.g. axis specifications, window size,
and title), and
curve options, which describe the behavior of
individual traces or collections of points being plotted. In addition, the
module itself supports options that allow direct pass-through of plotting
commands to the underlying gnuplot process.
Basic plotting¶
Gnuplot generates many kinds of plot, from basic line plots and histograms to
scaled labels. Individual plots can be 2-D or 3-D, and different sets of plot
styles are supported in each mode. Plots can be sent to a variety of devices;
see the description of plot options, below.
You select a plot style with the "with" curve option, and feed in
columns of data (usually ordinate followed by abscissa). The collection of
columns is called a "tuple". These plots have two columns in their
tuples:
$x = xvals(51)-25; $y = $x**2;
gplot(with=>'points', $x, $y); # Draw points on a parabola
gplot(with=>'lines', $x, $y); # Draw a parabola
gplot({title=>"Parabolic fit"},
with=>"yerrorbars", legend=>"data", $x, $y+(random($y)-0.5)*2*$y/20, pdl($y/20),
with=>"lines", legend=>"fit", $x, $y);
Normal threading rules apply across the arguments to a given plot.
All data are required to be supplied as either PDLs or list refs. If you use a
list ref as a data column, then normal threading is disabled. For example:
$x = xvals(5);
$y = xvals(5)**2;
$labels = ['one','two','three','four','five'];
gplot(with=>'labels',$x,$y,$labels);
See below for supported curve styles.
Modifying plots
Gnuplot is built around a monolithic plot model - it is not possible to add new
data directly to a plot without redrawing the entire plot. To support
replotting, PDL::Graphics::Gnuplot stores the data you plot in the plot
object, so that you can add new data with the "replot" command:
$w=gpwin(x11);
$x=xvals(101)/100;
$y=$x;
$w->plot($x,$y);
$w->replot($x,$y*$y);
For speed, the data are *not* disconnected from their original variables - so
this will plot X vs. sqrt(X):
$x = xvals(101)/100;
$y = xvals(101)/100;
$w->plot($x,$y);
$y->inplace->sqrt;
$w->replot();
Image plotting
Several of the plot styles accept image data. The tuple parameters work the same
way as for basic plots, but each "column" is a 2-D PDL rather than a
1-D PDL. As a special case, the "with image" plot style accepts
either a 2-D or a 3-D PDL. If you pass in 3-D PDL, the extra dimension can
have size 1, 3, or 4. It is interpreted as running across (R,G,B,A) color
planes.
3-D plotting
You can plot in 3-D by setting the plot option "trid" to a true value.
Three dimensional plots accept either 1-D or 2-D PDLs as data columns. If you
feed in 2-D "columns", many of the common plot styles will
generalize appropriately to 3-D. For example, to plot a 2-D surface as a line
grid, you can use the "lines" style and feed in 2-D columns instead
of 1-D columns.
Enhanced text¶
Most gnuplot output devices include the option to markup "enhanced
text". That means text is interpreted so that you can change its font and
size, and insert superscripts and subscripts into labels. Codes are:
- {}
- Text grouping - enclose text in braces to group characters, as in
LaTeX.
- ^
- Superscript the next character or group (shrinks it slightly too where
that is supported).
- _
- Subscript the next character or group (shrinks it slightly too where that
is supported).
- @
- Phantom box (occupies no width; controls height for super- and
subscripting)
- &
- Controllable-width space, e.g. &{template-string}
- ~
- overstrike -- e.g. ~a{0.8-} overprints '-' on 'a', raised by
0.8xfontsize.
- {/[fontname][=fontsize | *fontscale] text}
- Change font to (optional) fontname, and optional absolute font size or
relative font scale ("fontsize" and "fontscale" are
numbers). The space after the size parameter is not rendered.
- \
- Backslash escapes control characters to render them as themselves.
Color specification¶
There are several contexts where you can specify color of plot elements. In
those places, you can specify colors exactly as in the Gnuplot manual, or more
tersely. In general, a color spec can be any one of the following:
- - an integer
- This specifies a recognizable unique color in the same order as used by
the plotting engine.
- - the name of a color
- (e.g. "blue"). Supported color names are listed in the variable
@Alien::Gnuplot::colors.
- - an RGB value string
- Strings have the form "#RRGGBB", where the "#" is
literal and the RR, GG, and BB are hexadecimal bytes.
- - the word "palette"
- "palette" indicates that color is to be drawn from the scaled
colorbar palette (which you can set with the "clut" plot
option), by lookup using an additional column in the associated data
tuple.
- - the word "variable"
- "variable" indicates that color is to be drawn from the integer
plotting colors used by the plotting engine, indexed by an additional
column in the associated data tuple.
- - the phrase "rgb variable"
- "rgb variable" indicates that color is to be directly specified
by a 24 bit integer specifying 8-bit values for (from most significant
byte to least significant byte) R, G, and B in the output color. The
integer is drawn from an additional column in the associated data
tuple.
Plot styles supported¶
Gnuplot itself supports a wide range of plot styles, and all are supported by
PDL::Graphics::Gnuplot. Most of the basic plot styles collect tuples of 1-D
columns in 2-D mode (for ordinary plots), or either 1-D or 2-D
"columns" in 3-D mode (for grid surface plots and such). Image modes
always collect tuples made of 2-D "columns".
You can pass in 1-D columns as either PDLs or ARRAY refs. That is important for
plot types (such as "labels") that require a collection of strings
rather than numeric data.
Each plot style can by modified to support particular colors or line style
options. These modifications get passed in as curve options (see below). For
example, to plot a blue line you can use
"with=>'lines',lc=>'blue'". To match the autogenerated style
of a particular line you can use the "ls" curve option.
The GNuplot plot styles supported are:
- •
- "boxerrorbars" - combo of "boxes" and
"yerrorbars", below (2D)
- •
- "boxes" - simple boxes around regions on the plot (2D)
- •
- "boxxyerrorbars" - Render X and Y error bars as boxes (2D)
- •
- "candlesticks" - Y error bars with inner and outer limits
(2D)
- •
- "circles" - circles with variable radius at each point:
X/Y/radius (2D)
- •
- "dots" - tiny points ("dots") at each point, e.g. for
scatterplots (2D/3D)
- •
- "ellipses" - ellipses. Accepts X/Y/major/minor/angle (2D)
- •
- "filledcurves" - closed polygons or axis-to-line filled shapes
(2D)
- •
- "financebars" - financial style plot. Accepts
date/open/low/high/close (2D)
- •
- "fsteps" - square bin plot; delta-Y, then delta-X (see
"steps", "histeps") (2D)
- •
- "histeps" - square bin plot; plateaus centered on X coords (see
"fsteps", "steps") (2D)
- •
- "histogram" - binned histogram of dataset (not direct plot; see
"newhistogram") (2D)
- •
- "fits" - (PDL-specific) renders FITS image files in scientific
coordinates
- •
- "image" - Takes (i), (x,y,i), or (x,y,z,i). See
"rgbimage", "rgbalpha", "fits". (2D/3D)
- •
- "impulses" - vertical line from axis to the plotted point
(2D/3D)
- •
- "labels" - Text labels at specified locations all over the plot
(2D/3D)
- •
- "lines" - regular line plot (2D/3D)
- •
- "linespoints" - line plot with symbols at plotted points
(2D/3D)
- •
- "newhistogram" - multiple-histogram-friendly histogram style
(see "histogram") (2D)
- •
- "points" - symbols at plotted points (2D/3D)
- •
- "rgbalpha" - R/G/B color image with variable transparency
(2D/3D)
- •
- "rgbimage" - R/G/B color image (2D/3D)
- •
- "steps" - square bin plot; delta-X, then delta-Y (see
"fsteps", "histeps") (2D)
- •
- "vectors" - Small arrows: (x,y,[z]) -> (x+dx,y+dy,[z+dz])
(2D/3D)
- •
- "xerrorbars" - points with X error bars ("T" form)
(2D)
- •
- "xyerrorbars" - points with both X and Y error bars
("T" form) (2D)
- •
- "yerrorbars" - points with Y error bars ("T" form)
(2D)
- •
- "xerrorlines" - line plot with X errorbars at each point.
(2D)
- •
- "xyerrorlines" - line plot with XY errorbars at each point.
(2D)
- •
- "yerrorlines" - line plot with Y error limits at each point.
(2D)
- •
- "pm3d" - three-dimensional variable-position surface plot
Options arguments¶
The plot options are parameters that affect the whole plot, like the title of
the plot, the axis labels, the extents, 2d/3d selection, etc. All the plot
options are described below in "Plot options". Plot options can be
set in the plot object, or passed to the plotting methods directly. Plot
options can be passed in as a leading interpolated hash, as a leading hash
ref, or as a trailing hash ref in the argument list to any of the main
plotting routines ("gplot", "plot", "image",
etc.).
The curve options are parameters that affect only one curve in particular. Each
call to "plot()" can contain many curves, and options for a
particular curve
precede the data for that curve in the argument list.
The actual type of curve (the "with" option) is persistent, but all
other curve options and modifiers are not. An example:
gplot( with => 'points', $x, $a,
{axes=> x1y2}, $x, $b,
with => 'lines', $x, $c );
This plots 3 curves: $a vs. $x plotted with points on the main y-axis (this is
the default), $b vs. $x plotted with points on the secondary y axis, and $c
vs. $x plotted with lines on the main y-axis (the default). Note that the
curve options can be supplied as either an inline hash or a hash ref.
All the curve options are described below in "Curve options".
If you want to plot multiple curves of the same type without setting any curve
options explicitly, you must include an empty hash ref between the tuples for
subsequent lines, as in:
gplot( $x, $a, {}, $x, $b, {}, $x, $c );
Data arguments¶
Following the curve options in the "plot()" argument list is the
actual data being plotted. Each output data point is a "tuple" whose
size varies depending on what is being plotted. For example if we're making a
simple 2D x-y plot, each tuple has 2 values; if we're making a 3d plot with
each point having variable size and color, each tuple has 5 values
(x,y,z,size,color). Each tuple element must be passed separately. For ordinary
2-D plots, the 0 dim of the tuple elements runs across plotted point. PDL
threading is active, so you can plot multiple curves with similar curve
options on a normal 2-D plot, just by stacking data inside the passed-in PDLs.
(An exception is that threading is disabled if one or more of the data
elements is a list ref).
PDLs vs list refs
The usual way to pass in data is as a PDL -- one PDL per column of data in the
tuple. But strings, in particular, cannot easily be hammered into PDLs.
Therefore any column in each tuple can be a list ref containing values (either
numeric or string). The column is interpreted using the usual polymorphous
cast-behind-your-back behavior of Perl. For the sake of sanity, if even one
list ref is present in a tuple, then threading is disabled in that tuple:
everything has to have a nice 1-D shape.
Implicit domains
When making a simple 2D plot, if exactly 1 dimension is missing,
PDL::Graphics::Gnuplot will use sequence(N) as the domain. This is why code
like "plot(pdl(1,5,3,4,4) )" works. Only one PDL is given here, but
the plot type ("lines" by default) requires 2 elements per tuple. We
are thus exactly 1 piddle short; sequence(5) is used as the missing domain
PDL. This is thus equivalent to "plot(sequence(5), pdl(1,5,3,4,4)
)".
If plotting in 3d or displaying an image, an implicit domain will be used if we
are exactly 2 piddles short. In this case, PDL::Graphics::Gnuplot will use a
2D grid as a domain. Example:
my $xy = zeros(21,21)->ndcoords - pdl(10,10);
gplot({'3d' => 1},
with => 'points', inner($xy, $xy));
gplot( with => 'image', sin(rvals(51,51)) );
Here the only given piddle has dimensions (21,21). This is a 3D plot, so we are
exactly 2 piddles short. Thus, PDL::Graphics::Gnuplot generates an implicit
domain, corresponding to a 21-by-21 grid.
"PDL::Graphics::Gnuplot" requires explicit separators between tuples
for different plots, so it is always clear from the arguments you pass in just
how many columns you are supplying. For example, "plot($a,$b)" will
plot $b vs. $a. If you actually want to plot an overlay of both $a and $b
against array index, you want "plot($a,{},$b)" instead. The
"{}" is a hash ref containing a collection of all the curve options
that you are changing between the two curves -- in this case, zero of them.
Images¶
PDL::Graphics::Gnuplot supports four styles of image plot, via the
"with" curve option.
The "image" style accepts a single image plane and displays it using
the palette (pseudocolor map) that is specified in the plot options for that
plot. As a special case, if you supply as data a (WxHx3) PDL it is treated as
an RGB image and displayed with the "rgbimage" style (below). For
quick image display there is also an "image" method:
use PDL::Graphics::Gnuplot qw/image/;
$im = sin(rvals(51,51)/2);
image( $im ); # display the image
gplot( with=>'image', $im ); # display the image (longer form)
The colors are autoscaled in both cases. To set a particular color range, use
the 'cbrange' plot option:
image( {cbrange=>[0,1]}, $im );
You can plot rgb images directly with the image style, just by including a 3rd
dimension of size 3 on your image:
$rgbim = pdl( xvals($im), yvals($im),rvals($im)/sqrt(2));
image( $rgbim ); # display an RGB image
gplot( with=>'image', $rgbim ); # display an RGB image (longer form)
Some additional plot styles exist to specify RGB and RGB transparent forms
directly. These are the "with" styles "rgbimage" and
"rgbalpha". For each of them you must specify the channels as
separate PDLs:
gplot( with=>'rgbimage', $rgbim->dog ); # RGB the long way
gplot( with=>'rgbalpha', $rgbim->dog, ($im>0) ); # RGBA the long way
According to the gnuplot specification you can also give X and Y values for each
pixel, as in
gplot( with=>'image', xvals($im), yvals($im), $im )
but this appears not to work properly for anything more complicated than a
trivial matrix of X and Y values.
PDL::Graphics::Gnuplot provides a "fits" plot style that interprets
World Coordinate System (WCS) information supplied in the header of the
scientific image format FITS. The image is displayed in rectified scientific
coordinates, rather than in pixel coordinates. You can plot FITS images in
scientific coordinates with
gplot( with=>'fits', $fitsdata );
The fits plot style accepts a modifier "resample" (which may be
abbreviated), that allows you to downsample and/or rectify the image before it
is passed to the Gnuplot back-end. This is useful either to cut down on the
burden of transferring large blocks of image data or to rectify images with
nonlinear WCS transformations in their headers. (gnuplot itself has a bug that
prevents direct rendering of images in nonlinear coordinates).
gplot( with=>'fits res 200', $fitsdata );
gplot( with=>'fits res 100,400',$fitsdata );
to specify that the output are to be resampled onto a square 200x200 grid or a
100x400 grid, respectively. The resample sizes must be positive integers.
Interactivity¶
Several of the graphical backends of Gnuplot are interactive, allowing you to
pan, zoom, rotate and measure the data interactively in the plot window. See
the Gnuplot documentation for details about how to do this. Some terminals
(such as "wxt") are persistently interactive. Other terminals (such
as "x11") maintain their interactivity only while the underlying
gnuplot process is active -- i.e. until another plot is created with the same
PDL::Graphics::Gnuplot object, or until the perl process exits (whichever
comes first). Still others (the hardcopy devices) aren't interactive at all.
Some interactive devices (notably "wxt" and "x11") also
support mouse input: you can write PDL scripts that accept and manipulate
graphical input from the plotted window.
PLOT OPTIONS¶
Gnuplot controls plot style with "plot options" that configure and
specify virtually all aspects of the plot to be produced. Plot options are
tracked as stored state in the PDL::Graphics::Gnuplot object. You can set them
by passing them in to the constructor, to an "options" method, or to
the "plot" method itself.
Nearly all the underlying Gnuplot plot options are supported, as well as some
additional options that are parsed by the module itself for convenience.
There are many, many plot options. For convenience, we've grouped them by
general category below. Each group has a heading "POs for
<foo>", describing the category. You can skip below them all if you
want to read about curve options or other aspects of PDL::Graphics::Gnuplot.
POs for Output: terminal, termoption, output, device, hardcopy¶
You can send plots to a variety of different devices; Gnuplot calls devices
"terminals". With the object-oriented interface, you must set the
output device with the constructor "PDL::Graphics::Gnuplot::new" (or
the exported constructor "gpwin") or the "output" method.
If you use the simple non-object interface, you can set the output with the
"terminal", "termoption", and "output" plot
options.
"terminal" sets the output device type for Gnuplot, and
"output" sets the actual output file or window number.
"device" and "hardcopy" are for convenience.
"device" offers a PGPLOT-style device specifier in
"filename/device" format (the "filename" gets sent to the
"output" option, the "device" gets sent to the
"terminal" option). "hardcopy" takes an output file name,
attempts to parse out a file suffix and infer a device type.
"hardcopy" also uses a common set of terminal options needed to fill
an entire letter page with a plot.
For finer grained control of the plotting environment, you can send
"terminal options" to Gnuplot. If you set the terminal directly with
plot options, you can include terminal options by interpolating them into a
string, as in "terminal jpeg interlace butt crop", or you can use
the constructor "new" (also exported as "gpwin"), which
parses terminal options as an argument list.
The routine "PDL::Graphics::Gnuplot::terminfo" prints a list of all
availale terminals or, if you pass in a terminal name, options accepted by
that terminal.
POs for Titles¶
The options described here are
- title
- xlabel
- x2label
- ylabel
- y2label
- zlabel
- cblabel
- key
Gnuplot supports "enhanced" text escapes on most terminals; see
"text", below.
The "title" option lets you set a title for the whole plot.
Individual plot components are labeled with the "label" options.
"xlabel", "x2label", "ylabel", and
"y2label" specify axis titles for 2-D plots. The "zlabel"
works for 3-D plots. The "cblabel" option sets the label for the
color box, in plot types that have one (e.g. image display).
(Don't be confused by "clabel", which doesnt' set a label at all,
rather specifies the printf format used by contour labels in contour plots.)
"key" controls where the plot key (that relates line/symbol style to
label) is placed on the plot. It takes a scalar boolean indicating whether to
turn the key on (with default values) or off, or a list ref containing any of
the following arguments (all are optional) in the order listed:
- •
- ( on | off ) - turn the key on or off
- •
- ( inside | outside | lmargin | rmargin | tmargin | bmargin | at
<pos> )
These keywords set the location of the key -- "inside/outside" is
relative to the plot border; the margin keywords indicate location in the
margins of the plot; and at <pos> (where <pos> is a 2-list
containing (x,y): "key=>[at=>[0.5,0.5]]") is an exact
location to place the key.
- •
- ( left | right | center ) ( top | bottom | center ) - horiz./vert.
alignment
- •
- ( vertical | horizontal ) - stacking direction within the key
- •
- ( Left | Right ) - justification of plot labels within the key (note
case)
- •
- [no]reverse - switch order of label and sample line
- •
- [no]invert - invert the stack order of the labels
- •
- samplen <length> - set the length of the sample lines
- •
- spacing <dist> - set the spacing between adjacent labels in the
list
- •
- [no]autotitle - control whether labels are generated when not
specified
- •
- title "<text>" - set a title for the key
- •
- [no]enhanced - override terminal settings for enhanced text
interpretation
- •
- font "<face>,<size>" - set font for the labels
- •
- textcolor <colorspec>
- •
- [no]box linestyle <ls> linetype <lt> linewidth <lw> -
control box around the key
POs for axes, grids, & borders¶
The options described here are
- grid
- xzeroaxis
- x2zeroaxis
- yzeroaxis
- y2zeroaxis
- zzeroaxis
- border
Normally, tick marks and their labels are applied to the border of a plot, and
no extra axes (e.g. the y=0 line) nor coordinate grids are shown. You can
specify which (if any) zero axes should be drawn, and which (if any) borders
should be drawn.
The "border" option controls whether the plot itself has a border
drawn around it. You can feed it a scalar boolean value to indicate whether
borders should be drawn around the plot -- or you can feed in a list ref
containing options. The options are all optional but must be supplied in the
order given.
- •
- <integer> - packed bit flags for which border lines to draw
The default if you set a true value for "border" is to draw all
border lines. You can feed in a single integer value containing a bit
mask, to draw only some border lines. From LSB to MSB, the coded lines are
bottom, left, top, right for 2D plots -- e.g. 5 will draw bottom and top
borders but neither left nor right.
In three dimensions, 12 bits are used to describe the twelve edges of a cube
surrounding the plot. In groups of three, the first four control the
bottom (xy) plane edges in the same order as in the 2-D plots; the middle
four control the vertical edges that rise from the clockwise end of the
bottom plane edges; and the last four control the top plane edges.
- •
- ( back | front ) - draw borders first or last (controls hidden line
appearance)
- •
- linewidth <lw>, linestyle <ls>, linetype <lt>
These are Gnuplot's usual three options for line control.
The "grid" option indicates whether gridlines should be drawn on each
axis. It takes a list ref of arguments, each of which is either "no"
or "m" or "", followed by an axis name and
"tics" -- e.g.
"grid=>["noxtics","ymtics"]" draws no X
gridlines and draws (horizontal) Y gridlines on Y axis major and minor tics,
while "grid=>["xtics","ytics"]" or
"grid=>["xtics ytics"]" will draw both vertical (X) and
horizontal (Y) grid lines on major tics.
To draw a coordinate grid with default values, set "grid=>1". For
more control, feed in a list ref with zero or more of the following
parameters, in order:
The "zeroaxis" keyword indicates whether to actually draw each axis
line at the corresponding zero along its indicated dimension. For example, to
draw the X axis (y=0), use "xzeroaxis=>1". If you just want the
axis turned on with default values, you can feed in a Boolean scalar; if you
want to set its parameters, you can feed in a list ref containing linewidth,
linestyle, and linetype (with appropriate parameters for each), e.g.
"xzeroaxis=>[linewidth=>2]".
POs for axis range and mode¶
The options described here are
- xrange
- x2range
- yrange
- y2range
- zrange
- rrange
- cbrange
- trange
- urange
- vrange
- autoscale
- logscale
Gnuplot accepts explicit ranges as plot options for all axes. Each option
accepts a list ref with (min, max). If either min or max is missing, then the
opposite limit is autoscaled. The x and y ranges refer to the usual ordinate
and abscissa of the plot; x2 and y2 refer to alternate ordinate and abscissa;
z if for 3-D plots; r is for polar plots; t, u, and v are for parametric
plots. cb is for the color box on plots that include it (see
"color", below).
"rrange" is used for radial coordinates (which are accessible using
the "mapping" plot option, below).
"cbrange" (for 'color box range') sets the range of values over which
palette colors (either gray or pseudocolor) are matched. It is valid in any
color-mapped plot (including images or palette-mapped lines or points), even
if no color box is being displayed for this plot.
"trange", "urange", and "vrange" set ranges for
the parametric coordinates if you are plotting a parametric curve.
By default all axes are autoscaled unless you specify a range on that axis, and
partially (min or max) autoscaled if you specify a partial range on that axis.
"autoscale" allows more explicit control of how autoscaling is
performed, on an axis-by-axis basis. It accepts a list ref, each element of
which specifies how a single axis should be autoscaled. Each element contains
an axis name followed by one of
"fix,"min","max","fixmin", or
"fixmax", e.g.
autoscale=>['xmax','yfix']
To not autoscale an axis at all, specify a range for it. The fix style of
autoscaling forces the autoscaler to use the actual min/max of the data as the
limit for the corresponding axis -- by default the axis gets extended to the
next minor tic (as set by the autoticker or by a tic specification, see
below).
"logscale" allows you to turn on logarithmic scaling for any or all
axes, and to set the base of the logarithm. It takes a list ref, the first
element of which is a string mushing together the names of all the axes to
scale logarithmically, and the second of which is the base of the logarithm:
"logscale=>[xy=>10]". You can also leave off the base if you
want base-10 logs: "logscale=>['xy']".
POs for Axis tick marks¶
The options described here are
- xtics
- x2tics
- ytics
- y2tics
- ztics
- cbtics
- mxtics
- mx2tics
- mytics
- my2tics
- mztics
- mcbtics
Axis tick marks are called "tics" within Gnuplot, and they are
extensively controllable via the "{axis}tics" options. In
particular, major and minor ticks are supported, as are arbitrarily variable
length ticks, non-equally spaced ticks, and arbitrarily labelled ticks.
Support exists for time formatted ticks (see "POs for time data
values" below).
By default, gnuplot will automatically place major and minor ticks. You can turn
off ticks on an axis by setting the appropriate {foo}tics option to a defined,
false scalar value (e.g. "xtics=>0"). If you want to set major
tics to happen at a regular specified intervals, you can set the appropriate
tics option to a nonzero scalar value (e.g. "xtics=>2" to specify
a tic every 2 units on the X axis). To use default values for the tick
positioning, specify an empty hash or array ref (e.g.
"xtics=>{}"), or a string containing only whitespace (e.g.
"<xtics="' '>>).
If you prepend an 'm' to any tics option, it affects minor tics instead of major
tics (major tics typically show units; minor tics typically show fractions of
a unit).
Each tics option can accept a hash ref containing options to pass to Gnuplot.
You can also pass in a snippet of gnuplot command, as either a string or an
array ref -- but those techniques are deprecated and may disappear in a future
version of "PDL:Graphics::Gnuplot".
The keywords are case-insensitive and may be abbreviated, just as with other
option types. They are:
- •
- axis - set to 1 to place tics on the axis (the default)
- •
- border - set to 1 to place tics on the border (not the default)
- •
- mirror - set to 1 to place mirrored tics on the opposite axis/border (the
default, unless an alternate axis interferes -- e.g. y2)
- •
- in - set to 1 to draw tics inward from the axis/border
- •
- out - set to 1 to draw tics outward from the axis/border
- •
- scale - multiplier on tic length compared to the default
If you pass in undef, tics get the default length. If you pass in a scalar,
major tics get scaled. You can pass in an array ref to scale minor tics
too.
- •
- rotate - turn label text by the given angle (in degrees) on the drawing
plane
- •
- offset - offset label text from default position, (units: characters;
requires array ref containing x,y)
- •
- locations - sets tic locations. Gets an array ref: [incr], [start, incr],
or [start, incr, stop].
- •
- labels - sets tic locations explicitly, with text labels for each. If you
specify both "locations" and "labels", you get both
sets of tics on the same axis.
The labels should be a nested list ref that is a collection of duals or
triplets. Each dual or triplet should contain [label, position,
minorflag], as in
"<labels="[["one",1,0],["three-halves",1.5,1],["two",2,0]]>>.
- •
- format - printf-style format string for tic labels. There are some
extensions to the gnuplot format tags -- see the gnuplot manual. Gnuplot
4.8 and higher have %h, which works like %g but uses extended text
formatting if it is available.
- •
- font - set font name and size (system font name)
- •
- rangelimited - set to 1 to limit tics to the range of values actually
present in the plot
- •
- textcolor - set the color of the ticks (see "color specs"
below)
For example, to turn on inward mirrored X axis ticks with diagonal Arial 9 text,
use:
xtics => {axis=>1,mirror=>1,in=>1,rotate=>45,font=>'Arial,9'}
or
xtics => ['axis','mirror','in','rotate by 45','font "Arial,9"']
POs for time data values¶
The options described here are
- xmtics
- x2mtics
- ymtics
- y2mtics
- zmtics
- cbmtics
- xdtics
- x2dtics
- ydtics
- y2dtics
- zdtics
- cbdtics
- xdata
- x2data
- ydata
- y2data
- zdata
- cbdata
Gnuplot contains support for plotting absolute time and date on any of its axes,
with conventional formatting. There are three main methods, which are mutually
exclusive (i.e. you should not attempt to use two at once on the same axis).
- Plotting timestamps using UNIX times
- You can set any axis to plot timestamps rather than numeric values by
setting the corresponding "data" plot option to
"time", e.g. "<xdata=""time">>. If
you do so, then numeric values in the corresponding data are interpreted
as UNIX time (seconds since the UNIX epoch, neglecting leap seconds). No
provision is made for UT"-"TAI conversion. You can format how
the times are plotted with the "format" option in the various
"tics" options(above). Output specifiers should be in UNIX
strftime(3) format -- for example,
"<xdata=""time",xtics=>{format=>"%Y-%b-%dT%H:%M:%S"}>>
will plot UNIX times as ISO timestamps in the ordinate.
Due to limitations within gnuplot, the time resolution in this mode is
limited to 1 second - if you want fractional seconds, you must use
numerically formatted times (and/or create your own tick labels using the
"labels" suboption to the "?tics" option.
Timestamp format specifiers
Time format specifiers use the following printf-like codes:
- •
- Year A.D.: %Y is 4-digit year; %y is 2-digit year (1969-2068)
- •
- Month of year: %m: 01-12; %b or %h: abrev. name; %B: full name
- •
- Week of year: %W (week starting Monday); %U (week starting
Sunday)
- •
- Day of year: %j (1-366; boundary is midnight)
- •
- Day of month: %d (01-31)
- •
- Day of week: %w (0-6, Sunday=0), %a (abrev. name), %A (full
name)
- •
- Hour of day: %k (0-23); %H (00-23); %l (1-12); %I (01-12)
- •
- Am/pm: %p ("am" or "pm")
- •
- Minute of hour: %M (00-60)
- •
- Second of minute: %S (0-60)
- •
- Total seconds since start of 2000 A.D.: %s
- •
- Timestamps: %T (same as "%H:%M:%S"); %R (same as
"%H:%M"); %r (same as "%I:%M:%S %p")
- •
- Datestamps: %D (same as "%m/%d/%y"); %F (same as
"%Y-%m-%d")
- •
- ISO timestamps: use "%DT%T".
- day-of-week plotting
- If you just want to plot named days of the week, you can instead use the
"dtics" options set plotting to day of week, where 0 is Sunday
and 6 is Saturday; values are interpreted modulo 7. For example,
"xmtics=>1,xrange=>[-4,9]" will plot two weeks from
Wednesday to Wednesday. As far as output format goes, this is exactly
equivalent to using the %w option with full formatting - but you can treat
the numeric range in terms of weeks rather than seconds.
- month-of-year plotting
- The "mtics" options set plotting to months of the year, where 1
is January and 12 is December, so "xdtics=>1,
xrange=>[0,4]" will include Christmas through Easter. This is
exactly equivalent to using the %d option with full formatting - but you
can treat the numeric range in terms of months rather than seconds.
POs for location/size¶
The options described here are
- tmargin
- bmargin
- lmargin
- rmargin
- offsets
- origin
- size
- justify
- clip
Adjusting the size, location, and margins of the plot on the plotting surface is
something of a null operation for most single plots -- but you can tweak the
placement and size of the plot with these options. That is particularly useful
for multiplots, where you might like to make an inset plot or to lay out a set
of plots in a custom way.
The margin options accept scalar values -- either a positive number of character
heights or widths of margin around the plot compared to the edge of the device
window, or a string that starts with "at screen " and interpolates a
number containing the fraction of the plot window offset. The "at
screen" technique allows exact plot placement and is an alternative to
the "origin" and "size" options below.
The "offsets" option allows you to put an empty boundary around the
data, inside the plot borders, in an autosacaled graph. The offsets only
affect the x1 and y1 axes, and only in 2D plot commands. "offsets"
accepts a list ref with four values for the offsets, which are given in
scientific (plotted) axis units.
The "origin" option lets you specify the origin (lower left corner) of
an individual plot on the plotting window. The coordinates are screen
coordinates -- i.e. fraction of the total plotting window.
The size option lets you adjust the size and aspect ratio of the plot, as an
absolute fraction of the plot window size. You feed in fractional ratios, as
in "size=>[$xfrac, $yfrac]". You can also feed in some keywords
to adjust the aspect ratio of the plot. The size option overrides any
autoscaling that is done by the auto-layout in multiplot mode, so use with
caution -- particularly if you are multiplotting. You can use "size"
to adjust the aspect ratio of a plot, but this is deprecated in favor of the
pseudo-option "justify".
"justify" sets the scientific aspect ratio of a 2-D plot. Unity yields
a plot with a square scientific aspect ratio. Larger numbers yield taller
plots.
"clip" controls the border between the plotted data and the border of
the plot. There are three clip types supported: points, one, and two. You can
set them independently by passing in booleans with their names:
"clip=>[points=>1,two=>0]".
POs for Color: colorbox, palette, clut¶
Color plots are supported via RGB and pseudocolor. Plots that use pseudcolor or
grayscale can have a "color box" that shows the photometric meaning
of the color.
The colorbox generally appears when necessary but can be controlled manually
with the "colorbox" option. "colorbox" accepts a scalar
boolean value indicating whether or no to draw a color box, or a list ref
containing additional options. The options are all, well, optional but must
appear in the order given:
- ( vertical | horizontal ) - indicates direction of the gradient in the
box
- ( default | user ) - indicates user origin and size
- If you specify "default" the colorbox will be placed on the
right-hand side of the plot; if you specify "user", you give the
location and size in subsequent arguments:
colorbox => [ 'user', 'origin'=>"$x,$y", 'size' => "$x,$y" ]
- ( front | back ) - draws the colorbox before or after the plot
- ( noborder | bdefault | border <line style> ) - specify border
- The line style is a numeric type as described in the gnuplot manual.
The "palette" option offers many arguments that are not fully
documented in this version but are explained in the gnuplot manual. It offers
complete control over the pseudocolor mapping function.
For simple color maps, "clut" gives access to a set of named color
maps. (from "Color Look Up Table"). A few existing color maps are:
"default", "gray", "sepia", "ocean",
"rainbow", "heat1", "heat2", and
"wheel". To see a complete list, specify an invalid table, e.g.
"clut=>'xxx'". (This should be improved in a future version).
POs for 3D: trid, view, pm3d, hidden3d, dgrid3d, surface, xyplane, mapping¶
If "trid" or its synonym "3d" is true, Gnuplot renders a 3-D
plot. This changes the default tuple size from 2 to 3. This option is used to
switch between the Gnuplot "plot" and "splot" command, but
it is tracked with persistent state just as any other option.
The "view" option controls the viewpoint of the 3-D plot. It takes a
list of numbers: "view=>[$rot_x, $rot_z, $scale, $scale_z]".
After each number, you can omit the subsequent ones. Alternatively,
"view=>['map']" represents the drawing as a map (e.g. for contour
plots) and "view=>[equal=>'xy']" forces equal length scales on
the X and Y axes regardless of perspective, while
"view=>[equal=>'xyz']" sets equal length scales on all three
axes.
The "pm3d" option accepts several parameters to control the pm3d plot
style, which is a palette-mapped 3d surface. They are not documented here in
this version of the module but are explained in the gnuplot manual.
"hidden3d" accepts a list of parameters to control how hidden surfaces
are plotted (or not) in 3D. It accepts a boolean argument indicating whether
to hide "hidden" surfaces and lines; or a list ref containing
parameters that control how hidden surfaces and lines are handled. For details
see the gnuplot manual.
"xyplane" sets the location of that plane (which is drawn) relative to
the rest of the plot in 3-space. It takes a single string: "at" or
"relative", and a number. "xyplane=>[at=>$z]" places
the XY plane at the stated Z value (in scientific units) on the plot.
"xyplane=>[relative=>$frac]" places the XY plane $frac times
the length of the scaled Z axis *below* the Z axis (i.e. 0 places it at the
bottom of the plotted Z axis; and -1 places it at the top of the plotted Z
axis).
"mapping" takes a single string: "cartesian",
"spherical", or "cylindrical". It determines the
interpretation of data coordinates in 3-space. (Compare to the
"polar" option in 2-D).
POs for Contour plots - contour, cntrparam¶
Contour plots are only implemented in 3D. To make a normal 2D contour plot, use
3-D mode, but set the view to "map" - which projects the 3-D plot
onto its 2-D XY plane. (This is convoluted, for sure -- future versions of
this module may have a cleaner way to do it).
"contour" enables contour drawing on surfaces in 3D. It takes a single
string, which should be "base", "surface", or
"both".
"cntrparam" manages how contours are generated and smoothed. It
accepts a list ref with a collection of Gnuplot parameters that are issued one
per line; refer to the Gnuplot manual for how to operate it.
POs for Polar plots - polar, angles, mapping¶
You can make 2-D polar plots by setting "polar" to a true value. The
ordinate is then plotted as angle, and the abscissa is radius on the plot. The
ordinate can be in either radians or degrees, depending on the
"angles" parameter
"angles" takes either "degrees" or "radians"
(default is radians).
"mapping" is used to set 3-D polar plots, either cylindrical or
spherical (see the section on 3-D plotting, above).
POs for Markup - label, arrow, object¶
You specify plot markup in advance of the plot command, with plot options (or
add it later with the "replot" method). The options give you access
to a collection of (separately) numbered descriptions that are accumulated
into the plot object. To add a markup object to the next plot, supply the
appropriate options as a list ref or as a single string. To specify all markup
objects at once, supply the appropriate options for all of them as a nested
list-of-lists.
To modify an object, you can specify it by number, either by appending the
number to the plot option name (e.g. "arrow3") or by supplying it as
the first element of the option list for that object.
To remove all objects of a given type, supply undef (e.g.
"arrow=>undef").
For example, to place two labels, use the plot option:
label => [["Upper left",at=>"10,10"],["lower right",at=>"20,5"]];
To add a label to an existing plot object, if you don't care about what index
number it gets, do this:
$w->options( label=>["my new label",at=>[10,20]] );
If you do care what index number it gets (or want to replace an existing label),
do this:
$w->options( label=>[$n, "my replacement label", at=>"10,20"] );
where $w is a Gnuplot object and $n contains the label number you care about.
label - add a text label to the plot.
The "label" option allows adding small bits of text at arbitrary
locations on the plot.
Each label specifier list ref accepts the following suboptions, in order. All of
them are optional -- if no options other than the index tag are given, then
any existing label with that index is deleted.
For examples, please refer to the Gnuplot 4.4 manual, p. 117.
- <tag> - optional index number (integer)
- <label text> - text to place on the plot.
- You may supply double-quotes inside the string, but it is not necessary in
most cases (only if the string contains just an integer and you are not
specifying a <tag>.
- at <position> - where to place the text (sci. coordinates)
- The <position> should be a string containing a gnuplot position
specifier. At its simplest, the position is just two numbers separated by
a comma, as in
"label2=>["foo",at=>"5,3"", to specify
(X,Y) location on the plot in scientific coordinates. Each number can be
preceded by a coordinate system specifier; see the Gnuplot 4.4 manual
(page 20) for details.
- ( left | center | right ) - text placement rel. to position
- rotate [ by <degrees> ] - text rotation
- If "rotate" appears in the list alone, then the label is rotated
90 degrees CCW (bottom-to-top instead of left-to-right). The following
"by" clause is optional.
- font "<name>,<size>" - font specifier
- The <name>,<size> must be double quoted in the string (this
may be fixed in a future version), as in
C<< label3=>["foo",at=>"3,4",font=>'"Helvetica,18"'] >>.
- noenhanced - turn off gnuplot enhanced text processing (if enabled)
- ( front | back ) - rendering order (last or first)
- textcolor <colorspec>
- (point <pointstyle> | nopoint ) - control whether the exact position
is marked
- offset <offset> - offfset from position (in points).
arrow - place an arrow or callout line on the plot
Works similarly to the "label" option, but with an arrow instead of
text.
The arguments, all of which are optional but which must be given in the order
listed, are:
- from <position> - start of arrow line
- The <position> should be a string containing a gnuplot position
specifier. At its simplest, the position is just two numbers separated by
a comma, as in
"label2=>["foo",at=>"5,3"", to specify
(X,Y) location on the plot in scientific coordinates. Each number can be
preceded by a coordinate system specifier; see the Gnuplot 4.4 manual
(page 20) for details.
- ( to | rto ) <position> - end of arrow line
- These work like "from". For absolute placement, use
"to". For placement relative to the "from" position,
use "rto".
- (arrowstyle | as) <arrow_style>
- This specifies that the arrow be drawn in a particular predeclared
numerical style. If you give this parameter, you shoudl omit all the
following ones.
- ( nohead | head | backhead | heads ) - specify arrowhead placement
- size <length>,<angle>,<backangle> - specify arrowhead
geometry
- ( filled | empty | nofilled ) - specify arrowhead fill
- ( front | back ) - specify drawing order ( last | first )
- linestyle <line_style> - specify a numeric linestyle
- linetype <line_type> - specify numeric line type
- linewidth <line_width> - multiplier on the width of the line
object - place a shape on the graph
"object"s are rectangles, ellipses, circles, or polygons that can be
placed arbitrarily on the plotting plane.
The arguments, all of which are optional but which must be given in the order
listed, are:
- <object-type> <object-properties> - type name of the shape and
its type-specific properties
- The <object-type> is one of four words: "rectangle",
"ellipse", "circle", or "polygon".
You can specify a rectangle with "from=>$pos1,
[r]to=>$pos2", with "center=>$pos1,
size=>"$w,$h"", or with
"at=>$pos1,size=>"$w,$h"".
You can specify an ellipse with "at=>$pos,
size=>"$w,$h"" or "center=>$pos
size=>"$w,$h"", followed by "angle=>$a".
You can specify a circle with "at=>$pos,
size=>"$w,$h"" or "center=>$pos
size=>"$w,$h"", followed by ""
size=>$radius >> and (optionally)
"arc=>"[$begin:$end]"".
You can specify a polygon with
"from=>$pos1,to=>$pos2,to=>$pos3,...to=>$posn" or
with
"from=>$pos1,rto=>$diff1,rto=>$diff2,...rto=>$diffn".
- ( front | back | behind ) - draw the object last | first |
really-first.
- fc <colorspec> - specify fill color
- fs <fillstyle> - specify fill style
- lw <width> - multiplier on line width
POs for appearance tweaks - bars, boxwidth, isosamples, pointsize, style¶
"bars" sets the width and behavior of the tick
marks at the ends of error bars. It takes a list containing at most two
elements, both of which are optional:
- •
- A width specifier, which should be a numeric size multiplier times the
usual width (which is about one character width in the default font size),
or the word "fullwidth" to make the ticks the same width as
their associated boxes in boxplots and histograms.
- •
- the word "front" or "back" to indicate drawing order
in plots that might contain filled rectangles (e.g. boxes, candlesticks,
or histograms).
If you pass in the undefined value you get no ticks on errorbars; if you pass in
the empty list ref you get default ticks.
"boxwidth" sets the width of drawn boxes in
boxplots, candlesticks, and histograms. It takes a list containing at most two
elements:
- •
- a numeric width
- •
- one of the words "absolute" or "relative".
Unless you set "relative", the numeric width sets the width of boxes
in X-axis scientific units (on log scales, this is measured at x=1 and the
same width is used throughout the plot plane). If "relative" is
included, the numeric width is taken to be a multiplier on the default width.
"isosamples" sets isoline density for plotting
functions as surfaces. You supply one or two numbers. The first is the number
of iso-u lines and the second is the number of iso-v lines. If you only
specify one, then the two are taken to be the same. From the gnuplot manual:
"An isoline is a curve parameterized by one of the surface parameters
while the other surface parameter is fixed. Isolines provide a simple means to
display a surface. By fixing the u parameter of surface s(u,v), the iso-u
lines of the form c(v) = s(u0,v) are produced, and by fixing the v parameter,
the iso-v lines of the form c(u)=s(u,v0) are produced".
"pointsize" accepts a single number and scales
the size of points used in plots.
"style" provides a great deal of customization
for individual plot styles. It is not (yet) fully parsed by
PDL::Graphics::Gnuplot; please refer to the Gnuplot manual for details (it is
pp. 145ff in the Gnuplot 4.6.1 maual). "style" accepts a hash ref
whose keys are plot styles (such as you would feed to the "with"
curve option), and whose values are list refs containing keywords and other
parameters to modify how each plot style should be displayed.
POs for locale/internationalization - locale, decimalsign¶
"locale" is used to control date stamp creation. See the gnuplot
manual.
"decimalsign" accepts a character to use in lieu of a "."
for the decimalsign. (e.g. in European countries use
"decimalsign=>','").
"globalwith" is used as a default plot style if no valid 'with' curve
option is present for a given curve.
If set to a nonzero value, "timestamp" causes a time stamp to be
placed on the side of the plot, e.g. for keeping track of drafts.
"zero" sets the approximation threshold for zero values within
gnuplot. Its default is 1e-8.
"fontpath" sets a font search path for gnuplot. It accepts a
collection of file names as a list ref.
Plotting is carried out by sending a collection of commands to an underlying
gnuplot process. In general, the plot options cause "set" commands
to be sent, configuring gnuplot to make the plot; these are followed by a
"plot" or "splot" command and by any cleanup that is
necessary to keep gnuplot in a known state.
Provisions exist for sending commands directly to Gnuplot as part of a plot. You
can send commands at the top of the configuration but just under the initial
"set terminal" and "set output" commands (with the
"topcmds" option), at the bottom of the configuration and just
before the "plot" command (with the "extracmds" option),
or after the plot command (with the "bottomcmds" option). Each of
these plot options takes a list ref, each element of which should be one
command line for gnuplot.
Most plotting is done with binary data transfer to Gnuplot; however, due to some
bugs in Gnuplot binary handling, certain types of plot data are sent in ASCII.
In particular, time series and label data require transmission in ASCII (as of
Gnuplot 4.4). You can force ASCII transmission of all but image data by
explicitly setting the "binary=>0" option.
"dump" is used for debugging. If true, it writes out the gnuplot
commands to STDOUT
instead of writing to a gnuplot process. Useful to
see what commands would be sent to gnuplot. This is a dry run. Note that if
the 'binary' option is given (see below), then this dump will contain binary
data. If this binary data should be suppressed from the dump, set "dump
=" 'nobinary'>.
"tee" is used for debugging. If true, writes out the gnuplot commands
to STDERR
in addition to writing to a gnuplot process. This is
not a dry run: data is sent to gnuplot
and to the log. Useful
for debugging I/O issues. Note that if the 'binary' option is given (see
below), then this log will contain binary data. If this binary data should be
suppressed from the log, set "tee =" 'nobinary'>.
CURVE OPTIONS¶
The curve options describe details of specific curves within a plot. They are in
a hash, whose keys are as follows:
- legend
- Specifies the legend label for this curve
- axes
- Lets you specify which X and/or Y axes to plot on. Gnuplot supports a main
and alternate X and Y axis. You specify them as a packed string with the x
and y axes indicated: for example, "x1y1" to plot on the main
axes, or "x1y2" to plot using an alternate Y axis (normally
gridded on the right side of the plot).
- with
- Specifies the plot style for this curve. The value is passed to gnuplot
using its 'with' keyword, so valid values are whatever gnuplot supports.
See above ("Plot styles supported") for a list of supported
curve styles.
The following curve options in this list modify the plot style further. Not
all of them are applicable to all plot styles -- for example, it makes no
sense to specify a fill style for "with=>lines".
For historical reasons, you can supply the with modifier curve options as a
single string in the "with" curve option. That usage is
deprecated and will disappear in a future version of
PDL::Graphics::Gnuplot.
- linetype (abbrev 'lt')
- This is a numeric selector from the default collection of line styles. It
includes automagic selection of dash style, color, and width from the
default set of linetypes for your current output terminal.
- linestyle (abbrev 'ls')
- This works exactly like "linetype" above, except that you can
modify individual line styles by setting the "style line
<num>" plot option. That is handy for a custom style you might
use across several curves either a single plot or several plots.
- linewidth (abbrev 'lw')
- This is a numeric multiplier on the usual default line width in your
current terminal.
- linecolor (abbrev 'lc')
- This is a color specifier for the color of the line. You can feed in a
standard color name (they're listed in the package-global variable
@PDL::Graphics::Gnuplot::colornames), a small integer to index the
standard linetype colors, the word "variable" to indicate that
the line color is a standard linetype color to be drawn from an additional
column of data, "[rgbcolor=><num>]" to specify an RGB
color as a 24-bit packed integer, "[rgbcolor=>'variable']" to
specify an additional column of data containing 24-bit packed integers
with RGB color values, "[palette=>'frac',<val>]" to
specify a single fractional position (scaled 0-1) in the current palette,
or "[palette=>'cb',<val>]" to specify a single value in
the scaled cbrange.
There is no "linecolor=>[palette=>variable]" due to
Gnuplot's non-orthogonal syntax. To draw line color from the palette, via
an additional data column, see the separate "palette" curve
option (below).
- textcolor (abbrev 'tc')
- For plot styles like "labels" that specify text, this sets the
color of the text. It has the same format as "linecolor"
(above).
- pointtype (abbrev 'pt')
- Selects a point glyph shape from the built-in list for your terminal, for
plots that render points as small glyphs (like "points" and
"linespoints").
- pointsize (abbrev 'ps')
- Selects a fractional size for point glyphs, relative to the default size
on your terminal, for plots that render points as small glyphs.
- fillstyle (abbrev 'fs')
- Specify the way that filled regions should be colored, in plots that have
fillable areas (like "boxes"). Unlike "linestyle"
above, "fillstyle" accepts a full specification rather than an
index into a set of predefined styles. You can feed in: "empty"
for no fill; "solid" for a solid fill;
"['transparent','solid', <density>]" for a transparent
solid fill on terminals that support it; "pattern" for a
cycling-per-curve pattern fill; "['pattern',<n>]" to
specify a particular fill pattern.
Any of those fill style specifications can have a border specification
appended to it. To specify a border, append "'border',
lt=><type>, lc=><colorspec>" to the list. (You can
omit the lt or the lc). To specify no border, append
"<'noborder'">.
- nohidden3d
- If you are making a 3D plot and have used the plot option
"hidden3d" to get hidden line removal, you can override that for
a particular curve by setting the "nohidden3d" option to a true
value. Only the single curve with "nohidden3d" set will have its
hidden points rendered.
- nocontours
- If you are making a contour 3D plot, you can inhibit rendering of contours
for a particular curve by setting "nocontours" to a true
value.
- nosurface
- If you are making a surface 3D plot, you can inhibit rendering of the
surface associated with a particular curve, by setting
"nosurface" to a true value.
- palette
- Setting "palette => 1" causes line color to be drawn from an
additional column in the data tuple. This column is always the very last
column in the tuple, in case of conflict (e.g. if you set both
"pointsize=>variable" and "palette=>1", then the
palette column is the last column and the pointsize column is
second-to-last).
- tuplesize
- Specifies how many values represent each data point. Normally you don't
need to set this as individual "with" styles implicitly set a
tuple size (which is automatically extended if you specify additional
modifiers such as "palette" that require more data); this option
lets you override PDL::Graphics::Gnuplot's parsing in case of
irregularity.
- cdims
- Specifies the dimensions of of each column in this curve's tuple. It must
be 0, 1, or 2. Normally you don't need to set this for most plots; the
main use is to specify that a 2-D data PDL is to be interpreted as a
collection of 1-D columns rather than a single 2-D grid (which would be
the default in a 3-D plot). For example:
$w=gpwin();
$r2 = rvals(21,21)**2;
$w->plot3d( wi=>'lines', xvals($r2), yvals($r2), $r2 );
will produce a grid of values on a paraboloid. To instead plot a collection
of lines using the threaded syntax, try
$w->plot3d( wi=>'lines', cd=>1, xvals($r2), yvals($r2), $r2 );
which will plot 21 separate curves in a threaded manner.
RECIPES¶
Most of these come directly from Gnuplot commands. See the Gnuplot docs for
details.
2D plotting¶
If we're plotting a piddle $y of y-values to be plotted sequentially (implicit
domain), all you need is
gplot($y);
If we also have a corresponding $x domain, we can plot $y vs. $x with
gplot($x, $y);
Simple style control
To change line thickness:
gplot(with => 'lines',linewidth=>4, $x, $y);
gplot(with => 'lines', lw=>4, $x, $y);
To change point size and point type:
gplot(with => 'points',pointtype=>8, $x, $y);
gplot(with => 'points',pt=>8, $x, $y);
Errorbars
To plot errorbars that show $y +- 1, plotted with an implicit domain
gplot(with => 'yerrorbars', $y, $y->ones);
Same with an explicit $x domain:
gplot(with => 'yerrorbars', $x, $y, $y->ones);
Symmetric errorbars on both x and y. $x +- 1, $y +- 2:
gplot(with => 'xyerrorbars', $x, $y, $x->ones, 2*$y->ones);
To plot asymmetric errorbars that show the range $y-1 to $y+2 (note that here
you must specify the actual errorbar-end positions, NOT just their deviations
from the center; this is how Gnuplot does it)
gplot(with => 'yerrorbars', $y, $y - $y->ones, $y + 2*$y->ones);
More multi-value styles
Plotting with variable-size circles (size given in plot units, requires Gnuplot
>= 4.4)
gplot(with => 'circles', $x, $y, $radii);
Plotting with an variably-sized arbitrary point type (size given in multiples of
the "default" point size)
gplot(with => 'points', pointtype=>7, pointsize=>'variable',
$x, $y, $sizes);
Color-coded points
gplot(with => 'points', palette=>1,
$x, $y, $colors);
Variable-size AND color-coded circles. A Gnuplot (4.4.0) bug make it necessary
to specify the color range here
gplot(cbmin => $mincolor, cbmax => $maxcolor,
with => 'circles', palette=>1,
$x, $y, $radii, $colors);
3D plotting¶
General style control works identically for 3D plots as in 2D plots.
To plot a set of 3d points, with a square aspect ratio (squareness requires
Gnuplot >= 4.4):
splot(square => 1, $x, $y, $z);
If $xy is a 2D piddle, we can plot it as a height map on an implicit domain
splot($xy);
Complicated 3D plot with fancy styling:
my $pi = 3.14159;
my $theta = zeros(200)->xlinvals(0, 6*$pi);
my $z = zeros(200)->xlinvals(0, 5);
splot(title => 'double helix',
{ with => 'linespoints',
pointsize=>'variable',
pointtype=>7,
palette=>1,
legend => 'spiral 1' },
{ legend => 'spiral 2' },
# 2 sets of x, 2 sets of y, single z
PDL::cat( cos($theta), -cos($theta)),
PDL::cat( sin($theta), -sin($theta)),
$z,
# pointsize, color
0.5 + abs(cos($theta)), sin(2*$theta) );
3D plots can be plotted as a heat map.
splot( extracmds => 'set view 0,0',
with => 'image',
$xy );
Hardcopies¶
To send any plot to a file, instead of to the screen, one can simply do
gplot(hardcopy => 'output.pdf',
$x, $y);
The "hardcopy" option is a shorthand for the "terminal" and
"output" options. The output device is chosen from the file name
suffix.
If you want more (any) control over the output options (e.g. page size, font,
etc.) then you can specify the output device using the "output"
method or the constructor itself -- or the corresponding plot options in the
non-object mode. For example, to generate a PDF of a particular size with a
particular font size for the text, one can do
gplot(terminal => 'pdfcairo solid color font ",10" size 11in,8.5in',
output => 'output.pdf',
$x, $y);
This command is equivalent to the "hardcopy" shorthand used
previously, but the fonts and sizes can be changed.
Using the object oriented mode, you could instead say:
$w = gpwin();
$w->plot( $x, $y );
$w->output( pdfcairo, solid=>1, color=>1,font=>',10',size=>[11,8.5,'in'] );
$w->replot();
$w->close();
Many hardcopy output terminals (such as "pdf" and "svg")
will not dump their plot to the file unless the file is explicitly closed with
a change of output device or a call to "reset", "restart",
or "close". This is because those devices support multipage output
and also require and end-of-file marker to close the file.
Plotting examples¶
A simple example¶
my $win = gpwin('x11');
$win->plot( sin(xvals(45)) * 3.14159/10 );
Here we just plot a simple function. The default plot style is a line. Line
plots take a 2-tuple (X and Y values). Since we have supplied only one
element, "plot()" understands it to be the Y value (abscissa) of the
plot, and supplies value indices as X values -- so we get a plot of just over
2 cycles of the sine wave over an X range across X values from 0 to 44.
A not-so-simple example¶
$win = gpwin('x11');
$pi = 3.14159
$win->plot( {with => line}, xvals(10)**2, xvals(10),
{with => circles}, 2 * xvals(50), 2 * sin(xvals(50) * $pi / 10), xvals(50)/20
);
This plots sqrt(x) in an interesting way, and overplots some circles of varying
size. The line plot accepts a 2-tuple, and we supply both X and Y. The circles
plot accepts a 3-tuple: X, Y, and R.
A complicated example:¶
$pi = 3.14159;
$theta = xvals(201) * 6 * $pi / 200;
$z = xvals(201) * 5 / 200;
gplot( {trid => 1, title => 'double helix',cbr=>[0,1]},
{with => 'linespoints',
pointsize=>'variable',
pointtype=>2,
palette=>1,
legend => ['spiral 1','spiral 2'],
cdim=>1},
pdl( cos($theta), -cos($theta) ), # x
pdl( sin($theta), -sin($theta) ), # y
$z, # z
(0.5 + abs(cos($theta))), # pointsize
sin($theta/3), # color
{ with=>'points',
pointsize=>'variable',
pointtype=>5,
palette=>0
},
zeroes(6), # x
zeroes(6), # y
xvals(6), # z
xvals(6)+1 # point size
);
This is a 3d plot with variable size and color. There are 5 values in the tuple.
The first 2 piddles have dimensions (N,2); all the other piddles have a single
dimension. The "cdim=>1" specifies that each column of data
should be one-dimensional. Thus the PDL threading generates 2 distinct curves,
with varying values for x,y and identical values for everything else. To label
the curves differently, 2 different sets of curve options are given. Omitting
the "cdim" curve option would yield a 201x2 grid with the
"linespoints" plotstyle, rather than two separate curves.
In addition to the threaded pair of linespoints curves, there are six variable
size points plotted as filled squares, as a secondary curve.
Plot options are passed in in two places: as a leading hash ref, and as a
trailing hash ref. Any other hash elements or hash refs must be curve options.
Curves are delimited by non-data arguments. After the initial hash ref, curve
options for the first curve (the threaded pair of spirals) are passed in as a
second hash ref. The curve's data arguments are ended by the first non-data
argument (the hash ref with the curve options for the second curve).
FUNCTIONS¶
gpwin¶
use PDL::Graphics::Gnuplot;
$w = gpwin( @options );
$w->plot( @plot_args );
gpwin is the PDL::Graphics::Gnuplot exported constructor. It is exported by
default and is a synonym for "new PDL::Graphics::Gnuplot(...)". If
given no arguments, it creates a plot object with the default terminal
settings for your gnuplot. You can also give it the name of a Gnuplot terminal
type (e.g. 'x11') and some terminal and output options (see
"output").
new¶
$w = new PDL::Graphics::Gnuplot;
$w->plot( @plot_args );
#
# Specify plot options alone
$w = new PDL::Graphics::Gnuplot( {%plot_options} );
#
# Specify device and device options (and optional default plot options)
$w = new PDL::Graphics::Gnuplot( device, %device_options, {%plot_options} );
$w->plot( @plot_args );
Creates a PDL::Graphics::Gnuplot persistent plot object, and connects it to
gnuplot.
For convenience, you can specify the output device and its options right here in
the constructor. Because different gnuplot devices accept different options,
you must specify a device if you want to specify any device configuration
options (such as window size, output file, text mode, or default font).
If you don't specify a device type, then the Gnuplot default device for your
system gets used. You can set that with an environment variable (check the
Gnuplot documentation).
Gnuplot uses the word "terminal" for output devices; you can see a
list of terminals supported by PDL::Graphics::Gnuplot by invoking
"PDL::Graphics::Gnuplot::terminfo()" (for example in the perldl
shell).
For convenience, you can provide default plot options here. If the last argument
to "new()" is a trailing hash ref, it is treated as plot options.
After you have created an object, you can change its terminal/output device with
the "output" method, which is useful for (e.g.) throwing up an
interactive plot and then sending it to a hardcopy device. See
"output" for a description of terminal options and how to format
them.
Normally, the object connects to the command "gnuplot" in your path,
using the "Alien::Gnuplot" module. If you need to specify a binary
other than this default, check the "Alien::Gnuplot" documentation.
my $plot = PDL::Graphics::Gnuplot->new({title => 'Object-oriented plot'});
$plot->plot( legend => 'curve', sequence(5) );
output¶
$window->output( $device );
$window->output( $device, %device_options );
$window->output( $device, %device_options, {plot_options} );
$window->output( %device_options, {plot_options} );
$window->output( %device_options );
Sets the output device and options for a Gnuplot object. If you omit the $device
name, then you get the gnuplot default device (generally "x11",
"wxt", or "aqua", depending on platform).
You can control the output device of a PDL::Graphics::Gnuplot object on the fly.
That is useful, for example, to replot several versions of the same plot to
different output devices (interactive and hardcopy).
Gnuplot interprets terminal options differently per device.
PDL::Graphics::Gnuplot attempts to interpret some of the more common ones in a
common way. In particular:
- size
- Most drivers support a "size" option to specify the size of the
output plotting surface. The format is [$width, $height, $unit]; the
trailing unit string is optional but recommended, since the default unit
of length changes from device to device.
The unit string can be in, cm, mm, px, or pt. Pixels are taken to be 1 point
in size (72 pixels per inch) and dimensions are computed accordingly.
- output
- This option actually sets the object's "output" option for most
terminal devices; that changes the file to which the plot will be written.
Some devices, notably X11 and Aqua, don't make proper use of
"output"; for those devices, specifying "output" in
the object constructor actually sets the appropriate terminal option (e.g.
"window" in the X11 terminal). This is described as a "plot
option" in the Gnuplot manual, but it is treated as a setup variable
and parsed with the setup/terminal options here in the constructor.
- enhanced
- This is a flag that indicates whether to enable Gnuplot's enhanced text
processing (e.g. for superscripts and subscripts). Set it to a false value
for plain text, to a true value for enhanced text (which includes
LaTeX-like markup for super/sub scripts and fonts).
For a brief description of the terminal options that any one device supports,
you can run
PDL::Graphics::Gnuplot::terminfo().
As with plot options, terminal options can be abbreviated to the shortest unique
string -- so (e.g.) "size" can generally be abbreviated
"si" and "monochrome" can be abbreviated "mono"
or "mo".
close¶
$w=gpwin();
$w->plot(xvals(5));
$w->close;
Close gnuplot process (actually just a synonym for restart)
Some of the gnuplot terminals (e.g. pdf) don't write out a file promptly. The
close method closes the associated gnuplot subprocess, forcing the file to be
written out. It is implemented as a simple restart operation.
The object preserves the plot state, so "replot" and similar methods
still work with the new subprocess.
restart¶
$w->restart();
PDL::Graphics::Gnuplot::restart();
Restart the gnuplot backend for a plot object
Occasionally the gnuplot backend can get into an unknown state.
"restart" kills the gnuplot backend and starts a new one, preserving
state in the object. (i.e. "replot" and similar functions work even
with the new subprocess).
Called with no arguments, "restart" applies to the global plot object.
reset¶
$w->reset()
Clear state from the gnuplot backend
Clears all plot option state from the underlying object. All plot options except
"terminal", "termoptions", "output", and
"multiplot" are cleared. This is similar to the "reset"
command supported by gnuplot itself, and in fact it also causes a
"reset" to be sent to gnuplot.
options¶
$w = new PDL::Graphics::Gnuplot();
$w->options( globalwith=>'lines' );
print %{$w->options()};
Set/get persistent plot options for a plot object
The options method parses plot options into a gnuplot object on a cumulative
basis, and returns the resultant options hash.
If called as a sub rather than a method,
options() changes the global
gnuplot object.
gplot¶
Plot method exported by default (synonym for
"PDL::Graphics::Gnuplot::plot")
plot¶
This is the main plotting routine in PDL::Graphics::Gnuplot.
Each "plot()" call creates a new plot from whole cloth, either
creating or overwriting the output for that device.
If you want to add features to an existing plot, use "replot".
"plot()" understands the PDL bad value mechanism. Bad values are
omitted from the plot.
$w=gpwin();
$w->plot({temp_plot_options}, # optional
curve_options, data, data, ... , # curve_options are optional for the first plot
curve_options, data, data, ... ,
{temp_plot_options});
Most of the arguments are optional.
All of the extensive array of gnuplot plot styles are supported, including
images and 3-D plots.
use PDL::Graphics::Gnuplot qw(plot);
my $x = sequence(101) - 50;
plot($x**2);
See main POD for PDL::Graphics::Gnuplot for details.
You can pass plot options into plot as either a leading or trailing hash ref, or
both. If you pass both, the trailing hash ref is parsed last and overrides the
leading hash.
For debugging and curiosity purposes, the last plot command issued to gnuplot is
maintained in a package global: $PDL::Graphics::Gnuplot::last_plotcmd, and
also in each object as the {last_plotcmd} field.
replot¶
Replot the last plot (possibly with new arguments).
"replot" is similar to gnuplot's "replot" command - it
allows you to regenerate the last plot made with this object. You can change
the plot by adding new elements to it, modifying options, or even (with the
"device" method) changing the output device. "replot"
takes the same arguments as "plot".
If you give no arguments at all (or only a plot object) then the plot is simply
redrawn. If you give plot arguments, they are added to the new plot exactly as
if you'd included them in the original plot element list, and maintained for
subsequent replots.
(Compare to 'markup').
markup¶
Add ephemeral markup to the last plot.
"markup" works exactly the same as "replot", except that any
new arguments are not added to the replot list - so you can add temporary
markup to a plot and regenerate the plot later without it.
plot3d¶
Generate 3D plots. Synonym for "plot(trid => 1, ...)"
splot¶
Generate 3D plots. Synonym for "plot(trid => 1, ...)"
lines¶
Generates plots with lines, by default. Shorthand for "plot(globalwith
=> 'lines', ...)"
points¶
Generates plots with points, by default. Shorthand for "plot(globalwith
=> 'points', ...)"
image¶
Displays an image (either greyscale or RGB). Shorthand for "plot(globalwith
=> 'image', ...)"
imag¶
Synonym for "image", for people who grew up with PDL::Graphics::PGPLOT
and can't remember the closing 'e'
fits¶
Displays a FITS image. Synonym for "plot(globalwith => 'fits',
...)".
multiplot¶
$a = (xvals(101)/100) * 6 * 3.14159/180;
$b = sin($a);
$w->multiplot(layout=>[2,2,"columnsfirst"]);
$w->plot({title=>"points"},with=>"points",$a,$b);
$w->plot({title=>"lines"}, with=>"lines", $a,$b);
$w->plot({title=>"image"}, with=>"image", $a->(*1) * $b );
$w->end_multi();
Plot multiple plots into a single page of output.
The "multiplot" method enables multiplot mode in gnuplot, which
permits multiple plots on a single pane. Plots can be lain out in a grid, or
can be lain out freeform using the "size" and "origin"
plot options for each of the individual plots.
It is not possible to change the terminal or output device when in multiplot
mode; if you try to do that, by setting one of those plot options,
PDL::Graphics::Gnuplot will throw an error.
The options hash will accept:
- layout - define a regular grid of plots to multiplot
- "layout" should be followed by an ARRAY ref that contains at
least number of columns ("NX") followed by number of rows
("NY). After that, you may include any of the "rowsfirst",
"columnsfirst", "downwards", or "upwards"
keywords to specify traversal order through the grid. Only the first
letter is examined, so (e.g.) "down" or even "dog"
works the same as "downwards".
- title - define a title for the entire page
- "title" should be followed by a single scalar containing the
title string.
- scale - make gridded plots larger or smaller than their allocated
space
- "scale" takes either a scalar or a list ref containing one or
two values. If only one value is supplied, it is a general scale factor of
each plot in the grid. If two values are supplied, the first is an X
stretch factor for each plot in the grid, and the second is a Y stretch
factor for each plot in the grid.
- offset - offset each plot from its grid origin
- "offset" takes a list ref containing two values, that control
placement of each plot within the grid.
end_multi¶
$w=gpwin();
$w->multiplot(layout=>[2,1]);
$w->plot({title=>"points},with=>'points',$a,$b);
$w->plot({title=>"lines",with=>"lines",$a,$b);
$w->end_multi();
Ends a multiplot block (i.e. a block of plots that are meant to render to a
single page).
read_mouse¶
($x,$y,$char,$modstring) = $w->read_mouse($message);
$hash = $w->read_mouse($message);
Get a mouse click or keystroke from the active interactive plot window.
For interactive devices (e.g. x11, xwt, aqua), get_click lets you accept a
keystroke or mouse button input from the gnuplot window. In list context, it
returns four arguments containing the reported X, Y, keystroke character, and
modifiers packed in a string. In scalar context, it returns a hash ref
containing those things.
read_mouse blocks execution for input, but responds gracefully to interrupts.
read_polygon¶
$points = $w->read_polygon(%opt)
Read in a polygon by accepting mouse clicks. The polygon is returned as a 2xN
PDL of ($x,$y) values in scientific units. Acceptable options are:
- message - what to print before collecting points
- There are some printf-style escapes for the prompt:
* %c - expands to "an open" or "a closed"
* %n - number of points currently in the polygon
* %N - number of points expected for the polygon
* %k - list of all keys accepted
* "%%" - %
- prompt - what to print to prompt the user for the next point
- "prompt" uses the same escapes as "message".
- n_points - number of points to accept (or 0 for indefinite)
- With 0 value, points are accepted until the user presses 'q' or 'ESC' on
the keyboard with focus on the graph. With other value, points are
accepted until that happens *or* until the number of points is at least
n_points.
- actions - hash of callback code refs indexed by character for action
- You can optionally call a callback routine when any particular character
is pressed. The actions table is a hash ref whose keys are characters and
whose values are either code refs (to be called on the associated
keypress) or array refs containing a short description string followed by
a code ref. Non-printable characters (e.g. ESC, BS, DEL) are accessed via
a hash followed by a three digit decimal ASCII code -- e.g.
"#127" for DEL. Button events are indexed with the strings
"BUTTON1", "BUTTON2", and "BUTTON3", and
modifications must be entered as well for shift, control, and
The code ref receives the arguments ($obj, $c, $poly,$x,$y,$mods),
where:
- $obj is the plot object
- $c is the character (or "BUTTON"n"" string),
- $poly is a scalar ref; $$poly is the current polygon before the
action,
- $x and $y are the current scientific coordinates, and
- $mods is the modifier string.
- You can't override the 'q' or '#027' (ESC) callbacks. You *can* override
the BUTTON1 and DEL callbacks, potentially preventing the user from
entering points at all! You should do that with caution.
- closed - (default false): generate a closed polygon
- This works by duplicating the initial point at the end of the point
list.
- markup - (default 'linespoints'): style to use to render the polygon on
the fly
- If this is set to a true value, it should be a valid 'with' specifier
(curve option). The routine will call markup after each click.
terminfo¶
use PDL::Graphics::Gnuplot qw/terminfo/
terminfo()
terminfo 'aqua'
$w = gpwin();
$w->terminfo();
Print out information about gnuplot terminals and their custom option syntax.
The "terminfo" routine is a reference tool to describe the Gnuplot
terminal types and the options they accept. It's mainly useful in interactive
sessions. It outputs information directly to the terminal.
COMPATIBILITY¶
Everything should work on all platforms that support Gnuplot and Perl.
Currently, MacOS, Fedora and Debian Linux, Cygwin, and Microsoft Windows
(under both Active State Strawberry Perl) have been tested to work, although
the interprocess control link is not as reliable under Microsoft Windows as
under POSIX systems. Please report successes or failures on other platforms to
the authors. A transcript of a failed run with {tee => 1} would be most
helpful.
REPOSITORY¶
<
https://github.com/drzowie/PDL-Graphics-Gnuplot>
AUTHOR¶
Craig DeForest, "<craig@deforest.org>" and Dima Kogan,
"<dima@secretsauce.net>"
STILL TO DO¶
- some plot and curve options need better parsing:
- - Hash values should be accepted (and parsed properly) for all plot
options.
- Currently many of the more complicated plot options accept array refs
only. Hash ref parsing is needed for regularity.
- - labels need attention (plot option labels)
- They need to be handled as hashes, not just as array refs. Also, they
don't seem to be working with timestamps. Further, deeply nested options
(e.g. "at" for labels) need attention.
- - new plot styles
- The "boxplot" plot style (new to gnuplot 4.6?) requires a
different using syntax and will require some hacking to support.
LICENSE AND COPYRIGHT¶
Copyright 2011-2013 Craig DeForest and Dima Kogan
This program is free software; you can redistribute it and/or modify it under
the terms of either: the GNU General Public License as published by the Free
Software Foundation; or the Perl Artistic License included with the Perl
language.
See
http://dev.perl.org/licenses/ for more information.