NAME

PDL::Graphics::Gnuplot - Gnuplot-based plotter for PDL

SYNOPSIS

use PDL::Graphics::Gnuplot qw(plot plot3d);

my $x = sequence(101) - 50;
plot($x**2);

plot( title => 'Parabola with error bars',
      with => 'xyerrorbars', tuplesize => 4, legend => 'Parabola',
      $x**2 * 10, abs($x)/10, abs($x)*5 );

my $xy = zeros(21,21)->ndcoords - pdl(10,10);
my $z = inner($xy, $xy);
plot(title  => 'Heat map', '3d' => 1,
     extracmds => 'set view map',
     with => 'image', $z*2);

my $pi    = 3.14159;
my $theta = zeros(200)->xlinvals(0, 6*$pi);
my $z     = zeros(200)->xlinvals(0, 5);
plot3d(cos($theta), sin($theta), $z);

DESCRIPTION

This module allows PDL data to be plotted using Gnuplot as a backend. As much as was possible, this module acts as a passive pass-through to Gnuplot, thus making available the full power and flexibility of the Gnuplot backend. Gnuplot is described in great detail at its upstream website: http://www.gnuplot.info.

The main subroutine that PDL::Graphics::Gnuplot exports is plot(). A call to plot() looks like

plot(plot_options,
     curve_options, data, data, ... ,
     curve_options, data, data, ... );

Options arguments

Each set of options is a hash that can be passed inline or as a hashref: both plot( title => 'Fancy plot!', ... ) and plot( {title => 'Another fancy plot'}, ...) work. The plot options must precede all the curve options.

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".

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. Furthermore, curve options are all cumulative. 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 legend option, since it's very rarely a good idea to have multiple curves with the same label. An example:

plot( with => 'points', $x, $a,
      y2   => 1,        $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 also on the secondary y axis. All the curve options are described below in "Curve options".

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). In the plot() argument list each tuple element must be passed separately. If we're making anything fancier than a simple 2D or 3D plot (2- and 3- tuples respectively) then the tuplesize curve option must be passed in. Furthermore, PDL threading is active, so multiple curves can be plotted by stacking data inside the passed-in piddles. When doing this, multiple sets of curve options can be passed in as multiple hashrefs preceding the data itself in the argument list. By using hashrefs we can make clear which option corresponds to which plot. An example:

my $pi    = 3.14159;
my $theta = zeros(200)->xlinvals(0, 6*$pi);
my $z     = zeros(200)->xlinvals(0, 5);

plot( '3d' => 1, title => 'double helix',

      { with => 'points pointsize variable pointtype 7 palette', tuplesize => 5,
        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) );

This is a 3d plot with variable size and color. There are 5 values in the tuple, which we specify. The first 2 piddles have dimensions (N,2); all the other piddles have a single dimension. 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. Since the curve options are cumulative, the style and tuplesize needs only to be passed in for the first curve; the second curve inherits those options.

Implicit domains

When a particular tuplesize is specified, PDL::Graphics::Gnuplot will attempt to read that many piddles. If there aren't enough piddles available, PDL::Graphics::Gnuplot will throw an error, unless an implicit domain can be used. This happens if we are exactly 1 or 2 piddles short (usually when making 2D and 3D plots respectively).

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 piddle is given here, but a default tuplesize of 2 is active, and we are thus exactly 1 piddle short. This is thus equivalent to plot( sequence(5), pdl(1,5,3,4,4) ).

If plotting in 3d, 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);
plot('3d' => 1,
      with => 'points', inner($xy, $xy));

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.

Note that this logic doesn't look at whether a 2D or 3D plot is being made. It can make sense to have a 2D implicit domain when making 2D plots. For example, one can be plotting a color map:

my $xy = zeros(21,21)->ndcoords - pdl(10,10);
my $z = inner($xy, $xy);
plot(title  => 'Heat map',
     tuplesize => 3, with => 'image', $z*2);

This is the same example as in the Synopsis, but plotted without '3d' => 1; the output is very similar.

Also note that the tuplesize curve option is independent of implicit domains. This option specifies not how many data piddles we have, but how many values represent each data point. For example, if we want a 2D plot with varying colors plotted with an implicit domain, set tuplesize to 3 as before, but pass in only 2 piddles (y, color).

