Plotting with PDL::Graphics::Gnuplot

From pdl

(Difference between revisions)
Jump to: navigation, search
(Points and glyphs)
(Playing with axis direction and threading)
 
(46 intermediate revisions not shown)
Line 189: Line 189:
   
   
-
===Points and glyphs===
+
===Points, glyphs, and labels===
Basic point plots are OK, but there's so much *more*...
Basic point plots are OK, but there's so much *more*...
Line 225: Line 225:
[[Image: circles.png]]
[[Image: circles.png]]
-
;ellipses:accepts x, y, major_diameter, minor_diameter, angle.  If you omit the angle the ellipses are vertical.  If you omit the minor diameter, the ellipses are circles.
+
;ellipses:accepts x, y, major_diameter, minor_diameter, angle.  If you omit the angle the major diameter is horizontal.  If you omit the minor diameter, the ellipses are circles.
-
  $x = xvals(51);
+
Notice that the major diameter as delivered doesn't have to be the actual major diameter of the ellipse -- the ellipses at the left hand side of the plot have a "major diameter" that is small than their "minor diameter".
-
  $y = sin($x/5);
+
 
-
  $rmaj = sin($x/50*3.14159*2);
+
  $x = xvals(51)/50;
-
  $rmin = cos($x/50*3.14159*2);
+
  $y = $x**2;
-
  $w->plot(title=>"Ellipses", xlab=>"X value", ylab=>"Y value",
+
  $rmaj = sin($x*3.14159*2);
 +
  $rmin = cos($x*3.14159*2);
 +
$w = gpwin(png,output=>"ellipses.png", size=>[5,5,'in'],font=>',11');
 +
  $w->plot(title=>"Ellipses", xlab=>"X value", ylab=>"Y value",j=>1,
     with=>"ellipses",$x,$y,$rmaj, $rmin);
     with=>"ellipses",$x,$y,$rmaj, $rmin);
 +
[[Image: ellipses.png]]
-
;boxes:boxes
+
;labels:Places text labels at (x,y) locations on your plot.  You can also vary the size and color of the labels by feeding in additional columns. 
-
;labels:labels
+
The example text here shows both how to place generic labels around the field, and also how to modify their size.  It's a little awkward - you have to use the enhanced text mode to do so.  That requires using a "{/=<fontsize> foo}" string for each "foo" you want plotted.  We generate it on the fly with Perl's <code>map {} @list</code> construct.
-
;vectors:vectors
+
$t = xvals(8)*2*PI/7;
 +
$x = 10*sin($t); $x(7).=0;
 +
$y = 10*cos($t); $y(7).=0;
 +
$size = 12 + (xvals(8)==7)+9;
 +
$labels = ["Happy","Dopey","Sneezy","Lazy","Grumpy","Sleepy","Doc","Snow White"];
 +
$w=gpwin(png,out=>"labels.png",size=>[8,4,'in'],font=>',11', enhanced=>1);
 +
$w->multiplot(layout=>[2,1]);
 +
$w->plot(title=>"Labels with one font",xr=>[-12,12],yr=>[-12,12],
 +
                with=>"labels",$x,$y,$labels);
 +
$w->plot(title=>"Labels with variable size",xr=>[-12,12],yr=>[-12,12],
 +
                with=>"labels", $x, $y, [ map { "{/=".(12+9*m/White/)."$_}" } @$labels]);
 +
 
 +
 
 +
[[Image: labels.png]]
 +
 
 +
;vectors:You can plot vector fields using little arrows.  See the gnuplot documentation for how to modify the arrows' style -- you can.
 +
 
 +
$xy = ndcoords(11,11)->clump(1,2) - 5;
 +
$theta = 80*PI/180;
 +
$rotmat = pdl( [ cos($theta), sin($theta) ], [-sin($theta), cos($theta)]);
 +
$vec = $xy x $rotmat;
 +
$w=gpwin(png,output=>"vectors.png",size=>[4,4],font=>",11");
 +
$w->plot( {title=>"A simple vector field plot",j=>1}, with=>'vectors', $xy((0)), $xy((1)), $vec((0))/10, $vec((1))/10 );
 +
 
 +
[[Image: vectors.png]]
===Error bars===
===Error bars===
-
;yerrorbars, xerrorbars, xyerrorbars:
+
Error bar plots are the bread-and-butter of correct scientific plotting, and there are many to choose from.  Most of the styles can accept either a single error size (and create a symmetric error bar of that size, *relative* to each plotted point) or a pair of bounds (and create a not-necessarily-symmetric error bar between those *absolute* bounds for each plotted point).
-
;yerrorlines, xerrorlines, xyerrorlines:
+
;yerrorbars, xerrorbars, xyerrorbars: these are the basic bread-and-butter point plots, with I-beam error bars in the vertical and/or horizontal directions.
-
;boxerrorbars:boxes with yerrorbars
+
$x = xvals(31);
 +
$y = $x**2 / 30;
 +
$dy1 = 10*cos($x/2);
 +
$dy2 = 10*sin($x/2);
 +
$w=gpwin(png,output=>'errorbars.png',size=>[9,3],font=>',10',enh=>1);
 +
$w->multiplot(layout=>[3,1]);
 +
$w->options(yr=>[-30,30],xr=>[-15,35]);
 +
$w->plot( {title=>"{/=12 yerrorbars: absolute and relative}"},
 +
                  legend=>"Relative Y errorbars", with=>'yerrorbars', $x, $y, $dy1,
 +
                  legend=>"Absolute Y errorbars", with=>'yerrorbars', $x, $y/2-15, ($y-$dy1**2/3)/2-15, ($y+$dy2**2/3)/2-15
 +
                );
 +
$w->plot({title=>"{/=12 xerrorbars: absolute and relative}",key=>'bottom center'},
 +
                legend=>"Relative X errorbars", with=>'xerrorbars', $x, $y, $dy1,
 +
                legend=>"Absolute X errorbars", with=>'xerrorbars', $x, $y/2-15, ($x-$dy1**2/10), ($x+$dy2**2/10)
 +
                );
 +
