line
stmt
bran
cond
sub
pod
time
code
1
##############################
2
#
3
# PDL::Graphics::Gnuplot
4
#
5
# This glue module is complicated because it connects a complicated
6
# syntax (Perl) to another complicated syntax (Gnuplot). Here is a
7
# quick internal overview to get your bearings, above the usual POD.
8
#
9
# PDL::Graphics::Gnuplot (P:G:G) objects generally are associated with
10
# an external gnuplot process, and data are passed to the process
11
# through a pipe. It is possible to intercept the data going through
12
# the pipe, either by diverting (dumping) data to stdout instead of
13
# gnuplot, or by teeing the data to stdout as well as gnuplot.
14
# Further, you can turn on syntax checking to validate P:G:G itself.
15
# Syntax checking is performed in a second P:G:G process, since
16
# screwing up the synchronization between Gnuplot and the P:G:G state
17
# is hazardous in the event of syntax error.
18
#
19
# The perl P:G:G object attempts to store and manage essentially
20
# all of the state that is also held inside the gnuplot program.
21
# This takes the form of:
22
# - Terminal options - setup for a given terminal output
23
# - Plot options - setup per-plot
24
# - Curve options - setup per-curve within a plot
25
#
26
# Option handling uses branch tables. Plot and curve options are
27
# parsed using the $pOptionsTable and $cOptionsTable respectively -
28
# these are big global hashes that describe the gnuplot syntax.
29
# Terminal options are "worser" - the options that are accepted depend
30
# on the terminal device, so the table $termTab contains a
31
# description of which terminal options are allowed for each of the
32
# supported gnuplot terminals.
33
#
34
# All options handling is performed through parsing and emitter
35
# routines that are pointed to from those three tables. That is
36
# handled with _parseOptHash(), which accepts an input parameter and a
37
# particular option description table, and parses the input according
38
# to the table. The opposite (used for command generation) is
39
# _emitOpts(), which takes a parsed hash and emits an appropriate
40
# (sub)command into its returned string.
41
#
42
# There are some plot modes that we want to support, and that gnuplot
43
# itself does not yet support. These are "mocked up" using data
44
# prefrobnicators. Currently there is only one of those - FITS
45
# imagery.
46
#
47
# The gnuplot syntax is more than a little byzantine, and this is
48
# reflected in the code - specifically, in the code in plot(), which
49
# is the main workhorse.
50
#
51
# plot() pulls plot arguments off the front and back of the argument
52
# list. It relies on its subroutine parseArgs to break the remaining
53
# parameters into chunks of parameters, each of which represents a
54
# single curve (including curve options and actual data to be
55
# plotted). Because we allow threading, a given batch of curve option
56
# arguments and data can yield many chunks. Those chunks are then
57
# passed through a number of steps back in the main plot() routine,
58
# and turned into a colllection of gnuplot commands suitable for plot
59
# generation.
60
#
61
# Because option parsing and handling is slightly more complicated
62
# than simply interpreting values and assigning defaults, we do not
63
# use a pre-existing package (such as PDL::Options) for option parsing
64
# - we use a dual parse table scheme. Each option set has an "abbrev"
65
# table that is generated at compile time and resolves unique
66
# abbreviations; and a "parse" table that indicates what to do with
67
# each option. Since this mechanism is near at hand, we use it even
68
# for routines (such as read_polygon) that could and would use
69
# PDL::Options in other circumstances.
70
71
=encoding UTF-8
72
73
=head1 NAME
74
75
PDL::Graphics::Gnuplot - Gnuplot-based plotting for PDL
76
77
=head1 SYNOPSIS
78
79
pdl> use PDL::Graphics::Gnuplot;
80
81
pdl> $x = sequence(101) - 50;
82
pdl> gplot($x**2);
83
pdl> gplot($x**2,{xr=>[0,50]});
84
85
pdl> gplot( {title => 'Parabola with error bars'},
86
with => 'xyerrorbars', legend => 'Parabola',
87
$x**2 * 10, abs($x)/10, abs($x)*5 );
88
89
pdl> $xy = zeroes(21,21)->ndcoords - pdl(10,10);
90
pdl> $z = inner($xy, $xy);
91
pdl> gplot({title => 'Heat map',
92
trid => 1,
93
view => [0,0]
94
},
95
with => 'image', xvals($z),yvals($z),zeroes($z),$z*2
96
);
97
98
pdl> $w = gpwin(); # constructor
99
pdl> $pi = 3.14159;
100
pdl> $theta = zeroes(200)->xlinvals(0, 6*$pi);
101
pdl> $z = zeroes(200)->xlinvals(0, 5);
102
pdl> $w->plot3d(cos($theta), sin($theta), $z);
103
pdl> $w->terminfo(); # get information
104
105
106
=head1 DESCRIPTION
107
108
This module allows PDL data to be plotted using Gnuplot as a backend
109
for 2D and 3D plotting and image display. Gnuplot (not affiliated
110
with the GNU project) is a venerable, open-source program that
111
produces both interactive and publication-quality plots on many
112
different output devices. It is available through most Linux
113
repositories, on MacOS, and from its website
114
L.
115
116
It is not necessary to understand the gnuplot syntax to generate
117
basic, or even complex, plots - though the full syntax is available
118
for advanced users who want the full flexibility of the Gnuplot
119
backend.
120
121
For a very quick demonstration of the power of this module, see
122
L,
123
and others on visualisation of
124
L and
125
L.
126
127
Gnuplot recognizes both hard-copy and interactive plotting devices,
128
and on interactive devices (like X11) it is possible to pan, scale,
129
and rotate both 2-D and 3-D plots interactively. You can also enter
130
graphical data through mouse clicks on the device window. On some
131
hardcopy devices (e.g. "PDF") that support multipage output, it is
132
necessary to close the device after plotting to ensure a valid file is
133
written out.
134
135
C exports two routines by default: a
136
constructor, C and a general purpose plot routine,
137
C. Depending on options, C can produce line plots,
138
scatterplots, error boxes, "candlesticks", images, or any overlain
139
combination of these elements; or perspective views of 3-D renderings
140
such as surface plots.
141
142
A call to C looks like:
143
144
gplot({temp_plot_options}, # optional hash ref
145
curve_options, data, data, ... ,
146
curve_options, data, data, ... );
147
148
The data entries are columns to be plotted. They are normally
149
an optional ordinate and a required abscissa, but some plot modes
150
can use more columns than that. The collection of columns is called
151
a "tuple". Each column must be a separate PDL or an ARRAY ref. If
152
all the columns are PDLs, you can add extra dimensions to make threaded
153
collections of curves.
154
155
PDL::Graphics::Gnuplot also implements an object oriented
156
interface. Plot objects track individual gnuplot subprocesses. Direct
157
calls to C are tracked through a global object that stores
158
globally set configuration variables.
159
160
The C sub (or the C method) collects two kinds of
161
options hash: B, which describe the overall structure of
162
the plot being produced (e.g. axis specifications, window size, and
163
title), and B, which describe the behavior of
164
individual traces or collections of points being plotted. In
165
addition, the module itself supports options that allow direct
166
pass-through of plotting commands to the underlying gnuplot process.
167
168
=head2 Basic plotting
169
170
Gnuplot generates many kinds of plot, from basic line plots and histograms
171
to scaled labels. Individual plots can be 2-D or 3-D, and different sets
172
of plot styles are supported in each mode. Plots can be sent to a variety
173
of devices; see the description of plot options, below.
174
175
You can specify what type of graphics output you want, but in most cases
176
doing nothing will cause a plot to be rendered on your screen: with
177
X windows on UNIX or Linux systems, with an XQuartz window on MacOS,
178
or with a native window on Microsoft Windows.
179
180
You select a plot style with the "with" curve option, and feed in columns
181
of data (usually ordinate followed by abscissa). The collection of columns
182
is called a "tuple". These plots have two columns in their tuples:
183
184
$x = xvals(51)-25; $y = $x**2;
185
gplot(with=>'points', $x, $y); # Draw points on a parabola
186
gplot(with=>'lines', $x, $y); # Draw a parabola
187
gplot({title=>"Parabolic fit"},
188
with=>"yerrorbars", legend=>"data", $x, $y+(random($y)-0.5)*2*$y/20, pdl($y/20),
189
with=>"lines", legend=>"fit", $x, $y);
190
191
Normal threading rules apply across the arguments to a given plot.
192
193
All data are required to be supplied as either PDLs or array refs.
194
If you use an array ref as a data column, then normal
195
threading is disabled. For example:
196
197
$x = xvals(5);
198
$y = xvals(5)**2;
199
$labels = ['one','two','three','four','five'];
200
gplot(with=>'labels',$x,$y,$labels);
201
202
See below for supported curve styles.
203
204
=head3 Modifying plots
205
206
Gnuplot is built around a monolithic plot model - it is not possible to
207
add new data directly to a plot without redrawing the entire plot. To support
208
replotting, PDL::Graphics::Gnuplot stores the data you plot in the plot object,
209
so that you can add new data with the "replot" command:
210
211
$w=gpwin(x11);
212
$x=xvals(101)/100;
213
$y=$x;
214
$w->plot($x,$y);
215
$w->replot($x,$y*$y);
216
217
For speed, the data are *not* disconnected from their original variables - so
218
this will plot X vs. sqrt(X):
219
220
$x = xvals(101)/100;
221
$y = xvals(101)/100;
222
$w->plot($x,$y);
223
$y->inplace->sqrt;
224
$w->replot();
225
226
=head3 Plotting to an image file or device
227
228
PDL:Graphics::Gnuplot can plot to most of the devices supported by
229
gnuplot itself. You can specify the file type with the "output"
230
method or the object constructor "gplot". Either one will allow you
231
to name a type of file to produce, and a collection of options speciic to
232
that type of output file.
233
234
=head3 Image plotting
235
236
Several of the plot styles accept image data. The tuple parameters work the
237
same way as for basic plots, but each "column" is a 2-D PDL rather than a 1-D PDL.
238
As a special case, the "with image" plot style accepts either a 2-D or a 3-D PDL.
239
If you pass in 3-D PDL, the extra dimension can have size 1, 3, or 4. It is interpreted
240
as running across (R,G,B,A) color planes.
241
242
=head3 3-D plotting
243
244
You can plot in 3-D by setting the plot option C to a true value. Three
245
dimensional plots accept either 1-D or 2-D PDLs as data columns. If you feed
246
in 2-D "columns", many of the common plot styles will generalize appropriately
247
to 3-D. For example, to plot a 2-D surface as a line grid, you can use the "lines"
248
style and feed in 2-D columns instead of 1-D columns.
249
250
=head2 Enhanced text
251
252
Most gnuplot output devices include the option to markup "enhanced text". That means
253
text is interpreted so that you can change its font and size, and insert superscripts
254
and subscripts into labels. Codes are:
255
256
=over 3
257
258
=item {}
259
260
Text grouping - enclose text in braces to group characters, as in LaTeX.
261
262
=item ^
263
264
Superscript the next character or group (shrinks it slightly too where that is supported).
265
266
=item _
267
268
Subscript the next character or group (shrinks it slightly too where that is supported).
269
270
=item @
271
272
Phantom box (occupies no width; controls height for super- and subscripting)
273
274
=item &
275
276
Controllable-width space, e.g. &{template-string}
277
278
=item ~
279
280
overstrike -- e.g. ~a{0.8-} overprints '-' on 'a', raised by 0.8xfontsize.
281
282
=item {/[fontname][=fontsize | *fontscale] text}
283
284
Change font to (optional) fontname, and optional absolute font size or relative font scale ("fontsize" and "fontscale" are numbers). The space after the size parameter is not rendered.
285
286
=item \
287
288
Backslash escapes control characters to render them as themselves.
289
290
=back
291
292
=head2 Unicode text
293
294
Separately to "enhanced" text above, if you wish to include text that
295
is not ASCII, then you will need to pass data that has been UTF-8
296
encoded. Sample code to achieve this:
297
298
use utf8;
299
use Encode;
300
use PDL;
301
use PDL::Graphics::Gnuplot;
302
use PDL::Constants qw(PI);
303
304
sub plot_sin {
305
my ($w, $coeff) = @_;
306
my $xrange = [ -2*PI, 2*PI ];
307
my $x = zeroes(1e3)->xlinvals(@$xrange); my $y = sin($coeff * 2 * PI * $x);
308
my $title = "y = sin( $coeff * 2Ï€ * x )";
309
# to get around sending text through syswrite()
310
my $title_octets = encode('UTF-8', $title);
311
$w->plot(with=>'lines', $x, $y, {
312
xrange => $xrange,
313
title => $title_octets, # can not pass $title as-is
314
});
315
}
316
317
=head2 Color specification
318
319
There are several contexts where you can specify color of plot elements. In those
320
places, you can specify colors exactly as in the Gnuplot manual, or more tersely.
321
In general, a color spec can be any one of the following:
322
323
=over 3
324
325
=item - an integer
326
327
This specifies a recognizable unique color in the same order as used by the plotting engine.
328
329
=item - the name of a color
330
331
(e.g. "blue"). Supported color names are listed in the variable C<@Alien::Gnuplot::colors>.
332
333
=item - an RGB value string
334
335
Strings have the form C<#RRGGBB>, where the C<#> is literal and the RR, GG, and BB are hexadecimal bytes.
336
337
=item - the word "palette"
338
339
"palette" indicates that color is to be drawn from the scaled colorbar
340
palette (which you can set with the "clut" plot option), by lookup
341
using an additional column in the associated data tuple.
342
343
=item - the word "variable"
344
345
"variable" indicates that color is to be drawn from the integer
346
plotting colors used by the plotting engine, indexed by an additional
347
column in the associated data tuple.
348
349
=item - the phrase "rgb variable"
350
351
"rgb variable" indicates that color is to be directly specified by a
352
24 bit integer specifying 8-bit values for (from most significant byte
353
to least significant byte) R, G, and B in the output color. The
354
integer is drawn from an additional column in the associated data tuple.
355
356
=back
357
358
359
=head2 Plot styles supported
360
361
Gnuplot itself supports a wide range of plot styles, and all are supported by
362
PDL::Graphics::Gnuplot. Most of the basic plot styles collect tuples of 1-D columns
363
in 2-D mode (for ordinary plots), or either 1-D or 2-D "columns" in 3-D mode (for
364
grid surface plots and such). Image modes always collect tuples made of 2-D "columns".
365
366
You can pass in 1-D columns as either PDLs or ARRAY refs. That is important for
367
plot types (such as "labels") that require a collection of strings rather than
368
numeric data.
369
370
Each plot style can by modified to support particular colors or line
371
style options. These modifications get passed in as curve options (see
372
below). For example, to plot a blue line you can use
373
C'lines',lc=E'blue'>. To match the autogenerated style of a
374
particular line you can use the C curve option.
375
376
The GNuplot plot styles supported are:
377
378
=over 3
379
380
=item * C - combo of C and C, below (2D)
381
382
=item * C - simple boxes around regions on the plot (2D)
383
384
=item * C - Render X and Y error bars as boxes (2D)
385
386
=item * C - Y error bars with inner and outer limits (2D)
387
388
=item * C - circles with variable radius at each point: X/Y/radius (2D)
389
390
=item * C - tiny points ("dots") at each point, e.g. for scatterplots (2D/3D)
391
392
=item * C - ellipses. Accepts X/Y/major/minor/angle (2D)
393
394
=item * C - closed polygons or axis-to-line filled shapes (2D)
395
396
=item * C - financial style plot. Accepts date/open/low/high/close (2D)
397
398
=item * C - square bin plot; delta-Y, then delta-X (see C, C) (2D)
399
400
=item * C - square bin plot; plateaus centered on X coords (see C, C) (2D)
401
402
=item * C - binned histogram of dataset (not direct plot; see C) (2D)
403
404
=item * C - (PDL-specific) renders FITS image files in scientific coordinates
405
406
=item * C - Takes (i), (x,y,i), or (x,y,z,i). See C, C, C. (2D/3D)
407
408
=item * C - vertical line from axis to the plotted point (2D/3D)
409
410
=item * C - Text labels at specified locations all over the plot (2D/3D)
411
412
=item * C - regular line plot (2D/3D)
413
414
=item * C - line plot with symbols at plotted points (2D/3D)
415
416
=item * C - multiple-histogram-friendly histogram style (see C) (2D)
417
418
=item * C - symbols at plotted points (2D/3D)
419
420
=item * C - R/G/B color image with variable transparency (2D/3D)
421
422
=item * C - R/G/B color image (2D/3D)
423
424
=item * C - square bin plot; delta-X, then delta-Y (see C, C) (2D)
425
426
=item * C - Small arrows: (x,y,[z]) -> (x+dx,y+dy,[z+dz]) (2D/3D)
427
428
=item * C - points with X error bars ("T" form) (2D)
429
430
=item * C - points with both X and Y error bars ("T" form) (2D)
431
432
=item * C - points with Y error bars ("T" form) (2D)
433
434
=item * C - line plot with X errorbars at each point. (2D)
435
436
=item * C - line plot with XY errorbars at each point. (2D)
437
438
=item * C - line plot with Y error limits at each point. (2D)
439
440
=item * C - three-dimensional variable-position surface plot
441
442
=back
443
444
=head2 Options arguments
445
446
The plot options are parameters that affect the whole plot, like the title of
447
the plot, the axis labels, the extents, 2d/3d selection, etc. All the plot
448
options are described below in L<"Plot Options"|/"PLOT OPTIONS">. Plot options can be set
449
in the plot object, or passed to the plotting methods directly. Plot options can
450
be passed in as a leading interpolated hash, as a leading hash ref, or as a trailing
451
hash ref in the argument list to any of the main plotting routines (C, C,
452
C, etc.).
453
454
The curve options are parameters that affect only one curve in particular. Each
455
call to C can contain many curves, and options for a particular curve
456
I the data for that curve in the argument list. The actual type of curve
457
(the "with" option) is persistent, but all other curve options and modifiers
458
are not. An example:
459
460
gplot( with => 'points', $x, $a,
461
{axes=> x1y2}, $x, $b,
462
with => 'lines', $x, $c );
463
464
This plots 3 curves: $a vs. $x plotted with points on the main y-axis (this is
465
the default), $b vs. $x plotted with points on the secondary y axis, and $c
466
vs. $x plotted with lines on the main y-axis (the default). Note that the curve
467
options can be supplied as either an inline hash or a hash ref.
468
469
All the curve options are described below in L<"Curve Options"|/"CURVE OPTIONS">.
470
471
If you want to plot multiple curves of the same type without setting
472
any curve options explicitly, you must include an empty hash ref
473
between the tuples for subsequent lines, as in:
474
475
gplot( $x, $a, {}, $x, $b, {}, $x, $c );
476
477
=head2 Data arguments
478
479
Following the curve options in the C argument list is the
480
actual data being plotted. Each output data point is a "tuple" whose
481
size varies depending on what is being plotted. For example if we're
482
making a simple 2D x-y plot, each tuple has 2 values; if we're making
483
a 3d plot with each point having variable size and color, each tuple
484
has 5 values (x,y,z,size,color). Each tuple element must be passed
485
separately. For ordinary 2-D plots, the 0 dim of the tuple elements
486
runs across plotted point. PDL threading is active, so you can plot
487
multiple curves with similar curve options on a normal 2-D plot, just
488
by stacking data inside the passed-in PDLs. (An exception is that
489
threading is disabled if one or more of the data elements is a list
490
ref).
491
492
=head3 PDLs vs array refs
493
494
The usual way to pass in data is as a PDL -- one PDL per column of data
495
in the tuple. But strings, in particular, cannot easily be hammered into
496
PDLs. Therefore any column in each tuple can be an array ref containing
497
values (either numeric or string). The column is interpreted using the
498
usual polymorphous cast-behind-your-back behavior of Perl. For the sake
499
of sanity, if even one array ref is present in a tuple, then threading is
500
disabled in that tuple: everything has to have a nice 1-D shape.
501
502
503
=head3 Implicit domains
504
505
When making a simple 2D plot, if exactly 1 dimension is missing,
506
PDL::Graphics::Gnuplot will use C as the domain. This is
507
why code like C works. Only one PDL is given
508
here, but the plot type ("lines" by default) requires 2 elements per
509
tuple. We are thus exactly 1 ndarray short; C is used as
510
the missing domain PDL. This is thus equivalent to
511
C.
512
513
If plotting in 3d or displaying an image, an implicit domain will be
514
used if we are exactly 2 ndarrays short. In this case,
515
PDL::Graphics::Gnuplot will use a 2D grid as a domain. Example:
516
517
my $xy = zeros(21,21)->ndcoords - pdl(10,10);
518
gplot({'3d' => 1},
519
with => 'points', inner($xy, $xy));
520
gplot( with => 'image', sin(rvals(51,51)) );
521
522
Here the only given ndarray has dimensions (21,21). This is a 3D plot, so we are
523
exactly 2 ndarrays short. Thus, PDL::Graphics::Gnuplot generates an implicit
524
domain, corresponding to a 21-by-21 grid.
525
526
C requires explicit separators between tuples
527
for different plots, so it is always clear from the arguments you pass
528
in just how many columns you are supplying. For example,
529
C will plot C<$b> vs. C<$a>. If you actually want to
530
plot an overlay of both C<$a> and C<$b> against array index, you want
531
C instead. The C<{}> is a hash ref containing a
532
collection of all the curve options that you are changing between
533
the two curves -- in this case, zero of them.
534
535
=head2 Images
536
537
PDL::Graphics::Gnuplot supports four styles of image plot, via the "with" curve option.
538
539
The "image" style accepts a single image plane and displays it using
540
the palette (pseudocolor map) that is specified in the plot options
541
for that plot. As a special case, if you supply as data a (3xWxH) or
542
(WxHx3) PDL it is treated as an RGB image and displayed with the
543
"rgbimage" style (below), provided there are at least 5 pixels in each of the
544
other two dimensions (just to be sure). For quick image display there
545
is also an "image" method:
546
547
use PDL::Graphics::Gnuplot qw/image gplot/;
548
$im = sin(rvals(51,51)/2);
549
image( $im ); # display the image
550
gplot( with=>'image', $im ); # display the image (longer form)
551
552
The colors are autoscaled in both cases. To set a particular color range, use
553
the 'cbrange' plot option:
554
555
image( {cbrange=>[0,1]}, $im );
556
557
You can plot rgb images directly with the image style, just by including a
558
3rd dimension of size 3 on your image:
559
560
$rgbim = pdl( xvals($im), yvals($im),rvals($im)/sqrt(2));
561
image( $rgbim ); # display an RGB image
562
gplot( with=>'image', $rgbim ); # display an RGB image (longer form)
563
564
Some additional plot styles exist to specify RGB and RGB transparent forms
565
directly. These are the "with" styles "rgbimage" and "rgbalpha". For each
566
of them you must specify the channels as separate PDLs:
567
568
gplot( with=>'rgbimage', $rgbim->dog ); # RGB the long way
569
gplot( with=>'rgbalpha', $rgbim->dog, 255*($im>0) ); # RGBA the long way
570
571
According to the gnuplot specification you can also give X and Y
572
values for each pixel, as in
573
574
gplot( with=>'image', xvals($im), yvals($im), $im )
575
576
but this appears not to work properly for anything more complicated
577
than a trivial matrix of X and Y values.
578
579
PDL::Graphics::Gnuplot provides a "fits" plot style that interprets
580
World Coordinate System (WCS) information supplied in the header of
581
the scientific image format FITS. The image is displayed in rectified
582
scientific coordinates, rather than in pixel coordinates. You can plot
583
FITS images in scientific coordinates with
584
585
gplot( with=>'fits', $fitsdata );
586
587
The fits plot style accepts a curve option "resample" (which may be
588
abbreviated), that allows you to downsample and/or rectify the image
589
before it is passed to the Gnuplot back-end. This is useful either to
590
cut down on the burden of transferring large blocks of image data or
591
to rectify images with nonlinear WCS transformations in their headers.
592
(gnuplot itself has a bug that prevents direct rendering of images in
593
nonlinear coordinates).
594
595
gplot( with=>'fits', res=>1, $fitsdata );
596
gplot( with=>'fits', res=>[200], $fitsdata );
597
gplot( with=>'fits', res=>[100,400],$fitsdata );
598
599
to specify that the output are to be resampled onto a square 1024x1024 grid,
600
a 200x200 grid, or a 100x400 grid, respectively. The resample sizes must be
601
positive integers.
602
A true non-ref value will be treated as 1024x1024.
603
604
=head2 Interactivity
605
606
Several of the graphical backends of Gnuplot are interactive, allowing
607
you to pan, zoom, rotate and measure the data interactively in the plot
608
window. See the Gnuplot documentation for details about how to do
609
this. Some terminals (such as C) are persistently interactive. Other
610
terminals (such as C) maintain their interactivity only while the
611
underlying gnuplot process is active -- i.e. until another plot is
612
created with the same PDL::Graphics::Gnuplot object, or until the perl
613
process exits (whichever comes first). Still others (the hardcopy
614
devices) aren't interactive at all.
615
616
Some interactive devices (notably C and C) also support
617
mouse input: you can write PDL scripts that accept and manipulate
618
graphical input from the plotted window.
619
620
=head1 PLOT OPTIONS
621
622
Gnuplot controls plot style with "plot options" that configure and
623
specify virtually all aspects of the plot to be produced. Plot
624
options are tracked as stored state in the PDL::Graphics::Gnuplot
625
object. You can set them by passing them in to the constructor, to an
626
C method, or to the C method itself.
627
628
Nearly all the underlying Gnuplot plot options are supported, as well
629
as some additional options that are parsed by the module itself for
630
convenience.
631
632
There are many, many plot options. For convenience, we've grouped
633
them by general category below. Each group has a heading "POs for EfooE",
634
describing the category. You can skip below them all if you want to
635
read about curve options or other aspects of PDL::Graphics::Gnuplot.
636
637
=head2 POs for Output: terminal, termoption, output, device, hardcopy
638
639
You can send plots to a variety of different devices; Gnuplot calls
640
devices "terminals". With the object-oriented interface, you must set
641
the output device with the constructor C
642
(or the exported constructor C) or the C method. If you
643
use the simple non-object interface, you can set the output with the
644
C, C, and C plot options.
645
646
C sets the output device type for Gnuplot, and C sets the
647
actual output file or window number.
648
649
C and C are for convenience. C offers a
650
PGPLOT-style device specifier in "filename/device" format (the "filename"
651
gets sent to the "output" option, the "device" gets sent to the "terminal"
652
option). C takes an output file name, attempts to parse out a
653
file suffix and infer a device type. C also uses a common set of
654
terminal options needed to fill an entire letter page with a plot.
655
656
For finer grained control of the plotting environment, you can send
657
"terminal options" to Gnuplot. If you set the terminal directly with
658
plot options, you can include terminal options by interpolating them
659
into a string, as in C, or you can
660
use the constructor C (also exported as C), which parses
661
terminal options as an argument list.
662
663
The routine C prints a list of all
664
available terminals or, if you pass in a terminal name, options accepted
665
by that terminal.
666
667
668
=head2 POs for Titles
669
670
The options described here are
671
672
=over
673
674
=item title
675
676
=item xlabel
677
678
=item x2label
679
680
=item ylabel
681
682
=item y2label
683
684
=item zlabel
685
686
=item cblabel
687
688
=item key
689
690
=back
691
692
Gnuplot supports "enhanced" text escapes on most terminals; see "text",
693
below.
694
695
The C option lets you set a title for the whole plot.
696
697
Individual plot components are labeled with the C options.
698
C, C, C, and C specify axis titles
699
for 2-D plots. The C works for 3-D plots. The C option
700
sets the label for the color box, in plot types that have one (e.g.
701
image display).
702
703
(Don't be confused by C, which doesn't set a label at all, rather
704
specifies the printf format used by contour labels in contour plots.)
705
706
C controls where the plot key (that relates line/symbol style to label)
707
is placed on the plot. It takes a scalar boolean indicating whether to turn the
708
key on (with default values) or off, or an array ref containing any of the following
709
arguments (all are optional) in the order listed:
710
711
=over 3
712
713
=item * ( on | off ) - turn the key on or off
714
715
=item * ( inside | outside | lmargin | rmargin | tmargin | bmargin | at )
716
717
These keywords set the location of the key -- "inside/outside" is
718
relative to the plot border; the margin keywords indicate location in
719
the margins of the plot; and at (where is a comma-delimited string
720
containing (x,y): C[at=E"0.5,0.5"]>) is an exact location to place the key.
721
722
=item * ( left | right | center ) ( top | bottom | center ) - horiz./vert. alignment
723
724
=item * ( vertical | horizontal ) - stacking direction within the key
725
726
=item * ( Left | Right ) - justification of plot labels within the key (note case)
727
728
=item * [no]reverse - switch order of label and sample line
729
730
=item * [no]invert - invert the stack order of the labels
731
732
=item * samplen - set the length of the sample lines
733
734
=item * spacing - set the spacing between adjacent labels in the list
735
736
=item * [no]autotitle - control whether labels are generated when not specified
737
738
=item * title "" - set a title for the key
739
740
=item * [no]enhanced - override terminal settings for enhanced text interpretation
741
742
=item * font "," - set font for the labels
743
744
=item * textcolor
745
746
=item * [no]box linestyle linetype linewidth - control box around the key
747
748
=back
749
750
=head2 POs for axes, grids, & borders
751
752
The options described here are
753
754
=over
755
756
=item grid
757
758
=item xzeroaxis
759
760
=item x2zeroaxis
761
762
=item yzeroaxis
763
764
=item y2zeroaxis
765
766
=item zzeroaxis
767
768
=item border
769
770
=back
771
772
Normally, tick marks and their labels are applied to the border of a plot,
773
and no extra axes (e.g. the y=0 line) nor coordinate grids are shown. You can
774
specify which (if any) zero axes should be drawn, and which (if any)
775
borders should be drawn.
776
777
The C option controls whether the plot itself has a border
778
drawn around it. You can feed it a scalar boolean value to indicate
779
whether borders should be drawn around the plot -- or you can feed in a list
780
ref containing options. The options are all optional but must be supplied
781
in the order given.
782
783
=over 3
784
785
=item * - packed bit flags for which border lines to draw
786
787
788
The default if you set a true value for C is to draw all border lines.
789
You can feed in a single integer value containing a bit mask, to draw only some
790
border lines. From LSB to MSB, the coded lines are bottom, left, top, right for
791
2D plots -- e.g. 5 will draw bottom and top borders but neither left nor right.
792
793
In three dimensions, 12 bits are used to describe the twelve edges of
794
a cube surrounding the plot. In groups of three, the first four
795
control the bottom (xy) plane edges in the same order as in the 2-D
796
plots; the middle four control the vertical edges that rise from the
797
clockwise end of the bottom plane edges; and the last four control the
798
top plane edges.
799
800
=item * ( back | front ) - draw borders first or last (controls hidden line appearance)
801
802
=item * linewidth , linestyle , linetype
803
804
These are Gnuplot's usual three options for line control.
805
806
=back
807
808
The C option indicates whether gridlines should be drawn on
809
each axis. It takes an array ref of arguments, each of which is either "no" or "m" or "",
810
followed by an axis name and "tics" --
811
e.g. C<< grid=>["noxtics","ymtics"] >> draws no X gridlines and draws
812
(horizontal) Y gridlines on Y axis major and minor tics, while
813
C<< grid=>["xtics","ytics"] >> or C<< grid=>["xtics ytics"] >> will draw both
814
vertical (X) and horizontal (Y) grid lines on major tics.
815
816
To draw a coordinate grid with default values, set C<< grid=>1 >>. For more
817
control, feed in an array ref with zero or more of the following parameters, in order:
818
819
The C keyword indicates whether to actually draw each axis
820
line at the corresponding zero along its indicated dimension. For
821
example, to draw the X axis (y=0), use C<< xzeroaxis=>1 >>. If you just
822
want the axis turned on with default values, you can feed in a Boolean
823
scalar; if you want to set its parameters, you can feed in an array ref
824
containing linewidth, linestyle, and linetype (with appropriate
825
parameters for each), e.g. C<< xzeroaxis=>[linewidth=>2] >>.
826
827
=head2 POs for axis range and mode
828
829
The options described here are
830
831
=over
832
833
=item xrange
834
835
=item x2range
836
837
=item yrange
838
839
=item y2range
840
841
=item zrange
842
843
=item rrange
844
845
=item cbrange
846
847
=item trange
848
849
=item urange
850
851
=item vrange
852
853
=item autoscale
854
855
=item logscale
856
857
=back
858
859
Gnuplot accepts explicit ranges as plot options for all axes. Each option
860
accepts an array ref with (min, max). If either min or max is missing, then
861
the opposite limit is autoscaled. The x and y ranges refer to the usual
862
ordinate and abscissa of the plot; x2 and y2 refer to alternate ordinate and
863
abscissa; z if for 3-D plots; r is for polar plots; t, u, and v are for parametric
864
plots. cb is for the color box on plots that include it (see "color", below).
865
866
C is used for radial coordinates (which
867
are accessible using the C plot option, below).
868
869
C (for 'color box range') sets the range of values over which
870
palette colors (either gray or pseudocolor) are matched. It is valid
871
in any color-mapped plot (including images or palette-mapped lines or
872
points), even if no color box is being displayed for this plot.
873
874
C, C, and C set ranges for the parametric coordinates
875
if you are plotting a parametric curve.
876
877
By default all axes are autoscaled unless you specify a range on that
878
axis, and partially (min or max) autoscaled if you specify a partial
879
range on that axis. C allows more explicit control of how
880
autoscaling is performed, on an axis-by-axis basis. It accepts a hash
881
ref, each element of which specifies how a single axis should be
882
autoscaled. Each keyword contains an axis name followed by one of
883
"fix", "min", "max", "fixmin", or "fixmax". You can set all the axes at
884
once by setting the keyword name to ' '. Examples:
885
886
autoscale=>{x=>'max',y=>'fix'};
887
888
There is an older array ref syntax which is deprecated but still accepted.
889
890
To not autoscale an axis at all, specify a range for it. The fix style of
891
autoscaling forces the autoscaler to use the actual min/max of the data as
892
the limit for the corresponding axis -- by default the axis gets extended
893
to the next minor tic (as set by the autoticker or by a tic specification, see
894
below).
895
896
C allows you to turn on logarithmic scaling for any or all
897
axes, and to set the base of the logarithm. It takes an array ref, the
898
first element of which is a string mushing together the names of all
899
the axes to scale logarithmically, and the second of which is the base
900
of the logarithm: C<< logscale=>[xy=>10] >>. You can also leave off the
901
base if you want base-10 logs: C<< logscale=>['xy'] >>.
902
903
=head2 POs for Axis tick marks
904
905
The options described here are
906
907
=over
908
909
=item xtics
910
911
=item x2tics
912
913
=item ytics
914
915
=item y2tics
916
917
=item ztics
918
919
=item cbtics
920
921
=item mxtics
922
923
=item mx2tics
924
925
=item mytics
926
927
=item my2tics
928
929
=item mztics
930
931
=item mcbtics
932
933
=back
934
935
Axis tick marks are called "tics" within Gnuplot, and they are extensively
936
controllable via the "{axis}tics" options. In particular, major and minor
937
ticks are supported, as are arbitrarily variable length ticks, non-equally
938
spaced ticks, and arbitrarily labelled ticks. Support exists for time formatted
939
ticks (see C below).
940
941
By default, gnuplot will automatically place major and minor ticks.
942
You can turn off ticks on an axis by setting the appropriate {foo}tics
943
option to a defined, false scalar value (e.g. C<< xtics=>0 >>). If you
944
want to set major tics to happen at a regular specified intervals, you can set the
945
appropriate tics option to a nonzero scalar value (e.g. C<< xtics=>2 >> to
946
specify a tic every 2 units on the X axis). To use default values for the
947
tick positioning, specify an empty hash or array ref (e.g. C<< xtics=>{} >>), or
948
a string containing only whitespace (e.g. C<< xtics=>' ' >>).
949
950
If you prepend an 'm' to any tics option, it affects minor tics instead of
951
major tics (major tics typically show units; minor tics typically show fractions
952
of a unit).
953
954
Each tics option can accept a hash ref containing options to pass to
955
Gnuplot. You can also pass in a snippet of gnuplot command, as either
956
a string or an array ref -- but those techniques are deprecated and may
957
disappear in a future version of C.
958
959
The keywords are case-insensitive and may be abbreviated, just as with
960
other option types. They are:
961
962
=over 2
963
964
=item * axis - set to 1 to place tics on the axis (the default)
965
966
=item * border - set to 1 to place tics on the border (not the default)
967
968
=item * mirror - set to 1 to place mirrored tics on the opposite axis/border (the default, unless an alternate axis interferes -- e.g. y2)
969
970
=item * in - set to 1 to draw tics inward from the axis/border
971
972
=item * out - set to 1 to draw tics outward from the axis/border
973
974
=item * scale - multiplier on tic length compared to the default
975
976
If you pass in undef, tics get the default length. If you pass in a scalar, major tics get scaled. You can pass in an array ref to scale minor tics too.
977
978
=item * rotate - turn label text by the given angle (in degrees) on the drawing plane
979
980
=item * offset - offset label text from default position, (units: characters; requires array ref containing x,y)
981
982
=item * locations - sets tic locations. Gets an array ref: [incr], [start, incr], or [start, incr, stop].
983
984
=item * labels - sets tic locations explicitly, with text labels for each. If you specify both C and C, you get both sets of tics on the same axis.
985
986
The labels should be a nested array ref that is a collection of duals
987
or triplets. Each dual or triplet should contain [label, position, minorflag],
988
as in C<< labels=>[["one",1,0],["three-halves",1.5,1],["two",2,0]] >>.
989
990
=item * format - printf-style format string for tic labels. There are
991
some extensions to the gnuplot format tags -- see the gnuplot manual.
992
Gnuplot 4.8 and higher have C<%h>, which works like C<%g> but uses
993
extended text formatting if it is available.
994
995
=item * font - set font name and size (system font name)
996
997
=item * rangelimited - set to 1 to limit tics to the range of values actually present in the plot
998
999
=item * textcolor - set the color of the tick labels (see L"Color specification">)
1000
1001
=back
1002
1003
For example, to turn on inward mirrored X axis ticks with diagonal Arial 9 text, use:
1004
1005
xtics => {axis=>1,mirror=>1,in=>1,rotate=>45,font=>'Arial,9'}
1006
1007
or
1008
1009
xtics => ['axis','mirror','in','rotate by 45','font "Arial,9"']
1010
1011
=head2 POs for time data values
1012
1013
The options described here are
1014
1015
=over
1016
1017
=item xmtics
1018
1019
=item x2mtics
1020
1021
=item ymtics
1022
1023
=item y2mtics
1024
1025
=item zmtics
1026
1027
=item cbmtics
1028
1029
=item xdtics
1030
1031
=item x2dtics
1032
1033
=item ydtics
1034
1035
=item y2dtics
1036
1037
=item zdtics
1038
1039
=item cbdtics
1040
1041
=item xdata
1042
1043
=item x2data
1044
1045
=item ydata
1046
1047
=item y2data
1048
1049
=item zdata
1050
1051
=item cbdata
1052
1053
=back
1054
1055
Gnuplot contains support for plotting absolute time and date on any of its axes,
1056
with conventional formatting. There are three main methods, which are mutually exclusive
1057
(i.e. you should not attempt to use two at once on the same axis).
1058
1059
=over 3
1060
1061
=item B
1062
1063
You can set any axis to plot timestamps rather than numeric values by
1064
setting the corresponding "data" plot option to "time",
1065
e.g. C<< xdata=>"time" >>. If you do so, then numeric values in the
1066
corresponding data are interpreted as UNIX time (seconds since the
1067
UNIX epoch, neglecting leap seconds). No provision is made for
1068
UTC<->TAI conversion. You can format how the times are plotted with
1069
the "format" option in the various "tics" options(above). Output
1070
specifiers should be in UNIX strftime(3) format -- for example,
1071
C<< xdata=>"time",xtics=>{format=>"%Y-%b-%dT%H:%M:%S"} >>
1072
will plot UNIX times as ISO timestamps in the ordinate.
1073
1074
Due to limitations within gnuplot, the time resolution in this mode is
1075
limited to 1 second - if you want fractional seconds, you must use numerically
1076
formatted times (and/or create your own tick labels using the C suboption
1077
to the C option.
1078
1079
B
1080
1081
Time format specifiers use the following printf-like codes:
1082
1083
=over 3
1084
1085
=item * B: C<%Y> is 4-digit year; C<%y> is 2-digit year (1969-2068)
1086
1087
=item * B: C<%m>: 01-12; C<%b> or C<%h>: abrev. name; C<%B>: full name
1088
1089
=item * B: C<%W> (week starting Monday); C<%U> (week starting Sunday)
1090
1091
=item * B: C<%j> (1-366; boundary is midnight)
1092
1093
=item * B: C<%d> (01-31)
1094
1095
=item * B: C<%w> (0-6, Sunday=0), %a (abrev. name), %A (full name)
1096
1097
=item * B: C<%k> (0-23); C<%H> (00-23); C<%l> (1-12); C<%I> (01-12)
1098
1099
=item * B: C<%p> ("am" or "pm")
1100
1101
=item * B: C<%M> (00-60)
1102
1103
=item * B: C<%S> (0-60)
1104
1105
=item * B: C<%s>
1106
1107
=item * B: C<%T> (same as C<%H:%M:%S>); C<%R> (same as C<%H:%M>); C<%r> (same as C<%I:%M:%S %p>)
1108
1109
=item * B: C<%D> (same as C<%m/%d/%y>); C<%F> (same as C<%Y-%m-%d>)
1110
1111
=item * B: use C<%DT%T>.
1112
1113
=back
1114
1115
=item B
1116
1117
If you just want to plot named days of the week, you can instead use
1118
the C options set plotting to day of week, where 0 is Sunday and 6
1119
is Saturday; values are interpreted modulo 7. For example, C<<
1120
xmtics=>1,xrange=>[-4,9] >> will plot two weeks from Wednesday to
1121
Wednesday. As far as output format goes, this is exactly equivalent to
1122
using the C<%w> option with full formatting - but you can treat the
1123
numeric range in terms of weeks rather than seconds.
1124
1125
=item B
1126
1127
The C options set plotting to months of the year, where 1 is January and 12 is
1128
December, so C<< xdtics=>1, xrange=>[0,4] >> will include Christmas through Easter.
1129
This is exactly equivalent to using the C<%d> option with full formatting - but you
1130
can treat the numeric range in terms of months rather than seconds.
1131
1132
=back
1133
1134
=head2 POs for location/size
1135
1136
The options described here are
1137
1138
=over
1139
1140
=item tmargin
1141
1142
=item bmargin
1143
1144
=item lmargin
1145
1146
=item rmargin
1147
1148
=item offsets
1149
1150
=item origin
1151
1152
=item size
1153
1154
=item justify
1155
1156
=item clip
1157
1158
=back
1159
1160
Adjusting the size, location, and margins of the plot on the plotting
1161
surface is something of a null operation for most single plots -- but
1162
you can tweak the placement and size of the plot with these options.
1163
That is particularly useful for multiplots, where you might like to
1164
make an inset plot or to lay out a set of plots in a custom way.
1165
1166
The margin options accept scalar values -- either a positive number of
1167
character heights or widths of margin around the plot compared to the
1168
edge of the device window, or a string that starts with "at screen "
1169
and interpolates a number containing the fraction of the plot window
1170
offset. The "at screen" technique allows exact plot placement and is
1171
an alternative to the C and C options below.
1172
1173
The C option allows you to put an empty boundary around the
1174
data, inside the plot borders, in an autosacaled graph. The offsets
1175
only affect the x1 and y1 axes, and only in 2D plot commands.
1176
C accepts an array ref with four values for the offsets, which
1177
are given in scientific (plotted) axis units.
1178
1179
The C option lets you specify the origin (lower left corner)
1180
of an individual plot on the plotting window. The coordinates are
1181
screen coordinates -- i.e. fraction of the total plotting window.
1182
1183
The size option lets you adjust the size and aspect ratio of the plot,
1184
as an absolute fraction of the plot window size. You feed in fractional
1185
ratios, as in C<< size=>[$xfrac, $yfrac] >>. You can also feed in some keywords
1186
to adjust the aspect ratio of the plot. The size option overrides any
1187
autoscaling that is done by the auto-layout in multiplot mode, so use
1188
with caution -- particularly if you are multiplotting. You can use
1189
"size" to adjust the aspect ratio of a plot, but this is deprecated
1190
in favor of the pseudo-option C.
1191
1192
C sets the scientific aspect ratio of a 2-D plot. Unity
1193
yields a plot with a square scientific aspect ratio. Larger
1194
numbers yield taller plots.
1195
1196
C controls the border between the plotted data and the border of the plot.
1197
There are three clip types supported: points, one, and two. You can set them
1198
independently by passing in booleans with their names: C<< clip=>[points=>1,two=>0] >>.
1199
1200
=head2 POs for Color: colorbox, palette, clut, pseudocolor, pc, perceptual, pcp
1201
1202
Color plots are supported via RGB and pseudocolor. Plots that use pseudcolor or
1203
grayscale can have a "color box" that shows the photometric meaning of the color.
1204
1205
The colorbox generally appears when necessary but can be controlled manually
1206
with the C option. C accepts a scalar boolean value indicating
1207
whether or no to draw a color box, or an array ref containing additional options.
1208
The options are all, well, optional but must appear in the order given:
1209
1210
=over 3
1211
1212
=item ( vertical | horizontal ) - indicates direction of the gradient in the box
1213
1214
=item ( default | user ) - indicates user origin and size
1215
1216
If you specify C the colorbox will be placed on the right-hand side of the plot; if you specify C, you give the location and size in subsequent arguments:
1217
1218
colorbox => [ 'user', 'origin'=>"$x,$y", 'size' => "$x,$y" ]
1219
1220
=item ( front | back ) - draws the colorbox before or after the plot
1221
1222
=item ( noborder | bdefault | border ) - specify border
1223
1224
The line style is a numeric type as described in the gnuplot manual.
1225
1226
=back
1227
1228
The C option offers many arguments that are not fully
1229
documented in this version but are explained in the gnuplot manual.
1230
It offers complete control over the pseudocolor mapping function.
1231
1232
For simple color maps, C gives access to a set of named color
1233
maps. (from "Color Look Up Table"). A few existing color maps are:
1234
"default", "gray", "sepia", "ocean", "rainbow", "heat1", "heat2", and
1235
"wheel". To see a complete list, specify an invalid table,
1236
e.g. C<< clut=>'xxx' >>. C is maintained but is superseded
1237
by C and C (below), which give access to a better variety
1238
of color tables, and have better support for scientific images.
1239
1240
C (synonym C) gives access to the color tables built
1241
in to the C package, if that package is
1242
available. It takes either a color table name or an array ref which
1243
is a collection of arguments that get sent to the
1244
C transform definition method. Sending
1245
the empty string or undef will generate a list of allowable color
1246
table names. Many of the color tables are "photometric" and
1247
will render photometric data correctly without gamma correction.
1248
1249
C (synonym C) gives the same access to
1250
C as does C, but the
1251
"equal-perceptual-difference" scaling is used -- i.e. input
1252
values are gamma-corrected by the module so that uniform
1253
shifts in numeric value yield approximately uniform perceptual
1254
shifts.
1255
1256
If you use C or C, and if
1257
C can be loaded, then the external module
1258
is used to define a custom Gnuplot palette by linear interpolation
1259
across 256 values. That palette is then used to translate your
1260
monochrome data to a color image. The Gnuplot output is assumed
1261
to be sRGB. This is probably OK for most output devices.
1262
1263
=head2 POs for 3D: trid, view, pm3d, hidden3d, dgrid3d, surface, xyplane, mapping
1264
1265
If C or its synonym C<3d> is true, Gnuplot renders a 3-D plot.
1266
This changes the default tuple size from 2 to 3. This
1267
option is used to switch between the Gnuplot "plot" and "splot"
1268
command, but it is tracked with persistent state just as any other
1269
option.
1270
1271
The C option controls the viewpoint of the 3-D plot. It takes a
1272
list of numbers: C<< view=>[$rot_x, $rot_z, $scale, $scale_z] >>. After
1273
each number, you can omit the subsequent ones. Alternatively,
1274
C<< view=>['map'] >> represents the drawing as a map (e.g. for contour
1275
plots) and C<< view=>[equal=>'xy'] >> forces equal length scales on the X
1276
and Y axes regardless of perspective, while C<< view=>[equal=>'xyz'] >>
1277
sets equal length scales on all three axes.
1278
1279
The C option accepts several parameters to control the pm3d plot style,
1280
which is a palette-mapped 3d surface. They are not documented here in this
1281
version of the module but are explained in the gnuplot manual.
1282
1283
C accepts a list of parameters to control how hidden surfaces are
1284
plotted (or not) in 3D. It accepts a boolean argument indicating whether to hide
1285
"hidden" surfaces and lines; or an array ref containing parameters that control how
1286
hidden surfaces and lines are handled. For details see the gnuplot manual.
1287
1288
C sets the location of that plane (which is drawn) relative
1289
to the rest of the plot in 3-space. It takes a single string: "at" or
1290
"relative", and a number. C<< xyplane=>[at=>$z] >> places the XY plane at the
1291
stated Z value (in scientific units) on the plot. C<< xyplane=>[relative=>$frac] >>
1292
places the XY plane $frac times the length of the scaled Z axis *below* the Z
1293
axis (i.e. 0 places it at the bottom of the plotted Z axis; and -1 places it
1294
at the top of the plotted Z axis).
1295
1296
C takes a single string: "cartesian", "spherical", or
1297
"cylindrical". It determines the interpretation of data coordinates
1298
in 3-space. (Compare to the C option in 2-D).
1299
1300
=head2 POs for Contour plots - contour, cntrparam
1301
1302
Contour plots are only implemented in 3D. To make a normal 2D contour
1303
plot, use 3-D mode, but set the view to "map" - which projects the 3-D
1304
plot onto its 2-D XY plane. (This is convoluted, for sure -- future
1305
versions of this module may have a cleaner way to do it).
1306
1307
C enables contour drawing on surfaces in 3D. It takes a
1308
single string, which should be "base", "surface", or "both".
1309
1310
C manages how contours are generated and smoothed. It
1311
accepts an array ref with a collection of Gnuplot parameters that are
1312
issued one per line; refer to the Gnuplot manual for how to operate
1313
it.
1314
1315
=head2 POs for Polar plots - polar, angles, mapping
1316
1317
You can make 2-D polar plots by setting C to a true value. The
1318
ordinate is then plotted as angle, and the abscissa is radius on the plot.
1319
The ordinate can be in either radians or degrees, depending on the
1320
C parameter
1321
1322
C takes either "degrees" or "radians" (default is radians).
1323
1324
C is used to set 3-D polar plots, either cylindrical or spherical
1325
(see the section on 3-D plotting, above).
1326
1327
=head2 POs for Markup - label, arrow, object
1328
1329
You specify plot markup in advance of the plot command, with plot
1330
options (or add it later with the C method). The options give
1331
you access to a collection of (separately) numbered descriptions that
1332
are accumulated into the plot object. To add a markup object to the
1333
next plot, supply the appropriate options as an array ref or as a single
1334
string. To specify all markup objects at once, supply the appropriate
1335
options for all of them as a nested list-of-lists.
1336
1337
To modify an object, you can specify it by number, either by appending
1338
the number to the plot option name (e.g. C) or by supplying it
1339
as the first element of the option list for that object.
1340
1341
To remove all objects of a given type, supply undef (e.g. C<< arrow=>undef >>).
1342
1343
For example, to place two labels, use the plot option:
1344
1345
label => [["Upper left",at=>"10,10"],["lower right",at=>"20,5"]];
1346
1347
To add a label to an existing plot object, if you don't care about what
1348
index number it gets, do this:
1349
1350
$w->options( label=>["my new label",at=>[10,20]] );
1351
1352
If you do care what index number it gets (or want to replace an existing label),
1353
do this:
1354
1355
$w->options( label=>[$n, "my replacement label", at=>"10,20"] );
1356
1357
where C<$w> is a Gnuplot object and C<$n> contains the label number
1358
you care about.
1359
1360
1361
=head3 label - add a text label to the plot.
1362
1363
The C option allows adding small bits of text at arbitrary
1364
locations on the plot.
1365
1366
Each label specifier array ref accepts the following suboptions, in
1367
order. All of them are optional -- if no options other than the index
1368
tag are given, then any existing label with that index is deleted.
1369
1370
For examples, please refer to the Gnuplot 4.4 manual, p. 117.
1371
1372
=over 3
1373
1374
=item - optional index number (integer)
1375
1376
=item - text to place on the plot.
1377
1378
You may supply double-quotes inside the string, but it is not
1379
necessary in most cases (only if the string contains just an integer
1380
and you are not specifying a .
1381
1382
=item at - where to place the text (sci. coordinates)
1383
1384
The should be a string containing a gnuplot position specifier.
1385
At its simplest, the position is just two numbers separated by
1386
a comma, as in C<< label2=>["foo",at=>"5,3"] >>, to specify (X,Y) location
1387
on the plot in scientific coordinates. Each number can be preceded
1388
by a coordinate system specifier; see the Gnuplot 4.4 manual (page 20)
1389
for details.
1390
1391
=item ( left | center | right ) - text placement rel. to position
1392
1393
=item rotate [ by ] - text rotation
1394
1395
If "rotate" appears in the list alone, then the label is rotated 90 degrees
1396
CCW (bottom-to-top instead of left-to-right). The following "by" clause is
1397
optional.
1398
1399
=item font "," - font specifier
1400
1401
The , must be double quoted in the string (this may be fixed
1402
in a future version), as in
1403
1404
label3=>["foo",at=>"3,4",font=>'"Helvetica,18"']
1405
1406
=item noenhanced - turn off gnuplot enhanced text processing (if enabled)
1407
1408
=item ( front | back ) - rendering order (last or first)
1409
1410
=item textcolor
1411
1412
=item (point | nopoint ) - control whether the exact position is marked
1413
1414
=item offset - offfset from position (in points).
1415
1416
=back
1417
1418
=head3 arrow - place an arrow or callout line on the plot
1419
1420
Works similarly to the C option, but with an arrow instead of text.
1421
1422
The arguments, all of which are optional but which must be given in the order listed,
1423
are:
1424
1425
=over 3
1426
1427
=item from - start of arrow line
1428
1429
The should be a string containing a gnuplot position specifier.
1430
At its simplest, the position is just two numbers separated by
1431
a comma, as in C<< arrow2=>["foo",at=>"5,3"] >>, to specify (X,Y) location
1432
on the plot in scientific coordinates. Each number can be preceded
1433
by a coordinate system specifier; see the Gnuplot 4.4 manual (page 20)
1434
for details.
1435
1436
=item ( to | rto ) - end of arrow line
1437
1438
These work like C. For absolute placement, use "to". For placement
1439
relative to the C position, use "rto".
1440
1441
=item (arrowstyle | as)
1442
1443
This specifies that the arrow be drawn in a particular predeclared numerical
1444
style. If you give this parameter, you should omit all the following ones.
1445
1446
=item ( nohead | head | backhead | heads ) - specify arrowhead placement
1447
1448
=item size ,, - specify arrowhead geometry
1449
1450
=item ( filled | empty | nofilled ) - specify arrowhead fill
1451
1452
=item ( front | back ) - specify drawing order ( last | first )
1453
1454
=item linestyle - specify a numeric linestyle
1455
1456
=item linetype - specify numeric line type
1457
1458
=item linewidth - multiplier on the width of the line
1459
1460
=back
1461
1462
=head3 object - place a shape on the graph
1463
1464
Cs are rectangles, ellipses, circles, or polygons that can be placed
1465
arbitrarily on the plotting plane.
1466
1467
The arguments, all of which are optional but which must be given in the order listed, are:
1468
1469
=over 3
1470
1471
=item - type name of the shape and its type-specific properties
1472
1473
The is one of four words: "rectangle", "ellipse", "circle", or "polygon".
1474
1475
You can specify a rectangle with C<< from=>$pos1, [r]to=>$pos2 >>, with C<< center=>$pos1, size=>"$w,$h" >>,
1476
or with C<< at=>$pos1,size=>"$w,$h" >>.
1477
1478
You can specify an ellipse with C<< at=>$pos, size=>"$w,$h" >> or C<< center=>$pos, size=>"$w,$h" >>, followed
1479
by C<< angle=>$a >>.
1480
1481
You can specify a circle with C<< at=>$pos, >> or C<< center=>$pos, >>, followed
1482
by C<< size=>$radius >> and (optionally) C<< arc=>"[$begin:$end]" >>.
1483
1484
You can specify a polygon with C<< from=>$pos1,to=>$pos2,to=>$pos3,...to=>$posn >> or with
1485
C<< from=>$pos1,rto=>$diff1,rto=>$diff2,...rto=>$diffn >>.
1486
1487
=item ( front | back | behind ) - draw the object last | first | really-first.
1488
1489
=item fc - specify fill color
1490
1491
=item fs - specify fill style
1492
1493
=item lw - multiplier on line width
1494
1495
=back
1496
1497
=head2 POs for appearance tweaks - bars, boxwidth, isosamples, pointsize, style
1498
1499
B> sets the width and behavior of the tick marks at the ends of error bars.
1500
It takes a list containing at most two elements, both of which are optional:
1501
1502
=over 3
1503
1504
=item * A width specifier, which should be a numeric size multiplier times the usual
1505
width (which is about one character width in the default font size), or the word
1506
C to make the ticks the same width as their associated boxes in boxplots
1507
and histograms.
1508
1509
=item * the word "front" or "back" to indicate drawing order in plots that might contain
1510
filled rectangles (e.g. boxes, candlesticks, or histograms).
1511
1512
=back
1513
1514
If you pass in the undefined value you get no ticks on errorbars; if you pass in the
1515
empty array ref you get default ticks.
1516
1517
B> sets the width of drawn boxes in boxplots, candlesticks, and histograms. It
1518
takes a list containing at most two elements:
1519
1520
=over 3
1521
1522
=item * a numeric width
1523
1524
=item * one of the words C or C.
1525
1526
=back
1527
1528
Unless you set C, the numeric width sets the width of boxes
1529
in X-axis scientific units (on log scales, this is measured at x=1 and
1530
the same width is used throughout the plot plane). If C is
1531
included, the numeric width is taken to be a multiplier on the default
1532
width.
1533
1534
B> sets isoline density for plotting functions as
1535
surfaces. You supply one or two numbers. The first is the number of
1536
iso-u lines and the second is the number of iso-v lines. If you only
1537
specify one, then the two are taken to be the same. From the gnuplot
1538
manual: "An isoline is a curve parameterized by one of the surface
1539
parameters while the other surface parameter is fixed. Isolines
1540
provide a simple means to display a surface. By fixing the u
1541
parameter of surface s(u,v), the iso-u lines of the form c(v) =
1542
s(u0,v) are produced, and by fixing the v parameter, the iso-v lines
1543
of the form c(u)=s(u,v0) are produced".
1544
1545
B> accepts a single number and scales the size of points used in plots.
1546
1547
B> provides a great deal of customization for individual plot styles.
1548
It is not (yet) fully parsed by PDL::Graphics::Gnuplot; please refer to the Gnuplot
1549
manual for details (it is pp. 145ff in the Gnuplot 4.6.1 manual). C