Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/dkogan/pdl-graphics-gnuplot

Gnuplot-based plotting backend for PDL
https://github.com/dkogan/pdl-graphics-gnuplot

Last synced: 4 months ago
JSON representation

Gnuplot-based plotting backend for PDL

Awesome Lists containing this project

README 

          
=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 NOTICE



Note that this is the original implementation of PDL::Graphics::Gnuplot by Dima

Kogan. It is here for reference only. Main development has been taken over by

Craig Deforest; the new git tree is at

L. Please submit bug reports

and patches there.



=cut

=head1 NAME



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



=head1 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);



=head1 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: L.



The main subroutine that C exports is C. A call

to C looks like



 plot(plot_options,

      curve_options, data, data, ... ,

      curve_options, data, data, ... );



=head2 Options arguments



Each set of options is a hash that can be passed inline or as a hashref: both

C 'Fancy plot!', ... )> and C 'Another fancy

plot'}, ...)> work. The plot options I 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 L"Plot options">.



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 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 L"Curve options">.



=head2 Data arguments



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

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 C curve option I 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.



=head3 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 I 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 C as the domain. This is why code

like C 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 C.



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 C 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 C 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, C is

interpreted as plotting $b vs $a, I $a vs an implicit domain and $b vs an

implicit domain. If 2 implicit plots are desired, add a separator:

C. Here C<{}> is an empty curve options hash. If C<$a> and C<$b>

have the same dimensions, one can also do Ccat($b))>, taking advantage

of PDL threading.



=head2 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 C 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 L"CONSTRUCTORS"> below).



=head1 OPTIONS



=head2 Plot options



The plot options are a hash, passed as the initial arguments to the global

C subroutine or as the only arguments to the PDL::Graphics::Gnuplot

contructor. The supported keys of this hash are as follows:



=over 2



=item title



Specifies the title of the plot



=item 3d



If true, a 3D plot is constructed. This changes the default tuple size from 2 to

3



=item nogrid



By default a grid is drawn on the plot. If this option is true, this is turned off



=item globalwith



If no valid 'with' curve option is given, use this as a default



=item 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



=item 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



=item xlabel, ylabel, zlabel, y2label



These specify axis labels



=item 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 C

and C options. If the defaults provided by the C option are

insufficient, use C and C manually.



=item terminal



Sets the gnuplot terminal (with the gnuplot C command). This

determines what kind of output Gnuplot generates. See the Gnuplot docs for all

the details.



=item output



Sets the plot output file (with the gnuplot C command). You

generally only need to set this if you're generating a hardcopy, such as a PDF.



=item 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



=item dump



Used for debugging. If true, writes out the gnuplot commands to STDOUT

I 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)



=item log



Used for debugging. If true, writes out the gnuplot commands to STDERR I to writing to a gnuplot process. This is I a dry run: data is

sent to gnuplot I to the log. Useful for debugging I/O issues. Note that

this log will contain binary data, if binary plotting is enabled (see below)



=item 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 C 0> to go back to ASCII.



=back



=head2 Curve options



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

keys are as follows:



=over 2



=item legend



Specifies the legend label for this curve



=item 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



=item y2



If true, requests that this curve be plotted on the y2 axis instead of the main y axis



=item tuplesize



Specifies how many values represent each data point. For 2D plots this defaults

to 2; for 3D plots this defaults to 3.



=back



=head1 FUNCTIONS



=head2 plot



=for ref



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



Each C call creates a new plot in a new window.



=for usage



 plot(plot_options,

      curve_options, data, data, ... ,

      curve_options, data, data, ... );



Most of the arguments are optional.



=for example



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

 my $x = sequence(101) - 50;

 plot($x**2);



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



=head2 plot3d



=for ref



Generates 3D plots. Shorthand for C 1, ...)>



=head2 plotlines



=for ref



Generates plots with lines, by default. Shorthand for C 'lines', ...)>



=head2 plotpoints



=for ref



Generates plots with points, by default. Shorthand for C 'points', ...)>



=head1 CONSTRUCTORS



=head2 new



=for ref



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



=for example



  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 C<$plot> exists, the plot will be interactive. Also, calling

C<$plot-Eplot()> multiple times reuses the plot window instead of creating a

new one.



=head1 RECIPES



Most of these come directly from Gnuplot commands. See the Gnuplot docs for

details.



=head2 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);



=head3 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);



=head3 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);



=head3 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);



=head2 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 );



=head2 Hardcopies



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



  plot(hardcopy => 'output.pdf',

       $x, $y);



The C option is a shorthand for the C and C

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 C shorthand used previously, but the

fonts and sizes can be changed.



=head1 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.



=head1 REPOSITORY



L



=head1 AUTHOR



Dima Kogan, C<<  >>



=head1 LICENSE AND COPYRIGHT



Copyright 2011, 2012 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 Artistic License.



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



=cut