$w->plot({title=>"{/=12 xyerrorbars: absolute and relative}",key=>'top left'},
 +
                legend=>"Relative XY errorbars", with=>'xyerrorbars', $x, $y, $dy1, $dy1,
 +
                legend=>"Absolute XY errorbars", with=>'xyerrorbars',
 +
                  $x, $y/2-15, ($x-$dy1**2/10), ($x+$dy2**2/10), ($y-$dy1**2/3)/2-15, ($y+$dy2**2/3)/2-15
 +
                );
 +
$w->end_multi;
-
;boxxyerrorbars: boxes with xyerrorbars
+
[[Image:xyerrorbars.png]]
-
;candlesticks: candlesticks
+
;yerrorlines, xerrorlines, xyerrorlines: These work just like the errorbars plots above, but connect the actual data points with line segments.
-
;financebars:financebars
+
;boxerrorbars and boxxyerrorbars: boxes (see the histogram plots), only ... with errorbars added.
 +
 
 +
;candlesticks and financebars: Candlestick style and stem-and-leaf style dual-error-bar plots.  They're used for financial reporting, and also for describing slightly more about your error distribution than just mean and standard deviation.
 +
 
 +
$x = xvals(18)+ asin((xvals(18)-3)%7 < 2); # some data, some nans;
 +
$ylo = $x * (0.9+0.1*sin($x/4));
 +
$yhi = $x * (1.28 + 0.1*sin($x/3));
 +
$ylolo = $x * 0.75;
 +
$yhihi = $x * 1.5;
 +
$w = gpwin(png,output=>"candlesticks.png",size=>[8,3],font=>',11');
 +
$w->multiplot(layout=>[2,1]);
 +
$w->plot({title=>"Candlesticks plot",boxwidth=>[0.25]},  with=>'candlesticks',$x,$ylo,$ylolo,$yhihi,$yhi);
 +
$w->plot({title=>"Financebars plot",bars=>[4]},  with=>'financebars',$x,$ylo,$ylolo,$yhihi,$yhi);
 +
$w->end_multi;
 +
 
 +
[[Image: candlesticks.png]]
===Histograms===
===Histograms===
-
;impulses:impulses
+
 
-
;histogram:histogram
+
;histogram:A basic histogram plot with boxes coming from zero.  If you combine multiple traces, their boxes are stacked side-by-side for each ordinate value. You can make filled-in boxes by modifying the plot style -- see the "with boxes" example, below.  The same style modifiers work here.
 +
 
 +
$y =  xvals(10)**2;
 +
$y2 = xvals(10) * 5;
 +
 +
$w = gpwin(png, output=>"histogram.png",size=>[5,3,'in'],font=>',11');
 +
$w->plot(title=>"A simple histogram example plot",
 +
                xlab=>"Sample number",ylab=>"Bogosity",with=>"histogram",$y,{},$y2);
 +
$w->close;
 +
 
 +
[[Image:histogram.png]]
 +
 
 +
;impulses:A line-style impulse plot.  This is sort of a "trivial" histogram - if the plot is dense enough, it becomes an area plot.
 +
 
 +
$x = xvals(18) * 20 * 3.14159 / 180;
 +
$y = sin($x);
 +
 +
$w = gpwin(png,output=>"impulses.png", size=>[5,3,'in'],font=>',11');
 +
$w->plot({title=>"A simple impuse plot",
 +
          xlab=>"X value", ylab=>"Y value"},
 +
          with=>'boxes', $x, $y);
 +
 
 +
[[Image:impulses.png]]
 +
 
 +
;boxes:Basic box-style histogram plot.  This is useful for histogram-style charts of a single variable (or multiple ones with overlays).  Multiple variables's boxes are superimposed rather than placed side-by-side.
 +
 
 +
$x = xvals(18) * 20 * 3.14159 / 180;
 +
$y = sin($x);
 +
 +
$w = gpwin(png,output=>"boxes.png", size=>[5,3,'in'],font=>',11');
 +
$w->plot({title=>"A simple histogram with boxes",
 +
          xlab=>"X value", ylab=>"Y value",
 +
          style=>"fill solid 0.3", boxwidth=>[0.8,'relative'] },
 +
          with=>'boxes', $x, $y);
-
;newhistogram:newhistogram
+
[[Image:boxes.png]]
===Images===
===Images===
Line 286: Line 382:
===Lines and points===
===Lines and points===
 +
Here is an example for how to plot a collection of curves in a 3D plot. It plots <math>x^y</math> for <math>-10<=x<=10</math> and <math>y \in [0,1,2,3,4]</math>.
 +
$x = sequence(101)->xlinvals(-10,10);
 +
$y = sequence(1,5);
 +
$z = $x**$y;
 +
$z/=$z->maximum->transpose; #normalize z curves so we can see the differences
 +
$yp = $y->(*$x->dim(0))->clump(2);
 +
$view = [60,30,1,1];
 +
$leg = [map{sprintf("x^%d",$_)}(0..4)];
 +
$w=gpwin('png',(output=>'3dlines.png',size=>[8,5,'in'],enhanced=>1));
 +
$w->plot({title=>"3D line plot (x^y)",view=>$view,trid=>1,xlabel=>"X", ylabel=>"y (power)",zlabel=>"x^y"},{legend=>$leg,with=>'lines linewidth 3'},$x,$yp,$z);
 +
[[File:3Dlines.png|500px|3D line plot]]
-
===Cylindrical and spherical plots===
+
===Wireframe surface plots===
-
===Surface plots===
+
You can plot surfaces as a wireframe by feeding 2-D data into the "lines" command.
 +
 
 +
$rv = rvals(51,51)/25 * 3.14159 * 4;
 +
$z = cos($rv) / (0.25 + $rv/3.15159);
 +
$w = gpwin('png',output=>'3dgrid.png',size=>[8,5,'in'],enhanced=>1);
 +
$w->plot3d({title=>"'with lines' in 3D mode gives a grid"}, with=>'lines', $z);
 +
 
 +
 
 +
[[File:3dgrid.png|500px|3D grid plot]]
 +
 
 +
===True surface plots===
 +
 
 +
To plot a real surface, use "with pm3d" .  In its simplest form you just feed in a single 2-D PDL and it will be automagically shaded using the default color map (you can use 'clut' to change the color map, or feed in color table parameters manually, just as with an image).
 +
 
 +
use PDL::Constants;
 +
$rv = rvals(51,51)/25 * PI * 4;
 +
$z = cos($rv) / (0.25 + $rv / PI);
 +
