PDL::Graphics::PLplot - Object-oriented interface from perl/PDL to the PLPLOT plotting library
use PDL; use PDL::Graphics::PLplot; my $pl = PDL::Graphics::PLplot->new (DEV => "png", FILE => "test.png"); my $x = sequence(10); my $y = $x**2; $pl->xyplot($x, $y); $pl->close;
For more information on PLplot, see
http://www.plplot.org/
Also see the test file, t/plplot.pl in this distribution for some working examples.
This is the PDL interface to the PLplot graphics library. It is designed to be simple and light weight with a familiar 'perlish' Object Oriented interface.
The following options are supported. Most options can be used with any function. A few are only supported on the call to 'new'.
Set the color for index 0, the plot background
Set the output device type. To see a list of allowed types, try:
PDL::Graphics::PLplot->new();
PDL::Graphics::PLplot->new(DEV => 'png', FILE => 'test.png');
Set the output file or display. For file output devices, sets the output file name. For graphical displays (like 'xwin') sets the name of the display, eg ('hostname.foobar.com:0')
'xwin'
'hostname.foobar.com:0'
PDL::Graphics::PLplot->new(DEV => 'png', FILE => 'test.png'); PDL::Graphics::PLplot->new(DEV => 'xwin', FILE => ':0');
Set plotting options. See the PLplot documentation for the complete listing of available options. The value of 'OPTS' must be a hash reference, whose keys are the names of the options. For instance, to obtain PostScript fonts with the ps output device, use:
'OPTS'
PDL::Graphics::PLplot->new(DEV => 'ps', OPTS => {drvopt => 'text=1'});
This option is used in conjunction with DEV => 'mem'. This option takes as input a PDL image and allows one to 'decorate' it using PLplot. The 'decorated' PDL image can then be written to an image file using, for example, PDL::IO::Pic. This option may not be available if plplot does not include the 'mem' driver.
DEV => 'mem'
# read in Earth image and draw an equator. my $pl = PDL::Graphics::PLplot->new (MEM => $earth, DEV => 'mem'); my $x = pdl(-180, 180); my $y = zeroes(2); $pl->xyplot($x, $y, BOX => [-180,180,-90,90], VIEWPORT => [0.0, 1.0, 0.0, 1.0], XBOX => '', YBOX => '', PLOTTYPE => 'LINE'); $pl->close;
Set color index 1, the frame color
A flag used to specify equal scale on the axes. If this is not specified, the default is to scale the axes to fit best on the page.
PDL::Graphics::PLplot->new(DEV => 'png', FILE => 'test.png', JUST => 1);
The orientation of the plot:
0 -- 0 degrees (landscape mode) 1 -- 90 degrees (portrait mode) 2 -- 180 degrees (seascape mode) 3 -- 270 degrees (upside-down mode)
Intermediate values (0.2) are acceptable if you are feeling daring.
# portrait orientation PDL::Graphics::PLplot->new(DEV => 'png', FILE => 'test.png', ORIENTATION => 1);
Set the size in pixels of the output page.
# PNG 500 by 600 pixels PDL::Graphics::PLplot->new(DEV => 'png', FILE => 'test.png', PAGESIZE => [500,600]);
Set the number of sub pages in the plot, [$nx, $ny]
# PNG 300 by 600 pixels # Two subpages stacked on top of one another. PDL::Graphics::PLplot->new(DEV => 'png', FILE => 'test.png', PAGESIZE => [300,600], SUBPAGES => [1,2]);
Set the plotting box in world coordinates. Used to explicitly set the size of the plotting area.
my $pl = PDL::Graphics::PLplot->new(DEV => 'png', FILE => 'test.png'); $pl->xyplot ($x, $y, BOX => [0,100,0,200]);
Set the size of text in multiples of the default size. CHARSIZE => 1.5 gives characters 1.5 times the normal size.
CHARSIZE => 1.5
Set the current color for plotting and character drawing. Colors are specified not as color indices but as RGB triples. Some pre-defined triples are included:
BLACK GREEN WHEAT BLUE RED AQUAMARINE GREY BLUEVIOLET YELLOW PINK BROWN CYAN TURQUOISE MAGENTA SALMON WHITE ROYALBLUE DEEPSKYBLUE VIOLET STEELBLUE1 DEEPPINK MAGENTA DARKORCHID1 PALEVIOLETRED2 TURQUOISE1 LIGHTSEAGREEN SKYBLUE FORESTGREEN CHARTREUSE3 GOLD2 SIENNA1 CORAL HOTPINK LIGHTCORAL LIGHTPINK1 LIGHTGOLDENROD
# These two are equivalent: $pl->xyplot ($x, $y, COLOR => 'YELLOW'); $pl->xyplot ($x, $y, COLOR => [0,255,0]);
Set the line width for plotting. Values range from 1 to a device dependent maximum.
Set the line style for plotting. Pre-defined line styles use values 1 to 8, one being a solid line, 2-8 being various dashed patterns.
Set the length of major ticks as a fraction of the default setting. One (default) means leave these ticks the normal size.
Set the length of minor ticks (and error bar terminals) as a fraction of the default setting. One (default) means leave these ticks the normal size.
The number of minor tick marks between each major tick mark on the X axis. Specify zero (default) to let PLplot compute this automatically.
The number of minor tick marks between each major tick mark on the Y axis. Specify zero (default) to let PLplot compute this automatically.
Load pre-defined color map 1 color ranges. Currently, values include:
RAINBOW -- from Red to Violet through the spectrum REVERSERAINBOW -- Violet through Red GREYSCALE -- from black to white via grey. REVERSEGREYSCALE -- from white to black via grey. GREENRED -- from green to red REDGREEN -- from red to green
# Plot x/y points with the z axis in color $pl->xyplot ($x, $y, PALETTE => 'RAINBOW', PLOTTYPE => 'POINTS', COLORMAP => $z);
Specify which type of XY plot is desired:
LINE -- A line POINTS -- A bunch of symbols LINEPOINTS -- both
Set which subpage to plot on. Subpages are numbered 1 to N. A zero can be specified meaning 'advance to the next subpage' (just a call to pladv()).
my $pl = PDL::Graphics::PLplot->new(DEV => 'png', FILE => 'test.png', SUBPAGES => [1,2]); $pl->xyplot ($x, $y, SUBPAGE => 1); $pl->xyplot ($a, $b, SUBPAGE => 2);
Specify which symbol to use when plotting PLOTTYPE => 'POINTS'. A large variety of symbols are available, see: http://plplot.sourceforge.net/examples-data/demo07/x07.*.png, where * is 01 - 17.
PLOTTYPE => 'POINTS'
Specify the size of symbols plotted in multiples of the default size (1). Value are real numbers from 0 to large.
Specify the placement of text. Either relative to border, specified as:
[$side, $disp, $pos, $just]
Where
side = 't', 'b', 'l', or 'r' for top, bottom, left and right disp is the number of character heights out from the edge pos is the position along the edge of the viewport, from 0 to 1. just tells where the reference point of the string is: 0 = left, 1 = right, 0.5 = center.
or inside the plot window, specified as:
[$x, $y, $dx, $dy, $just]
x = x coordinate of reference point of string. y = y coordinate of reference point of string. dx Together with dy, this specifies the inclination of the string. The baseline of the string is parallel to a line joining (x, y) to (x+dx, y+dy). dy Together with dx, this specifies the inclination of the string. just Specifies the position of the string relative to its reference point. If just=0, the reference point is at the left and if just=1, it is at the right of the string. Other values of just give intermediate justifications.
# Plot text on top of plot $pl->text ("Top label", TEXTPOSITION => ['t', 4.0, 0.5, 0.5]); # Plot text in plotting area $pl->text ("Line label", TEXTPOSITION => [50, 60, 5, 5, 0.5]);
Add a title on top of a plot.
# Plot text on top of plot $pl->xyplot ($x, $y, TITLE => 'X vs. Y');
Set the location of the plotting window on the page. Takes a four element array ref specifying:
xmin -- The coordinate of the left-hand edge of the viewport. (0 to 1) xmax -- The coordinate of the right-hand edge of the viewport. (0 to 1) ymin -- The coordinate of the bottom edge of the viewport. (0 to 1) ymax -- The coordinate of the top edge of the viewport. (0 to 1)
# Make a small plotting window in the lower left of the page $pl->xyplot ($x, $y, VIEWPORT => [0.1, 0.5, 0.1, 0.5]); # Also useful in creating color keys: $pl->xyplot ($x, $y, PALETTE => 'RAINBOW', PLOTTYPE => 'POINTS', COLORMAP => $z); $pl->colorkey ($z, 'v', VIEWPORT => [0.93, 0.96, 0.15, 0.85]);
Specify how to label the X axis of the plot as a string of option letters:
a: Draws axis, X-axis is horizontal line (y=0), and Y-axis is vertical line (x=0). b: Draws bottom (X) or left (Y) edge of frame. c: Draws top (X) or right (Y) edge of frame. f: Always use fixed point numeric labels. g: Draws a grid at the major tick interval. h: Draws a grid at the minor tick interval. i: Inverts tick marks, so they are drawn outwards, rather than inwards. l: Labels axis logarithmically. This only affects the labels, not the data, and so it is necessary to compute the logarithms of data points before passing them to any of the drawing routines. m: Writes numeric labels at major tick intervals in the unconventional location (above box for X, right of box for Y). n: Writes numeric labels at major tick intervals in the conventional location (below box for X, left of box for Y). s: Enables subticks between major ticks, only valid if t is also specified. t: Draws major ticks.
The default is 'BCNST' which draws lines around the plot, draws major and minor ticks and labels major ticks.
'BCNST'
# plot two lines in a box with independent X axes labeled # differently on top and bottom $pl->xyplot($x1, $y, XBOX => 'bnst', # bottom line, bottom numbers, ticks, subticks YBOX => 'bnst'); # left line, left numbers, ticks, subticks $pl->xyplot($x2, $y, XBOX => 'cmst', # top line, top numbers, ticks, subticks YBOX => 'cst', # right line, ticks, subticks BOX => [$x2->minmax, $y->minmax]);
Used only with "xyplot". Draws horizontal error bars at all points ($x, $y) in the plot. Specify a PDL containing the same number of points as $x and $y which specifies the width of the error bar, which will be centered at ($x, $y).
$x
$y
Specify a label for the X axis.
Interval (in graph units/world coordinates) between major x axis tick marks. Specify zero (default) to allow PLplot to compute this automatically.
Specify how to label the Y axis of the plot as a string of option letters. See "XBOX".
Used only for xyplot. Draws vertical error bars at all points ($x, $y) in the plot. Specify a PDL containing the same number of points as $x and $y which specifies the width of the error bar, which will be centered at ($x, $y).
Specify a label for the Y axis.
Interval (in graph units/world coordinates) between major y axis tick marks. Specify zero (default) to allow PLplot to compute this automatically.
For "xyplot" (when COLORMAP is specified), for "shadeplot" and for "colorkey". Normally, the range of the Z variable (color) is taken as $z->minmax. If a different range is desired, specify it in ZRANGE, like so:
COLORMAP
$z->minmax
ZRANGE
$pl->shadeplot ($z, $nlevels, PALETTE => 'GREENRED', ZRANGE => [0,100]);
or
$pl->xyplot ($x, $y, PALETTE => 'RAINBOW', PLOTTYPE => 'POINTS', COLORMAP => $z, ZRANGE => [-90,-20]); $pl->colorkey ($z, 'v', VIEWPORT => [0.93, 0.96, 0.13, 0.85], ZRANGE => [-90,-20]);
Create an object representing a plot.
Arguments: none. Supported options: BACKGROUND DEV FILE FRAMECOLOR JUST PAGESIZE SUBPAGES
my $pl = PDL::Graphics::PLplot->new(DEV => 'png', FILE => 'test.png');
Set options for a plot object.
Arguments: none. Supported options: All options except: BACKGROUND DEV FILE FRAMECOLOR JUST PAGESIZE SUBPAGES (These must be set in call to 'new'.)
$pl->setparm (TEXTSIZE => 2);
Plot XY lines and/or points. Also supports color scales for points. This function works with bad values. If a bad value is specified for a points plot, it is omitted. If a bad value is specified for a line plot, the bad value makes a gap in the line. This is useful for drawing maps; for example $x and $y can be the continent boundary latitude and longitude.
Arguments: $x, $y Supported options: All options except: BACKGROUND DEV FILE FRAMECOLOR JUST PAGESIZE SUBPAGES (These must be set in call to 'new'.)
$pl->xyplot($x, $y, PLOTTYPE => 'POINTS', COLOR => 'BLUEVIOLET', SYMBOL => 1, SYMBOLSIZE => 4); $pl->xyplot($x, $y, PLOTTYPE => 'LINEPOINTS', COLOR => [50,230,30]); $pl->xyplot($x, $y, PALETTE => 'RAINBOW', PLOTTYPE => 'POINTS', COLORMAP => $z);
Plot a set of strip plots with a common X axis, but with different Y axes. Looks like a stack of long, thin XY plots, all line up on the same X axis.
Arguments: $x -- 1D PDL with common X axis values, length = N $ys -- 2D PDL with M Y-axis values: N x M %opts -- Options hash Supported options: All options except: BACKGROUND DEV FILE FRAMECOLOR JUST PAGESIZE SUBPAGES (These must be set in call to 'new'.)
my $x = sequence(20); my $y1 = $x**2; my $y2 = sqrt($x); my $y3 = $x**3; my $y4 = sin(($x/20) * 2 * $pi); $ys = cat($y1, $y2, $y3, $y4); $pl->stripplots($x, $ys, PLOTTYPE => 'LINE', TITLE => 'functions', YLAB => ['x**2', 'sqrt(x)', 'x**3', 'sin(x/20*2pi)'], COLOR => ['GREEN', 'DEEPSKYBLUE', 'DARKORCHID1', 'DEEPPINK'], XLAB => 'X label'); In addition, COLOR may be specified as a reference to a list of colors. If this is done, the colors are applied separately to each plot. Also, the options Y_BASE and Y_GUTTER can be specified. Y_BASE gives the Y offset of the bottom of the lowest plot (0-1, specified like a VIEWPORT, defaults to 0.1) and Y_GUTTER gives the gap between the graphs (0-1, default = 0.02).
Plot a color key showing which color represents which value
Arguments: $range : A PDL which tells the range of the color values $orientation : 'v' for vertical color key, 'h' for horizontal Supported options: All options except: BACKGROUND DEV FILE FRAMECOLOR JUST PAGESIZE SUBPAGES (These must be set in call to 'new'.)
# Plot X vs. Y with Z shown by the color. Then plot # vertical key to the right of the original plot. $pl->xyplot ($x, $y, PALETTE => 'RAINBOW', PLOTTYPE => 'POINTS', COLORMAP => $z); $pl->colorkey ($z, 'v', VIEWPORT => [0.93, 0.96, 0.15, 0.85]);
Create a shaded contour plot of 2D PDL 'z' with 'nsteps' contour levels. Linear scaling is used to map the coordinates of Z(X, Y) to world coordinates via the "BOX" option.
Arguments: $z : A 2D PDL which contains surface values at each XY coordinate. $nsteps : The number of contour levels requested for the plot. Supported options: All options except: BACKGROUND DEV FILE FRAMECOLOR JUST PAGESIZE SUBPAGES (These must be set in call to 'new'.)
# vertical key to the right of the original plot. # The BOX must be specified to give real coordinate values to the $z array. $pl->shadeplot ($z, $nsteps, BOX => [-1, 1, -1, 1], PALETTE => 'RAINBOW', ZRANGE => [0,100]); $pl->colorkey ($z, 'v', VIEWPORT => [0.93, 0.96, 0.15, 0.85], ZRANGE => [0,100]);
Create a histogram of a 1-D variable.
Arguments: $x : A 1D PDL $nbins : The number of bins to use in the histogram. Supported options: All options except: BACKGROUND DEV FILE FRAMECOLOR JUST PAGESIZE SUBPAGES (These must be set in call to 'new'.)
$pl->histogram ($x, $nbins, BOX => [$min, $max, 0, 100]);
Simple utility to plot a bar chart with labels on the X axis. The usual options can be specified, plus one other: MAXBARLABELS specifies the maximum number of labels to allow on the X axis. The default is 20. If this value is exceeded, then every other label is plotted. If twice MAXBARLABELS is exceeded, then only every third label is printed, and so on.
Arguments: $labels -- A reference to a perl list of strings. $values -- A PDL of values to be plotted. Supported options: All options except: BACKGROUND DEV FILE FRAMECOLOR JUST PAGESIZE SUBPAGES (These must be set in call to 'new'.)
$labels = ['one', 'two', 'three']; $values = pdl(1, 2, 3); # Note if TEXTPOSITION is specified, it must be in 4 argument mode (border mode): # [$side, $disp, $pos, $just] # # Where side = 't', 'b', 'l', or 'r' for top, bottom, left and right # 'tv', 'bv', 'lv' or 'rv' for top, bottom, left or right perpendicular to the axis. # # disp is the number of character heights out from the edge # pos is the position along the edge of the viewport, from 0 to 1. # just tells where the reference point of the string is: 0 = left, 1 = right, 0.5 = center. # # The '$pos' entry will be ignored (computed by the bargraph routine) $pl->bargraph($labels, $values, MAXBARLABELS => 30, TEXTPOSITION => ['bv', 0.5, 1.0, 1.0]);
Write text on a plot. Text can either be written with respect to the borders or at an arbitrary location and angle (see the "TEXTPOSITION" entry).
Arguments: $t : The text. Supported options: All options except: BACKGROUND DEV FILE FRAMECOLOR JUST PAGESIZE SUBPAGES (These must be set in call to 'new'.)
$pl->text("Count", COLOR => 'PINK', TEXTPOSITION => ['t', 3, 0.5, 0.5]); # top, 3 units out, string ref. pt in # center of string, middle of axis
Close a PLplot object, writing out the file and cleaning up.
Arguments: None
Returns: Nothing
This closing of the PLplot object can be done explicitly though the 'close' method. Alternatively, a DESTROY block does an automatic close whenever the PLplot object passes out of scope.
$pl->close;
The PDL low-level interface to the PLplot library closely mimics the C API. Users are referred to the PLplot User's Manual, distributed with the source PLplot tarball. This manual is also available on-line at the PLplot web site (http://www.plplot.org/).
There are though two differences in way the functions are called. The first one is due to a limitation in the pp_def wrapper of PDL, which forces all the non-piddle arguments to be at the end of the arguments list. It is the case of strings (char *) arguments in the C API. This affects the following functions [shown below with their prototypes in PDL, with arguments preceded by "(pdl)" are piddle-convertible; see the PLplot manual for the meaning of the arguments]:
char *
plaxes ((pdl) x0, (pdl) y0, (pdl) xtick, (pdl) nxsub, (pdl) ytick, (pdl) nysub, (string) xopt, (string (yopt)) plbox ((pdl) xtick, (pdl) nxsub, (pdl) ytick, (pdl) nysub, (string) xopt, (string) yopt) plbox3 ((pdl) xtick, (pdl) nsubx, (pdl) ytick, (pdl) nsuby, (pdl) ztick, (pdl) nsubz, (string) xopt, (string) xlabel, (string) yopt, (string) ylabel, (string) zopt, (string) zlabel) plmtex ((pdl) disp, (pdl) pos, (pdl) just, (string) side), (string) text); plstart ((pdl) nx, (pdl) ny, (string) devname);
The second notable different between the C and the PDL APIs is that many of the PDL calls do not need arguments to specify the size of the the vectors and/or matrices being passed. This size parameters are deduced from the size of the piddles, when possible. For now, the following interfaces are affected:
plcont (f, kx, lx, ky, ly, clevel) plfill (x, y) plhist (data, datmin, datmax, nbin, oldwin) plline (x, y) plline3 (x, y, z) plpoly3 (x, y, z, draw, ifcc) plmesh (x, y, z, opt) plmeshc (x, y, z, opt, clevel) plot3d (x, y, z, opt, side) plpoin (x, y, code) plpoin3 (x, y, z, code) plscmap1l (itype, intensity, coord1, coord2, coord3, rev) plstyl (mark, space) plsym (x, y, code)
Some of the API functions implemented in PDL have other specificities in comparison with the C API and will be discussed below.
$status = plxormod ($mode)
See the PLplot manual for reference.
%gin = plGetCursor ()
plGetCursor waits for graphics input event and translate to world coordinates and returns a hash with the following keys:
type: of event (CURRENTLY UNUSED) state: key or button mask keysym: key selected button: mouse button selected subwindow: subwindow (alias subpage, alias subplot) number string: translated string pX, pY: absolute device coordinates of pointer dX, dY: relative device coordinates of pointer wX, wY: world coordinates of pointer
Returns an empty hash if no translation to world coordinates is possible.
$strm = plgstrm ()
Returns the number of the current output stream.
$driver = plgdev ()
Returns the current driver name.
$strm = plmkstrm ()
Creates a new stream and makes it the default. Returns the number of the created stream.
$version = plgver ()
Doug Hunt <dhunt@ucar.edu> Rafael Laboissiere <rlaboiss@users.sourceforge.net>
perl(1), PDL(1), http://www.plplot.org/
To install , copy and paste the appropriate command in to your terminal.
cpanm
cpanm DHUNT/PDL-Graphics-PLplot-0.47.tar.gz
CPAN shell
perl -MCPAN -e shell install DHUNT/PDL-Graphics-PLplot-0.47.tar.gz
For more information on module installation, please visit the detailed CPAN module installation guide.