=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 Lhttp://metacpan.org/pod/PDL::Graphics::Gnuplot.

=cut

=encoding UTF-8

=head1 NAME

PDL::Graphics::Gnuplot - Gnuplot-based plotting for PDL

=head1 SYNOPSIS

pdl> use PDL::Graphics::Gnuplot;

pdl> $x = sequence(101) - 50; pdl> gplot($x2); pdl> gplot($x2,{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

=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. It is available through most Linux repositories, on MacOS, and from its website Lhttp://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.

For a very quick demonstration of the power of this module, see L<this YouTube demo video|https://www.youtube.com/watch?v=hUXDQL3rZ_0>, and others on visualisation of L<tesseract assembly|https://www.youtube.com/watch?v=ykQmNrSKqGQ> and L<rotation|https://www.youtube.com/watch?v=6tpsPYBrHy0>.

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<gpwin()> and a general purpose plot routine, C<gplot()>. Depending on options, C<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 C<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 C<gplot()> are tracked through a global object that stores globally set configuration variables.

The C<gplot()> sub (or the C<plot()> 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 can specify what type of graphics output you want, but in most cases doing nothing will cause a plot to be rendered on your screen: with X windows on UNIX or Linux systems, with an XQuartz window on MacOS, or with a native window on Microsoft Windows.

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 array refs. If you use an array 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 Plotting to an image file or device

PDL:Graphics::Gnuplot can plot to most of the devices supported by gnuplot itself. You can specify the file type with the "output" method or the object constructor "gplot". Either one will allow you to name a type of file to produce, and a collection of options speciic to that type of output file.

=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 Unicode text

Separately to "enhanced" text above, if you wish to include text that is not ASCII, then you will need to pass data that has been UTF-8 encoded. Sample code to achieve this:

use utf8; use Encode; use PDL; use PDL::Graphics::Gnuplot; use PDL::Constants qw(PI);

sub plotsin { my ($w, $coeff) = @; my $xrange = [ -2PI, 2PI ]; my $x = zeroes(1e3)->xlinvals(@$xrange); my $y = sin($coeff 2 PI $x); my $title = "y = sin( $coeff 2π * x )";

to get around sending text through syswrite()

my $title_octets = encode('UTF-8', $title);
$w->plot(with=>'lines', $x, $y, {
  xrange => $xrange,
  title => $title_octets, # can not pass $title as-is
});

}

=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<with=E'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"|/"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 (C, C, C, etc.).

The curve options are parameters that affect only one curve in particular. Each call to C<plot()> can contain many curves, and options for a particular curve I 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 L<"Curve Options"|/"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 );

=head2 Data arguments

Following the curve options in the C<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).

=head3 PDLs vs array 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 an array 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 array ref is present in a tuple, then threading is disabled in that tuple: everything has to have a nice 1-D shape.

=head3 Implicit domains

When making a simple 2D plot, if exactly 1 dimension is missing, PDL::Graphics::Gnuplot will use C<sequence(N)> as the domain. This is why code like C<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 ndarray short; C<sequence(5)> is used as the missing domain PDL. This is thus equivalent to C<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 ndarrays 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 ndarray has dimensions (21,21). This is a 3D plot, so we are exactly 2 ndarrays short. Thus, PDL::Graphics::Gnuplot generates an implicit domain, corresponding to a 21-by-21 grid.

C 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, C<plot($a,$b)> will plot C<$b> vs. C<$a>. If you actually want to plot an overlay of both C<$a> and C<$b> against array index, you want C<plot($a,{},$b)> instead. The C<{}> 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.

=head2 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 (3xWxH) or (WxHx3) PDL it is treated as an RGB image and displayed with the "rgbimage" style (below), provided there are at least 5 pixels in each of the other two dimensions (just to be sure). For quick image display there is also an "image" method:

use PDL::Graphics::Gnuplot qw/image gplot/; $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, 255*($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 curve option "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=>1, $fitsdata ); 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 1024x1024 grid, a 200x200 grid, or a 100x400 grid, respectively. The resample sizes must be positive integers. A true non-ref value will be treated as 1024x1024.

=head2 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 C) are persistently interactive. Other terminals (such as C) 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 C and C) also support mouse input: you can write PDL scripts that accept and manipulate graphical input from the plotted window.

=head1 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 C method, or to the C 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 EfooE", describing the category. You can skip below them all if you want to read about curve options or other aspects of PDL::Graphics::Gnuplot.

=head2 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 C (or the exported constructor C) or the C

method. If you use the simple non-object interface, you can set the output with the C, C, and C

plot options.

C sets the output device type for Gnuplot, and C

sets the actual output file or window number.

C and C are for convenience. C 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). C takes an output file name, attempts to parse out a file suffix and infer a device type. C 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 C, or you can use the constructor C (also exported as C), which parses terminal options as an argument list.

The routine C prints a list of all available terminals or, if you pass in a terminal name, options accepted by that terminal.

=head2 POs for Titles

The options described here are

=over

=item title

=item xlabel

=item x2label

=item ylabel

=item y2label

=item zlabel

=item cblabel

=item key

=back

Gnuplot supports "enhanced" text escapes on most terminals; see "text", below.

The C