$w=gpwin('png',output=>'pm3d-simple.png',size=>[8,5,'in'], enhanced=>1);
 +
$w->plot3d({title=>"'with pm3d' with one 2-D PDL gives autoshading'"},with=>'pm3d',$z);
 +
 
 +
[[File: pm3d-simple.png|500px|Simple surface plot with pm3d]]
 +
 
 +
You can distort the image by feeding in an XY coordinate for every point.
 +
 +
use PDL::Constants;
 +
$rv = rvals(51,51)/25 * PI * 4;
 +
$z = cos($rv) / (0.25 + $rv/PI);
 +
$x = sqrt(xvals($rv));
 +
$y = yvals($rv) ** 2;
 +
$w=gpwin('png', output=>'pm3d-distorted.png',size=>[8,5,'in'],enhanced=>1);
 +
$w->plot3d({title=>"'with pm3d' with sqrt scaling in x and y^{2} scaling in y"},with=>'pm3d',$x,$y,$z);
 +
 
 +
[[File: pm3d-distorted.png|500px|Distorted surface plot with pm3d]]
==Contour plots==
==Contour plots==
Line 302: Line 441:
=Some complex examples=
=Some complex examples=
 +
 +
==Playing with axis direction and threading==
 +
 +
Here's an example involving plotting a vector field on top of an image.
 +
 +
## Data setup
 +
$tails = ndcoords(10,10)->mv(0,-1);        # a grid
 +
$rel_heads = pdl(sin(sequence(10,10)/10*PI),
 +
                  cos(sequence(10,10)/10*PI)
 +
                ) / 3;
 +
## Three panel plot
 +
$w=gpwin( pngcairo, output=>’axes.png’,size=>[12,4], font=>',10' );
 +
$w->multiplot(layout=>[3,1]);
 +
 +
$w->options(justify=>1, xlab=>”X”, ylab=>”Y”);
 +
$w->plot(with=>’image’, sequence(10,10),
 +
          with=>’vectors’, $tails->dog, $rel_heads->dog,                # 1D columns; thread over dim 1
 +
          {title=>”Image + 10 threaded vector fields”});
 +
 +
$w->plot(with=>’image’, sequence(10,10),
 +
          with=>’vectors’, cdim=>2, $tails->dog, $rel_heads->dog, # 2D column: do not thread over dim 1
 +
          {title=>”Image + single vector field”});
 +
 +
$w->plot(with=>’image’, sequence(10,10),
 +
          with=>’vectors’, cdim=>2, $tails->dog, $rel_heads->dog,
 +
          {title=>”video-indexing style image”, yrange=>[9.5,-0.1]}); # reverse direction of yrange
 +
 +
$w->end_multi;
 +
 +
[[Image: axes.png]]
 +
 +
==Rendering the Solar System==
 +
 +
Here's an example two-panel rendering of the geometry of several spacecraft in on 16-Dec-2008.  It shows two "overhead" views of the ecliptic plane, with relevant objects rendered as circles.
 +
 +
This is a little more complicated than it has to be, to demonstrate a couple of types of iteration over glyph lists, and drawing arbitrary shapes using "with lines".  The circular graticule, for example, could equally well be rendered in radial coordinate mode.
 +
 +
This code uses inline modifiers to the "with" specifier, which (as of PDL::Graphics::Gnuplot 1.3) still require interpolating Gnuplot command fragments into a string. That behavior should remain backward-compatible but will be replaced with hash ref parameter passing.
 +
 +
use PDL::NiceSlice; use PDL::Constants;
 +
 +
## Data entry
 +
$au = 1.496e8;  #km per AU
 +
$ace_heq    = pdl(1.0, 0) - pdl(1.408e6,-1.70e5) / $au;  # from ACE metadata
 +
$wind_heq  = pdl(1.0, 0) - pdl(1.6e6,    -1.5e5)  / $au;# from WIND metadata
 +
$s_a_heq    = pdl(1.069e11, 0.965e11) / 1e3 / $au;        # from STEREO-A metadata
 +
$s_b_heq    = pdl(1.112e11,-1.078e11) / 1e3 / $au;        # from STEREO-B metadata
 +
$earth_heq  = pdl(1.005, 0);  # Earth isn't always at 1.000 AU (surprise!)
 +
 
 +
 +
$oc = " offset character "; # Abbreviation used in table below
 +
$r = pdl(0.002); # Glyph radius in AU
 +
$s = sub { return sprintf("lc rgb \"%s\"",$_[0]);};  # CODE ref sets the "line" color for each glyph
 +
 +
# The list gets (name, coords, color, label-position).  Note the #rrggbb format for Earth's color.
 +
@list = ( [ "Earth",  [$earth_heq->dog, $r*10 ], &$s("#40e0e0"), "center $oc 0,1" ],
 +
          [ "Wind",    [$wind_heq->dog,  $r* 6 ], &$s("black"),  "right $oc -1,0" ],
 +
          [ "ACE",    [$ace_heq->dog,  $r* 6 ], &$s("magenta"), "center $oc 0,-1"],
 +
          [ "STEREO-A",[$s_a_heq->dog,  $r*10 ], &$s("blue"), "center $oc 0,-0.75"],
 +
          [ "STEREO-B",[$s_b_heq->dog,  $r*10 ], &$s("red"),  "center $oc 0, 0.5" ],
 +
          [ "Sun",    [pdl(0),pdl(0),pdl(0.05)], &$s("yellow"), "left $oc 1.5, 1" ] );
 +
 
 +
## Example of splicing together several circles into a single plottable line
 +
## The circles are found in the usual way, and are spliced together with NaN
 +
## in between them, to break the plotted line. This makes a set of coordinates
 +
## that draw a circular graticule using "with lines", given the radii of the circles.
 +
$circth = xvals(360+1) * PI / 180;
 +
$circx = sin($circth);
 +
$circy = cos($circth);
 +
$cir = sub { 
 +
  my @radii = dog shift;    my $nan = asin(pdl(1.1));
 +
  my @circxs = map { ( $circx * $_, $nan ) } @radii;
 +
  my @circys = map { ( $circy * $_, $nan ) } @radii;
 +
  return ( $nan->glue(0, @circxs), $nan->glue(0, @circys) );
 +
};
 +
 
 +
# Basic window construction, with a 2x1 multiplot
 +