One thing to watch out for it to make sure PDL::Graphics::Gnuplot doesn't get confused about when to use implicit domains. For example, plot($a,$b) is interpreted as plotting $b vs $a, not $a vs an implicit domain and $b vs an implicit domain. If 2 implicit plots are desired, add a separator: plot($a,{},$b). Here {} is an empty curve options hash. If $a and $b have the same dimensions, one can also do plot($a->cat($b)), taking advantage of PDL threading.

Interactivity

The graphical backends of Gnuplot are interactive, allowing the user to pan, zoom, rotate and measure the data in the plot window. See the Gnuplot documentation for details about how to do this. Some terminals (such as wxt) are persistently interactive, and the rest of this section does not apply to them. Other terminals (such as x11) have the downside described here.

When using an affected terminal, interactivity is only possible if the gnuplot process is running. As long as the perl program calling PDL::Graphics::Gnuplot is running, the plots are interactive, but once it exits, the child gnuplot process will exit also. This will keep the plot windows up, but the interactivity will be lost. So if the perl program makes a plot and exits, the plot will NOT be interactive.

Due to particulars of the current implementation of PDL::Graphics::Gnuplot, each time plot() is called, a new gnuplot process is launched, killing the previous one. This results only in the latest plot being interactive. The way to resolve this is to use the object-oriented interface to PDL::Graphics::Gnuplot (see "CONSTRUCTORS" below).

OPTIONS

Plot options

The plot options are a hash, passed as the initial arguments to the global plot() subroutine or as the only arguments to the PDL::Graphics::Gnuplot contructor. The supported keys of this hash are as follows:

title: Specifies the title of the plot
3d: If true, a 3D plot is constructed. This changes the default tuple size from 2 to 3
nogrid: By default a grid is drawn on the plot. If this option is true, this is turned off
globalwith: If no valid 'with' curve option is given, use this as a default
square, square_xy: If true, these request a square aspect ratio. For 3D plots, square_xy plots with a square aspect ratio in x and y, but scales z. Using either of these in 3D requires Gnuplot >= 4.4
xmin, xmax, ymin, ymax, zmin, zmax, y2min, y2max, cbmin, cbmax: If given, these set the extents of the plot window for the requested axes. The y2 axis is the secondary y-axis that is enabled by the 'y2' curve option. The 'cb' axis represents the color axis, used when color-coded plots are being generated
xlabel, ylabel, zlabel, y2label: These specify axis labels
hardcopy: Instead of drawing a plot on screen, plot into a file instead. The output filename is the value associated with this key. The output format is inferred from the filename. Currently only eps, ps, pdf, png are supported with some default sets of options. This option is simply a shorthand for the terminal and output options. If the defaults provided by the hardcopy option are insufficient, use terminal and output manually.
terminal: Sets the gnuplot terminal (with the gnuplot set terminal command). This determines what kind of output Gnuplot generates. See the Gnuplot docs for all the details.
output: Sets the plot output file (with the gnuplot set output command). You generally only need to set this if you're generating a hardcopy, such as a PDF.
extracmds: Arbitrary extra commands to pass to gnuplot before the plots are created. These are passed directly to gnuplot, without any validation. The value is either a string of an arrayref of different commands
dump: Used for debugging. If true, 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 this dump will contain binary data, if the binary plotting is enabled (see below)
log: 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 this log will contain binary data, if binary plotting is enabled (see below)
binary: If set, binary data is passed to gnuplot instead of ASCII data. Binary is much more efficient (and thus faster). Binary input works for most plots, but not for all of them. An example where binary plotting doesn't work is 'with labels'. The efficiency gains are well worth it most of the time, so binary is the default. Set binary => 0 to go back to ASCII.

Curve options

The curve options describe details of specific curves. They are in a hash, whose keys are as follows:

legend: Specifies the legend label for this curve
with: Specifies the style for this curve. The value is passed to gnuplot using its 'with' keyword, so valid values are whatever gnuplot supports. Read the gnuplot documentation for the 'with' keyword for more information
y2: If true, requests that this curve be plotted on the y2 axis instead of the main y axis
tuplesize: Specifies how many values represent each data point. For 2D plots this defaults to 2; for 3D plots this defaults to 3.

