=head1 OVERVIEW
This is a Gnuplot-based plotter for PDL. This repository stores the history for
the PDL::Graphics::Gnuplot module on CPAN. Install the module via CPAN. CPAN
page at L.
=cut
=head1 NAME
PDL::Graphics::Gnuplot - Gnuplot-based plotting for PDL
=head1 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 = zeros(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 = zeros(200)->xlinvals(0, 6*$pi);
pdl> $z = zeros(200)->xlinvals(0, 5);
pdl> $w->plot3d(cos($theta), sin($theta), $z);
pdl> $w->terminfo(); # get information
=head1 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. You must obtain it separately from this
interface module. It is available through most Linux repositories, on
MacOS via fink and MacPorts, and from its website L.
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.
C exports two routines by default: a
constructor, C and a general purpose plot routine,
C. Depending on options, C 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 C 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 C are tracked through a global object that stores
globally set configuration variables.
The C sub (or the C method) collects two kinds of
options hash: B, which describe the overall structure of
the plot being produced (e.g. axis specifications, window size, and
title), and B, 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.
=head2 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.
=head3 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();
=head3 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.
=head3 3-D plotting
You can plot in 3-D by setting the plot option C 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.
=head2 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:
=over 3
=item {}
Text grouping - enclose text in braces to group characters, as in LaTeX.
=item ^
Superscript the next character or group (shrinks it slightly too where that is supported).
=item _
Subscript the next character or group (shrinks it slightly too where that is supported).
=item @
Phantom box (occupies no width; controls height for super- and subscripting)
=item &
Controllable-width space, e.g. &{template-string}
=item ~
overstrike -- e.g. ~a{0.8-} overprints '-' on 'a', raised by 0.8xfontsize.
=item {/[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.
=item \
Backslash escapes control characters to render them as themselves.
=back
=head2 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:
=over 3
=item - an integer
This specifies a recognizable unique color in the same order as used by the plotting engine.
=item - the name of a color
(e.g. "blue"). Supported color names are listed in the variable C<@Alien::Gnuplot::colors>.
=item - an RGB value string
Strings have the form C<#RRGGBB>, where the C<#> is literal and the RR, GG, and BB are hexadecimal bytes.
=item - 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.
=item - 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.
=item - 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.
=back
=head2 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
C'lines',lc=E'blue'>. To match the autogenerated style of a
particular line you can use the C curve option.
The GNuplot plot styles supported are:
=over 3
=item * C - combo of C and C, below (2D)
=item * C - simple boxes around regions on the plot (2D)
=item * C - Render X and Y error bars as boxes (2D)
=item * C - Y error bars with inner and outer limits (2D)
=item * C - circles with variable radius at each point: X/Y/radius (2D)
=item * C - tiny points ("dots") at each point, e.g. for scatterplots (2D/3D)
=item * C - ellipses. Accepts X/Y/major/minor/angle (2D)
=item * C - closed polygons or axis-to-line filled shapes (2D)
=item * C - financial style plot. Accepts date/open/low/high/close (2D)
=item * C - square bin plot; delta-Y, then delta-X (see C, C) (2D)
=item * C - square bin plot; plateaus centered on X coords (see C, C) (2D)
=item * C - binned histogram of dataset (not direct plot; see C) (2D)
=item * C - (PDL-specific) renders FITS image files in scientific coordinates
=item * C - Takes (i), (x,y,i), or (x,y,z,i). See C, C, C. (2D/3D)
=item * C - vertical line from axis to the plotted point (2D/3D)
=item * C - Text labels at specified locations all over the plot (2D/3D)
=item * C - regular line plot (2D/3D)
=item * C - line plot with symbols at plotted points (2D/3D)
=item * C - multiple-histogram-friendly histogram style (see C) (2D)
=item * C - symbols at plotted points (2D/3D)
=item * C - R/G/B color image with variable transparency (2D/3D)
=item * C - R/G/B color image (2D/3D)
=item * C - square bin plot; delta-X, then delta-Y (see C, C) (2D)
=item * C - Small arrows: (x,y,[z]) -> (x+dx,y+dy,[z+dz]) (2D/3D)
=item * C - points with X error bars ("T" form) (2D)
=item * C - points with both X and Y error bars ("T" form) (2D)
=item * C - points with Y error bars ("T" form) (2D)
=item * C - line plot with X errorbars at each point. (2D)
=item * C - line plot with XY errorbars at each point. (2D)
=item * C - line plot with Y error limits at each point. (2D)
=item * C - three-dimensional variable-position surface plot
=back
=head2 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 L. 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 (C, C,
C, etc.).
The curve options are parameters that affect only one curve in particular. Each
call to C can contain many curves, and options for a particular curve
I the data for that curve in the argument list. Furthermore, I. So if you set a particular style for a curve, this
style will persist for all the following curves, until this style is turned
off. The only exception to this is the C