$w = gpwin( png, output=>"solar_system.png",size=>[6,4.5,'in'],enh=>1, font=>',12');
 +
$w->multiplot(layout=>[2,1]);
 +
 
 +
# We make two plots with slightly different parameters, so why not
 +
# parameterize with a subroutine?
 +
$p = sub {
 +
  my( $xr, $yr, $title, $a, $radii, $scale ) = @_;
 +
 +
    #Figure projection values for the graticule labels
 +
    $xm = cos($a); $ym = sin($a);
 +
 +
  $w->plot(
 +
        {
 +
            xr=>$xr, yr=>$yr, title=>$title,
 +
            j=>1, xtics=>0, ytics=>0,
 +
        },
 +
 +
        ######## Concentric circles and their labels
 +
        with=>'lines ls 2 lw 2',                                     
 +
        &$cir($radii),
 +
        with=>'labels left offset 0.5, 0',
 +
        $radii * $xm, $radii * $ym,
 +
        [ map { sprintf( "{/=9 %g}\\n{/=9 AU}", $_, ) } $radii->list ],
 +
 +
        ######## A single glyph and label for each object
 +
        map {
 +
          ( with=>"circles fs solid $_->[2]",
 +
            $_->[1]->[0], $_->[1]->[1], $scale * $_->[1]->[2],
 +
            with=>"labels $_->[3]",
 +
            $_->[1]->[0], $_->[1]->[1], [$_->[0]]
 +
          )
 +
        } @list
 +
  );
 +
};
 +
 +
### Pedal hits the metal - generate two plots. 
 +
&$p( [-0.01, 1.1], [-0.8, 0.8], "2008-Dec-16 Ecliptic Plane",
 +
      -25*PI/180, (xvals(5)+1)/5, 1);
 +
&$p( [0.983, 1.009], [-0.019, 0.019], "2008-Dec-16 Near Earth",
 +
      -0.5*PI/180, pdl(985,990,995,1000,1005)/1000, 0.05);
 +
 +
### Close out window - necessary for some devices.  Also ends multiplot.
 +
$w->close;
 +
 +
[[Image: solar-system.png]]

Current revision as of 21:17, 11 March 2013

PDL::Graphics::Gnuplot is a plotting package for PDL. It is not currently included in the main PDL distribution - you can get it from CPAN, or from Github. It is a Perl-only layer that works with the standalone gnuplot plotting program. You can get gnuplot from the SourceForge site; it is also available pre-compiled for most common platforms (including Gnu/Linux, MacOS, and Microsoft Windows) via the usual package distribution channels for each platform.

Gnuplot can plot 2-D and 3-D lines, curves, surfaces, and scientific images in B/W, pseudocolor, or full RGBA color. It can render plots on many devices, including interactive screen display and publication-quality output formats such as PDF.

You can get full documentation for gnuplot itself at the gnuplot.info site, or for the module in its POD, which is quite extensive.

Here we include some cookbooks and recipes for simple plots.

Contents

Basics

You load PDL::Graphics::Gnuplot in the usual way. Two symbols are exported by default: gplot and gpwin. The former is a catch-all entry point for plotting stuff with usual subroutine-calling syntax. The latter is a constructor for the object oriented interface.

Plot syntax

The main entry point for plotting is the PDL::Graphics::Gnuplot::plot method, which is also exported by default as gplot. It accepts three kinds of arguments:

Plot options
these are named options that affect the appearance or behavior of the plot as a whole. They include things like 2D/3D selection, location of the legend (called the "key" by gnuplot), axis positioning and labeling, plot title, etc. You can set persistent plot options in the object itself with the options method, or just set transient ones on-the-fly in a call to plot. Plot options are supplied in a leading or trailing hash ref (or both) in the arg list.
Curve options
these are named options that affect an individual curve only, such as the curve style (set by the with option). Curve options can be run inline in the argument list, or can be supplied as a hash ref.
Data
Data for each plot are passed in as a collection of PDLs or array refs, called a "tuple". Each element of a "tuple" is called a "column", and represents some parameter of the data to be plotted -- e.g. ordinate, abscissa, color, glyph size, or error bar extent. Most types of plot use 1-D data; higher dimensions are threaded over, so you can pass in a 2-D column to generate many lines on a plot. Some types of plot use 2-D columns - for example, a grid mesh to be plotted in 3-D, or an image.

The argument list to plot thus contains:

  • an optional hash ref containing plot options;
  • Zero or more "curve blocks", each of which contains zero or more curve options followed by a tuple of data;
  • another optional hash ref containing plot options.

Because the size of a tuple is not known in advance (and different tuple sizes can change the style of plot), you *must* place either a curve option or an empty hash in between separate tuples. Curve options are cumulative, so you don't have to re-enter them for each curve block if they don't change. The empty hash between tuples serves to delimit curve blocks that have the same curve options.

The simplest plot

use PDL::Graphics::Gnuplot;
gplot( xvals(5)**2 );

That should produce a simple plot on your default output device. On most systems, it will appear on your screen and look more-or-less like this:

image:PGG-simple.png

Different systems will render the plot slightly differently because they use different output devices ("terminals") by default. On Linux it is X11; on MaxOS it is a program called AquaTerm. You can change the default output device with an environment variable.

Object Oriented plotting

It is recommended that you use the object-oriented interface. The exported constructor gpwin builds PDL::Graphics::Gnuplot objects, that represent a connection to a particular underlying gnuplot process. The objects store persistent options and other state, and you can use them to send the same plot to multiple devices (for example, to tweak a plot interactively so you like it, and then render it in a publication-quality form).

The constructor takes, as its first argument, the *name* of the output device (what gnuplot calles a "terminal") you want to use. The rest of the arguments are a collection of *terminal options* that modify the behavior of the terminal. Different terminals take different options. The enhanced option is a flag (on terminals that support it) indicating that you expect to use LaTeX-like markup for font and formatting information in text strings. Other common options include output (names an output file where appropriate), size (specifies an output size for the plot, in one of many convenient units), and font (names a system font and size to use by default for text markup on the plot).

use PDL::Graphics::Gnuplot;
$w = gpwin( wxt, enhanced=>1 ); # wxt is an anti-aliased X11 interactive terminal

Once you've defined an object, you can plot with it.