FUNCTIONS

plot

The main plotting routine in PDL::Graphics::Gnuplot.

Each plot() call creates a new plot in a new window.

plot(plot_options,
     curve_options, data, data, ... ,
     curve_options, data, data, ... );

Most of the arguments are optional.

use PDL::Graphics::Gnuplot qw(plot);
my $x = sequence(101) - 50;
plot($x**2);

See main POD for PDL::Graphics::Gnuplot for details.

plot3d

Generates 3D plots. Shorthand for plot('3d' => 1, ...)

plotlines

Generates plots with lines, by default. Shorthand for plot(globalwith => 'lines', ...)

plotpoints

Generates plots with points, by default. Shorthand for plot(globalwith => 'points', ...)

CONSTRUCTORS

new

Creates a PDL::Graphics::Gnuplot object to make a persistent plot.

my $plot = PDL::Graphics::Gnuplot->new(title => 'Object-oriented plot');
$plot->plot( legend => 'curve', sequence(5) );

The plot options are passed into the constructor; the curve options and the data are passed into the method. One advantage of making plots this way is that there's a gnuplot process associated with each PDL::Graphics::Gnuplot instance, so as long as $plot exists, the plot will be interactive. Also, calling $plot->plot() multiple times reuses the plot window instead of creating a new one.

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

plot($y);

If we also have a corresponding $x domain, we can plot $y vs. $x with

plot($x, $y);

Simple style control

To change line thickness:

plot(with => 'lines linewidth 4', $x, $y);

To change point size and point type:

plot(with => 'points pointtype 4 pointsize 8', $x, $y);

Errorbars

To plot errorbars that show $y +- 1, plotted with an implicit domain

plot(with => 'yerrorbars', tuplesize => 3,
     $y, $y->ones);

Same with an explicit $x domain:

plot(with => 'yerrorbars', tuplesize => 3,
     $x, $y, $y->ones);

Symmetric errorbars on both x and y. $x +- 1, $y +- 2:

plot(with => 'xyerrorbars', tuplesize => 4,
     $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)

plot(with => 'yerrorbars', tuplesize => 4,
     $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)

plot(with => 'circles', tuplesize => 3,
     $x, $y, $radii);

Plotting with an variably-sized arbitrary point type (size given in multiples of the "default" point size)

plot(with => 'points pointtype 7 pointsize variable', tuplesize => 3,
     $x, $y, $sizes);

Color-coded points

plot(with => 'points palette', tuplesize => 3,
     $x, $y, $colors);

Variable-size AND color-coded circles. A Gnuplot (4.4.0) quirk makes it necessary to specify the color range here

plot(cbmin => $mincolor, cbmax => $maxcolor,
     with => 'circles palette', tuplesize => 4,
     $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):

plot3d(square => 1, $x, $y, $z);

If $xy is a 2D piddle, we can plot it as a height map on an implicit domain

plot3d($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);

plot3d(title => 'double helix',

       { with => 'points pointsize variable pointtype 7 palette', tuplesize => 5,
         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:

plot3d( extracmds => 'set view map',
        with => 'image',
        $xy );

Hardcopies

To send any plot to a file, instead of to the screen, one can simply do

plot(hardcopy => 'output.pdf',
     $x, $y);

The hardcopy option is a shorthand for the terminal and output options. If more control is desired, the latter can be used. For example to generate a PDF of a particular size with a particular font size for the text, one can do

plot(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.

COMPATIBILITY

Everything should work on all platforms that support Gnuplot and Perl. Various flavors of GNU/Linux have been tested to work. Windows is known to not work at this time, but patches to change this are welcome.

REPOSITORY

https://github.com/dkogan/PDL-Graphics-Gnuplot

AUTHOR

Dima Kogan, <dima@secretsauce.net>

LICENSE AND COPYRIGHT

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 Artistic License.

See http://dev.perl.org/licenses/ for more information.

To install PDL::Graphics::Gnuplot, copy and paste the appropriate command in to your terminal.

cpanm

cpanm PDL::Graphics::Gnuplot

CPAN shell

perl -MCPAN -e shell
install PDL::Graphics::Gnuplot

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)