$x = xvals(51)/50;
$w = gpwin( png, output=>"PGG-points.png",size=>[320,240,'px'],font=>'Arial,9',enhanced=>1);
$w->plot( {key=>'top center'}, legend=>"x^2", with=>"points", $x, $x**2 );

should yield the following:

Image:PGG-points.png

Interactive plotting

There are several interactive output terminals. The wxt device is available on Gnu/Linux, MacOS, and Microsoft Windows, and allows you to pan and zoom the plot, and also to read off coordinates by placing the cursor over them. The wxt and x11 terminals also let you read mouse input into your script.

You can read mouse input like this:

$r = sin(rvals(51,51)/5) + sin(xvals(51,51)/10); # Generate some data
$w = gpwin(wxt);
$w->image($r);
($x,$y,$status) = $w->read_mouse();

The read_mouse() call will die unless $w is an interactive device that can accept mouse input. On return, $x and $y are the scientific coordinates of the click (in polar coordinates, they are actually *r* and *theta*); and $status is a hash containing mouse status. The "b" key points to the mouse button that was pressed, and the "m" key points to a string that indicates which, if any, modifier keys (like SHIFT) were pressed with the mouse button.

You can also read in a polygon with a simple event loop:

$r = sin(rvals(51,51)/5) + sin(xvals(51,51)/10); # Generate some data
$w = gpwin(wxt);
$w->image($r);
$p = $w->read_polygon();

read_polygon is a simple event loop that lets the user input a polygon with simple editing ("DEL" key works) and returns the coordinates of its vertices in a PDL. You can modify the event loop to do pretty much anything, by passing in code refs to carry out actions when specific buttons are pressed.


Display-and-save plots

If you are using object-oriented plotting, then you can generate and tweak your plot with an immediate display terminal like wxt, aqua, x11, or even dumb, then redirect the output to a publication-quality file format and replot directly to a file. You do it like this:

$w = gpwin(wxt); # or any immediate display device
$w->plot( with=>'points', xvals(5), xvals(5)**4 ); # or whatever
$w->output( png, output=>"foo.png" );  # or pdf, or jpg, or whatever format you want
$w->replot;

Remember that some formats, like pdf, require you to close the plot window before the plot is fully written to disk. (This is a requirement of gnuplot itself):

$w->close;

will close the file.

Basic examples of plot styles

Gnuplot treats plot styles on a per-curve basis, but the plot must be in 2-D or 3-D mode. The mode is set with the trid (synonym 3d) plot option flag (default value 0). If it is set to a true value the plot is in 3-D.

2-D plots

In 2-D, most of the plotting styles accept one-dimensional columns of data, each of which describes a curve or collection of points to be plotted. Feeding in columns with more dimensions causes those styles to thread, plotting multiple curves from the same tuple. In some cases, the plots behave differently depending on the number of columns in the tuple.

Lines, step functions, and filled curves

These curve styles are the workhorses of scientific plotting.

lines and linespoints
These are basic connect-the-dots styles with and without glyphs at the data points themselves.
 $x = xvals(101)/100;
 $y = cos( $x * 12 * 3.14 ) / (($x - 0.25)**2 + 0.2);
 
 $w = gpwin( png, output=>"lines.png",  size=>[5,3,'in'], font=>",11" );
 
 $w->plot( title=>"Lines and linespoints", xlab=>"X value", ylab=>"Y value",
          with=>"lines",       legend=>"lines",       $x,  $y,
          with=>"linespoints", legend=>"linespoints", $x, -$y
         );
 
 $w = gpwin( png, output=>"lines2.png",  size=>[5,3,'in'], font=>",11" );
 
 $w->plot( title=>"Lines and linespoints", xlab=>"Autogenerated X index", ylab=>"Y value",
          with=>"lines",       legend=>"lines",        $y,
          with=>"linespoints", legend=>"linespoints", -$y
         );


Image:lines.png Image:lines2.png

steps, fsteps, and histeps
The "steps" styles are useful for displaying data domain bins directly. The histeps style centers each range (Y) value on the corresponding domain location. The steps style places each range value between its associated domain point and the next one. The fsteps style places the range segment *before* the corresponding domain element.
$x = xvals(10);
$y = pdl(7,2,1,4,3,6,5,0,9,8);

$w = gpwin(png, output=>"steps.png", size=>[5,3,'in'], font=>",11");

$w->plot(title=>"Steps", xlab=>"X value", ylab=>"Y value", 
     with=>"histeps", legend=>"histeps", $x, $y,
     with=>"steps",   legend=>"steps",   $x+0.05, $y+0.05,
     with=>"fsteps",  legend=>"fsteps",  $x+0.10, $y+0.10
 );

Image:steps.png

filledcurves
There are several variants You can use filledcurves to draw a filled shape. If you feed in two columns of data, that is the default style:
$t = xvals(6) * 3.14159 * 4 / 5;
$x = cos($t); $y = sin($t);

$w = gpwin(png, output=>"star.png", size=>[4,3.5,'in'], font=>",11");
$w->plot( title=>"Star with filledcurves", justify=>1, xlab=>"X", ylab=>"Y",
         with=>filledcurves, $x, $y 
  );

Image:star.png

Other two-column variants include distance to an axis or line, and distance from a point:

$w = gpwin(png, output=>"filled.png", size=>[5,3,'in'], font=>",11");
 
$w->plot({title=>"Filled curves", xlab=>"X value", ylab=>"Y value",yrange=>[-1.5,1.5]},
       with=>"filledcurves y1=0",legend=>"filledcurves y1=0",xvals(10), sin(xvals(10)),
       with=>"filledcurves above x1",legend=>"filledcurves above x1", xvals(10),xvals(10)/10**2 - 0.5
  );

$w = gpwin(png, output=>"filled2.png", size=>[5,3,'in'],font=>",11");
 
$w->plot({title=>"Filled to a point", xlab=>"X value", ylab=>"Y value", yrange=>[0,8]}, 
       with=>"filledcurves xy=5,6", legend=>"filledcurves xy=5,6", xvals(31)/3, 1 - sin(xvals(31)/3)
   );

Image:filled.png Image:filled2.png

You can also fill the distance between two different curves, by feeding a third column into the tuple:

$x = xvals(10);
$yhi = sin($x) + 4 + $x/10;
$ylo = ($x**2)/50;
 
$w = gpwin(png, output=>"filled3.png", size=>[5,3,'in'], font=>",11");
$w->plot({yrange=>[0,8],title=>"Filled between curves", xlab=>"X value", ylab=>"Y value"},
    with=>"filledcurves", legend=>"filledcurves (3-tuple)", $x, $ylo, $yhi );

Image:filled3.png


Points, glyphs, and labels

Basic point plots are OK, but there's so much *more*...

points
glyphs at (x,y) locations. Shouldn't you be using one of the errorbars styles?
$w=gpwin(png, output=>"points.png", size=>[5,3,'in'],font=>',11');
$w->plot(title=>"Points. Yawn.",xlab=>"X value", ylab=>"Y value", 
     wi=>"points", le=>"sine",  xvals(46)*8,  sin(xvals(46)*3.14159*2/45),
     wi=>"points", le=>"flat",  xvals(46)*8, pdl(0)
 );

Image: points.png


dots
tiny points at (x,y) locations - useful for scatterplots. On pixelated devices like PNG or the screen, scatterplots can get overwhelmed quickly (this one does!) -- but on a high resolution device like a PDF, they are far more useful.
$a = rfits("/usr/local/src/PDL/m51.fits");
$b = $a->convolveND(ones(9,9)/81);
$w=gpwin(png, output=>"dots.png", size=>[4,4],font=>",11");
$w->plot(title=>"Image smear",xlab="Original image value", ylab=>"Smoothed image value",
      with=>'dots', $a->flat, $b->flat);

Image: dots.png

circles
useful for filled circles, outlined circles, or both.
$x = xvals(51);
$y = sin($x/5);
$r = cos($x/5) / 3;
$color = ($x-25)->abs;
$w = gpwin(png, output=>"circles.png", size=>[5,3,'in'],font=>',11');
$w->plot(title=>"Circles", xlab=>"X",ylab=>"Y",style=>"fill solid", 
       with=>"circles fillcolor palette", $x, $y, $r, $color);

Image: circles.png

ellipses
accepts x, y, major_diameter, minor_diameter, angle. If you omit the angle the major diameter is horizontal. If you omit the minor diameter, the ellipses are circles.

Notice that the major diameter as delivered doesn't have to be the actual major diameter of the ellipse -- the ellipses at the left hand side of the plot have a "major diameter" that is small than their "minor diameter".

$x = xvals(51)/50;
$y = $x**2;
$rmaj = sin($x*3.14159*2);
$rmin = cos($x*3.14159*2);
$w = gpwin(png,output=>"ellipses.png", size=>[5,5,'in'],font=>',11');
$w->plot(title=>"Ellipses", xlab=>"X value", ylab=>"Y value",j=>1,
   with=>"ellipses",$x,$y,$rmaj, $rmin);

Image: ellipses.png

labels
Places text labels at (x,y) locations on your plot. You can also vary the size and color of the labels by feeding in additional columns.

The example text here shows both how to place generic labels around the field, and also how to modify their size. It's a little awkward - you have to use the enhanced text mode to do so. That requires using a "{/=<fontsize> foo}" string for each "foo" you want plotted. We generate it on the fly with Perl's map {} @list construct.

$t = xvals(8)*2*PI/7;
$x = 10*sin($t); $x(7).=0;
$y = 10*cos($t); $y(7).=0;
$size = 12 + (xvals(8)==7)+9;
$labels = ["Happy","Dopey","Sneezy","Lazy","Grumpy","Sleepy","Doc","Snow White"];
$w=gpwin(png,out=>"labels.png",size=>[8,4,'in'],font=>',11', enhanced=>1);
$w->multiplot(layout=>[2,1]);
$w->plot(title=>"Labels with one font",xr=>[-12,12],yr=>[-12,12],
                with=>"labels",$x,$y,$labels);
$w->plot(title=>"Labels with variable size",xr=>[-12,12],yr=>[-12,12],
                with=>"labels", $x, $y, [ map { "{/=".(12+9*m/White/)."$_}" } @$labels]);


Image: labels.png

vectors
You can plot vector fields using little arrows. See the gnuplot documentation for how to modify the arrows' style -- you can.
$xy = ndcoords(11,11)->clump(1,2) - 5; 
$theta = 80*PI/180;
$rotmat = pdl( [ cos($theta), sin($theta) ], [-sin($theta), cos($theta)]);
$vec = $xy x $rotmat;
$w=gpwin(png,output=>"vectors.png",size=>[4,4],font=>",11");
$w->plot( {title=>"A simple vector field plot",j=>1}, with=>'vectors', $xy((0)), $xy((1)), $vec((0))/10, $vec((1))/10 );

Image: vectors.png

Error bars

Error bar plots are the bread-and-butter of correct scientific plotting, and there are many to choose from. Most of the styles can accept either a single error size (and create a symmetric error bar of that size, *relative* to each plotted point) or a pair of bounds (and create a not-necessarily-symmetric error bar between those *absolute* bounds for each plotted point).

yerrorbars, xerrorbars, xyerrorbars
these are the basic bread-and-butter point plots, with I-beam error bars in the vertical and/or horizontal directions.
$x = xvals(31);
$y = $x**2 / 30;
$dy1 = 10*cos($x/2);
$dy2 = 10*sin($x/2);
$w=gpwin(png,output=>'errorbars.png',size=>[9,3],font=>',10',enh=>1);
$w->multiplot(layout=>[3,1]);
$w->options(yr=>[-30,30],xr=>[-15,35]);
$w->plot( {title=>"{/=12 yerrorbars: absolute and relative}"},
                 legend=>"Relative Y errorbars", with=>'yerrorbars', $x, $y, $dy1,
                 legend=>"Absolute Y errorbars", with=>'yerrorbars', $x, $y/2-15, ($y-$dy1**2/3)/2-15, ($y+$dy2**2/3)/2-15
               );
$w->plot({title=>"{/=12 xerrorbars: absolute and relative}",key=>'bottom center'},
                legend=>"Relative X errorbars", with=>'xerrorbars', $x, $y, $dy1,
                legend=>"Absolute X errorbars", with=>'xerrorbars', $x, $y/2-15, ($x-$dy1**2/10), ($x+$dy2**2/10)
               );
$w->plot({title=>"{/=12 xyerrorbars: absolute and relative}",key=>'top left'},
                legend=>"Relative XY errorbars", with=>'xyerrorbars', $x, $y, $dy1, $dy1,
                legend=>"Absolute XY errorbars", with=>'xyerrorbars', 
                  $x, $y/2-15, ($x-$dy1**2/10), ($x+$dy2**2/10), ($y-$dy1**2/3)/2-15, ($y+$dy2**2/3)/2-15
               );
$w->end_multi;

Image:xyerrorbars.png

yerrorlines, xerrorlines, xyerrorlines
These work just like the errorbars plots above, but connect the actual data points with line segments.
boxerrorbars and boxxyerrorbars
boxes (see the histogram plots), only ... with errorbars added.
candlesticks and financebars
Candlestick style and stem-and-leaf style dual-error-bar plots. They're used for financial reporting, and also for describing slightly more about your error distribution than just mean and standard deviation.
$x = xvals(18)+ asin((xvals(18)-3)%7 < 2); # some data, some nans;
$ylo = $x * (0.9+0.1*sin($x/4));
$yhi = $x * (1.28 + 0.1*sin($x/3));
$ylolo = $x * 0.75;
$yhihi = $x * 1.5;
$w = gpwin(png,output=>"candlesticks.png",size=>[8,3],font=>',11');
$w->multiplot(layout=>[2,1]);
$w->plot({title=>"Candlesticks plot",boxwidth=>[0.25]},  with=>'candlesticks',$x,$ylo,$ylolo,$yhihi,$yhi);
$w->plot({title=>"Financebars plot",bars=>[4]},  with=>'financebars',$x,$ylo,$ylolo,$yhihi,$yhi);
$w->end_multi;

Image: candlesticks.png

Histograms

histogram
A basic histogram plot with boxes coming from zero. If you combine multiple traces, their boxes are stacked side-by-side for each ordinate value. You can make filled-in boxes by modifying the plot style -- see the "with boxes" example, below. The same style modifiers work here.
$y =   xvals(10)**2;
$y2 = xvals(10) * 5;

$w = gpwin(png, output=>"histogram.png",size=>[5,3,'in'],font=>',11');
$w->plot(title=>"A simple histogram example plot",
                xlab=>"Sample number",ylab=>"Bogosity",with=>"histogram",$y,{},$y2);
$w->close;

Image:histogram.png

impulses
A line-style impulse plot. This is sort of a "trivial" histogram - if the plot is dense enough, it becomes an area plot.
$x = xvals(18) * 20 * 3.14159 / 180;
$y = sin($x);

$w = gpwin(png,output=>"impulses.png", size=>[5,3,'in'],font=>',11');
$w->plot({title=>"A simple impuse plot", 
         xlab=>"X value", ylab=>"Y value"},
         with=>'boxes', $x, $y);

Image:impulses.png

boxes
Basic box-style histogram plot. This is useful for histogram-style charts of a single variable (or multiple ones with overlays). Multiple variables's boxes are superimposed rather than placed side-by-side.
$x = xvals(18) * 20 * 3.14159 / 180;
$y = sin($x);

$w = gpwin(png,output=>"boxes.png", size=>[5,3,'in'],font=>',11');
$w->plot({title=>"A simple histogram with boxes", 
         xlab=>"X value", ylab=>"Y value",
         style=>"fill solid 0.3", boxwidth=>[0.8,'relative'] },
         with=>'boxes', $x, $y);

Image:boxes.png

Images

image
image
rgbimage
rgbimage
rgbalpha
rgbalpha
fits
image with FITS WCS header


FITS files and the World Coordinate System

Plotting time values

Polar plots

Contour plots

3-D plots

Lines and points

Here is an example for how to plot a collection of curves in a 3D plot. It plots xy for − 10 < = x < = 10 and y \in [0,1,2,3,4].

$x = sequence(101)->xlinvals(-10,10);
$y = sequence(1,5);
$z = $x**$y;
$z/=$z->maximum->transpose; #normalize z curves so we can see the differences
$yp = $y->(*$x->dim(0))->clump(2);
$view = [60,30,1,1];
$leg = [map{sprintf("x^%d",$_)}(0..4)];
$w=gpwin('png',(output=>'3dlines.png',size=>[8,5,'in'],enhanced=>1));
$w->plot({title=>"3D line plot (x^y)",view=>$view,trid=>1,xlabel=>"X", ylabel=>"y (power)",zlabel=>"x^y"},{legend=>$leg,with=>'lines linewidth 3'},$x,$yp,$z);

3D line plot

Wireframe surface plots

You can plot surfaces as a wireframe by feeding 2-D data into the "lines" command.

$rv = rvals(51,51)/25 * 3.14159 * 4;
$z = cos($rv) / (0.25 + $rv/3.15159);
$w = gpwin('png',output=>'3dgrid.png',size=>[8,5,'in'],enhanced=>1);
$w->plot3d({title=>"'with lines' in 3D mode gives a grid"}, with=>'lines', $z);


3D grid plot

True surface plots

To plot a real surface, use "with pm3d" . In its simplest form you just feed in a single 2-D PDL and it will be automagically shaded using the default color map (you can use 'clut' to change the color map, or feed in color table parameters manually, just as with an image).

use PDL::Constants;
$rv = rvals(51,51)/25 * PI * 4;
$z = cos($rv) / (0.25 + $rv / PI);
$w=gpwin('png',output=>'pm3d-simple.png',size=>[8,5,'in'], enhanced=>1);
$w->plot3d({title=>"'with pm3d' with one 2-D PDL gives autoshading'"},with=>'pm3d',$z);

Simple surface plot with pm3d

You can distort the image by feeding in an XY coordinate for every point.

use PDL::Constants;
$rv = rvals(51,51)/25 * PI * 4;
$z = cos($rv) / (0.25 + $rv/PI);
$x = sqrt(xvals($rv));
$y = yvals($rv) ** 2;
$w=gpwin('png', output=>'pm3d-distorted.png',size=>[8,5,'in'],enhanced=>1);
$w->plot3d({title=>"'with pm3d' with sqrt scaling in x and y^{2} scaling in y"},with=>'pm3d',$x,$y,$z);

Distorted surface plot with pm3d

Contour plots

Getting Fancy

Text Markup

Labels on your Plots

Fancy Axes and Tick Marks

Some complex examples

Playing with axis direction and threading

Here's an example involving plotting a vector field on top of an image.

## Data setup
$tails = ndcoords(10,10)->mv(0,-1);        # a grid
$rel_heads = pdl(sin(sequence(10,10)/10*PI),
                 cos(sequence(10,10)/10*PI)
                ) / 3;
## Three panel plot
$w=gpwin( pngcairo, output=>’axes.png’,size=>[12,4], font=>',10' );
$w->multiplot(layout=>[3,1]);

$w->options(justify=>1, xlab=>”X”, ylab=>”Y”);
$w->plot(with=>’image’, sequence(10,10),	
         with=>’vectors’, $tails->dog, $rel_heads->dog,                 # 1D columns; thread over dim 1
         {title=>”Image + 10 threaded vector fields”});

$w->plot(with=>’image’, sequence(10,10),	
         with=>’vectors’, cdim=>2, $tails->dog, $rel_heads->dog, # 2D column: do not thread over dim 1
         {title=>”Image + single vector field”});

$w->plot(with=>’image’, sequence(10,10),	
         with=>’vectors’, cdim=>2, $tails->dog, $rel_heads->dog,
         {title=>”video-indexing style image”, yrange=>[9.5,-0.1]}); # reverse direction of yrange

$w->end_multi;

Image: axes.png

Rendering the Solar System

Here's an example two-panel rendering of the geometry of several spacecraft in on 16-Dec-2008. It shows two "overhead" views of the ecliptic plane, with relevant objects rendered as circles.

This is a little more complicated than it has to be, to demonstrate a couple of types of iteration over glyph lists, and drawing arbitrary shapes using "with lines". The circular graticule, for example, could equally well be rendered in radial coordinate mode.

This code uses inline modifiers to the "with" specifier, which (as of PDL::Graphics::Gnuplot 1.3) still require interpolating Gnuplot command fragments into a string. That behavior should remain backward-compatible but will be replaced with hash ref parameter passing.

use PDL::NiceSlice; use PDL::Constants;

## Data entry
$au = 1.496e8;   #km per AU
$ace_heq    = pdl(1.0, 0) - pdl(1.408e6,-1.70e5) / $au;   # from ACE metadata
$wind_heq   = pdl(1.0, 0) - pdl(1.6e6,    -1.5e5)   / $au;# from WIND metadata
$s_a_heq    = pdl(1.069e11, 0.965e11) / 1e3 / $au;        # from STEREO-A metadata
$s_b_heq    = pdl(1.112e11,-1.078e11) / 1e3 / $au;        # from STEREO-B metadata
$earth_heq  = pdl(1.005, 0);  # Earth isn't always at 1.000 AU (surprise!)
 

$oc = " offset character "; # Abbreviation used in table below
$r = pdl(0.002); # Glyph radius in AU
$s = sub { return sprintf("lc rgb \"%s\"",$_[0]);};  # CODE ref sets the "line" color for each glyph

# The list gets (name, coords, color, label-position).  Note the #rrggbb format for Earth's color.
@list = ( [ "Earth",   [$earth_heq->dog, $r*10 ], &$s("#40e0e0"), "center $oc 0,1" ],
          [ "Wind",    [$wind_heq->dog,  $r* 6 ], &$s("black"),   "right $oc -1,0" ],
          [ "ACE",     [$ace_heq->dog,   $r* 6 ], &$s("magenta"), "center $oc 0,-1"],
          [ "STEREO-A",[$s_a_heq->dog,   $r*10 ], &$s("blue"), "center $oc 0,-0.75"],
          [ "STEREO-B",[$s_b_heq->dog,   $r*10 ], &$s("red"),  "center $oc 0, 0.5" ],
          [ "Sun",     [pdl(0),pdl(0),pdl(0.05)], &$s("yellow"), "left $oc 1.5, 1" ] );
 
## Example of splicing together several circles into a single plottable line
## The circles are found in the usual way, and are spliced together with NaN
## in between them, to break the plotted line. This makes a set of coordinates
## that draw a circular graticule using "with lines", given the radii of the circles.
$circth = xvals(360+1) * PI / 180; 
$circx = sin($circth);
$circy = cos($circth);
$cir = sub {   
  my @radii = dog shift;     my $nan = asin(pdl(1.1));
  my @circxs = map { ( $circx * $_, $nan ) } @radii;
  my @circys = map { ( $circy * $_, $nan ) } @radii;
  return ( $nan->glue(0, @circxs), $nan->glue(0, @circys) );
};
 
# Basic window construction, with a 2x1 multiplot
$w = gpwin( png, output=>"solar_system.png",size=>[6,4.5,'in'],enh=>1, font=>',12');
$w->multiplot(layout=>[2,1]);
 
# We make two plots with slightly different parameters, so why not 
# parameterize with a subroutine?
$p = sub {
  my( $xr, $yr, $title, $a, $radii, $scale ) = @_;

   #Figure projection values for the graticule labels
   $xm = cos($a); $ym = sin($a);

  $w->plot( 
       {
           xr=>$xr, yr=>$yr, title=>$title,
           j=>1, xtics=>0, ytics=>0,
       },

       ######## Concentric circles and their labels
       with=>'lines ls 2 lw 2',                                      
       &$cir($radii),
       with=>'labels left offset 0.5, 0',
       $radii * $xm, $radii * $ym, 
       [ map { sprintf( "{/=9 %g}\\n{/=9 AU}", $_, ) } $radii->list ],

       ######## A single glyph and label for each object
       map { 
         ( with=>"circles fs solid $_->[2]",
           $_->[1]->[0], $_->[1]->[1], $scale * $_->[1]->[2],
           with=>"labels $_->[3]",
           $_->[1]->[0], $_->[1]->[1], [$_->[0]]
         )
        } @list
  );
};

### Pedal hits the metal - generate two plots.  
&$p( [-0.01, 1.1], [-0.8, 0.8], "2008-Dec-16 Ecliptic Plane", 
     -25*PI/180, (xvals(5)+1)/5, 1);
&$p( [0.983, 1.009], [-0.019, 0.019], "2008-Dec-16 Near Earth",
     -0.5*PI/180, pdl(985,990,995,1000,1005)/1000, 0.05); 

### Close out window - necessary for some devices.  Also ends multiplot.
$w->close;

Image: solar-system.png

Personal tools