/
README.pod
2663 lines (1789 loc) · 91.1 KB
/
README.pod
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
=head1 OVERVIEW
This is a Gnuplot-based plotter for PDL. This repository stores the history for
the PDL::Graphics::Gnuplot module on CPAN. Install the module via CPAN. CPAN
page at L<http://metacpan.org/pod/PDL::Graphics::Gnuplot>.
=cut
=head1 NAME
PDL::Graphics::Gnuplot - Gnuplot-based plotting for PDL
=head1 SYNOPSIS
pdl> use PDL::Graphics::Gnuplot;
pdl> $x = sequence(101) - 50;
pdl> gplot($x**2);
pdl> gplot($x**2,{xr=>[0,50]});
pdl> gplot( {title => 'Parabola with error bars'},
with => 'xyerrorbars', legend => 'Parabola',
$x**2 * 10, abs($x)/10, abs($x)*5 );
pdl> $xy = zeroes(21,21)->ndcoords - pdl(10,10);
pdl> $z = inner($xy, $xy);
pdl> gplot({title => 'Heat map',
trid => 1,
view => [0,0]
},
with => 'image', xvals($z),yvals($z),zeroes($z),$z*2
);
pdl> $w = gpwin(); # constructor
pdl> $pi = 3.14159;
pdl> $theta = zeroes(200)->xlinvals(0, 6*$pi);
pdl> $z = zeroes(200)->xlinvals(0, 5);
pdl> $w->plot3d(cos($theta), sin($theta), $z);
pdl> $w->terminfo(); # get information
=head1 DESCRIPTION
This module allows PDL data to be plotted using Gnuplot as a backend
for 2D and 3D plotting and image display. Gnuplot (not affiliated
with the GNU project) is a venerable, open-source program that
produces both interactive and publication-quality plots on many
different output devices. It is available through most Linux
repositories, on MacOS, and from its website
L<http://www.gnuplot.info>.
It is not necessary to understand the gnuplot syntax to generate
basic, or even complex, plots - though the full syntax is available
for advanced users who want the full flexibility of the Gnuplot
backend.
For a very quick demonstration of the power of this module, see
L<this YouTube demo video|https://www.youtube.com/watch?v=hUXDQL3rZ_0>,
and others on visualisation of
L<tesseract assembly|https://www.youtube.com/watch?v=ykQmNrSKqGQ> and
L<rotation|https://www.youtube.com/watch?v=6tpsPYBrHy0>.
Gnuplot recognizes both hard-copy and interactive plotting devices,
and on interactive devices (like X11) it is possible to pan, scale,
and rotate both 2-D and 3-D plots interactively. You can also enter
graphical data through mouse clicks on the device window. On some
hardcopy devices (e.g. "PDF") that support multipage output, it is
necessary to close the device after plotting to ensure a valid file is
written out.
C<PDL::Graphics::Gnuplot> exports two routines by default: a
constructor, C<gpwin()> and a general purpose plot routine,
C<gplot()>. Depending on options, C<gplot()> can produce line plots,
scatterplots, error boxes, "candlesticks", images, or any overlain
combination of these elements; or perspective views of 3-D renderings
such as surface plots.
A call to C<gplot()> looks like:
gplot({temp_plot_options}, # optional hash ref
curve_options, data, data, ... ,
curve_options, data, data, ... );
The data entries are columns to be plotted. They are normally
an optional ordinate and a required abscissa, but some plot modes
can use more columns than that. The collection of columns is called
a "tuple". Each column must be a separate PDL or an ARRAY ref. If
all the columns are PDLs, you can add extra dimensions to make threaded
collections of curves.
PDL::Graphics::Gnuplot also implements an object oriented
interface. Plot objects track individual gnuplot subprocesses. Direct
calls to C<gplot()> are tracked through a global object that stores
globally set configuration variables.
The C<gplot()> sub (or the C<plot()> method) collects two kinds of
options hash: B<plot options>, which describe the overall structure of
the plot being produced (e.g. axis specifications, window size, and
title), and B<curve options>, which describe the behavior of
individual traces or collections of points being plotted. In
addition, the module itself supports options that allow direct
pass-through of plotting commands to the underlying gnuplot process.
=head2 Basic plotting
Gnuplot generates many kinds of plot, from basic line plots and histograms
to scaled labels. Individual plots can be 2-D or 3-D, and different sets
of plot styles are supported in each mode. Plots can be sent to a variety
of devices; see the description of plot options, below.
You can specify what type of graphics output you want, but in most cases
doing nothing will cause a plot to be rendered on your screen: with
X windows on UNIX or Linux systems, with an XQuartz windows on MacOS,
or with a native window on Microsoft Windows.
You select a plot style with the "with" curve option, and feed in columns
of data (usually ordinate followed by abscissa). The collection of columns
is called a "tuple". These plots have two columns in their tuples:
$x = xvals(51)-25; $y = $x**2;
gplot(with=>'points', $x, $y); # Draw points on a parabola
gplot(with=>'lines', $x, $y); # Draw a parabola
gplot({title=>"Parabolic fit"},
with=>"yerrorbars", legend=>"data", $x, $y+(random($y)-0.5)*2*$y/20, pdl($y/20),
with=>"lines", legend=>"fit", $x, $y);
Normal threading rules apply across the arguments to a given plot.
All data are required to be supplied as either PDLs or array refs.
If you use an array ref as a data column, then normal
threading is disabled. For example:
$x = xvals(5);
$y = xvals(5)**2;
$labels = ['one','two','three','four','five'];
gplot(with=>'labels',$x,$y,$labels);
See below for supported curve styles.
=head3 Modifying plots
Gnuplot is built around a monolithic plot model - it is not possible to
add new data directly to a plot without redrawing the entire plot. To support
replotting, PDL::Graphics::Gnuplot stores the data you plot in the plot object,
so that you can add new data with the "replot" command:
$w=gpwin(x11);
$x=xvals(101)/100;
$y=$x;
$w->plot($x,$y);
$w->replot($x,$y*$y);
For speed, the data are *not* disconnected from their original variables - so
this will plot X vs. sqrt(X):
$x = xvals(101)/100;
$y = xvals(101)/100;
$w->plot($x,$y);
$y->inplace->sqrt;
$w->replot();
=head3 Plotting to an image file or device
PDL:Graphics::Gnuplot can plot to most of the devices supported by
gnuplot itself. You can specify the file type with the "output"
method or the object constructor "gplot". Either one will allow you
to name a type of file to produce, and a collection of options speciic to
that type of output file.
=head3 Image plotting
Several of the plot styles accept image data. The tuple parameters work the
same way as for basic plots, but each "column" is a 2-D PDL rather than a 1-D PDL.
As a special case, the "with image" plot style accepts either a 2-D or a 3-D PDL.
If you pass in 3-D PDL, the extra dimension can have size 1, 3, or 4. It is interpreted
as running across (R,G,B,A) color planes.
=head3 3-D plotting
You can plot in 3-D by setting the plot option C<trid> to a true value. Three
dimensional plots accept either 1-D or 2-D PDLs as data columns. If you feed
in 2-D "columns", many of the common plot styles will generalize appropriately
to 3-D. For example, to plot a 2-D surface as a line grid, you can use the "lines"
style and feed in 2-D columns instead of 1-D columns.
=head2 Enhanced text
Most gnuplot output devices include the option to markup "enhanced text". That means
text is interpreted so that you can change its font and size, and insert superscripts
and subscripts into labels. Codes are:
=over 3
=item {}
Text grouping - enclose text in braces to group characters, as in LaTeX.
=item ^
Superscript the next character or group (shrinks it slightly too where that is supported).
=item _
Subscript the next character or group (shrinks it slightly too where that is supported).
=item @
Phantom box (occupies no width; controls height for super- and subscripting)
=item &
Controllable-width space, e.g. &{template-string}
=item ~
overstrike -- e.g. ~a{0.8-} overprints '-' on 'a', raised by 0.8xfontsize.
=item {/[fontname][=fontsize | *fontscale] text}
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.
=item \
Backslash escapes control characters to render them as themselves.
=back
=head2 Unicode text
Separately to "enhanced" text above, if you wish to include text that
is not ASCII, then you will need to pass data that has been UTF-8
encoded. Sample code to achieve this:
use utf8;
use Encode;
use PDL;
use PDL::Graphics::Gnuplot;
use PDL::Constants qw(PI);
sub plot_sin {
my ($w, $coeff) = @_;
my $xrange = [ -2*PI, 2*PI ];
my $x = zeroes(1e3)->xlinvals(@$xrange); my $y = sin($coeff * 2 * PI * $x);
my $title = "y = sin( $coeff * 2π * x )";
# to get around sending text through syswrite()
my $title_octets = encode('UTF-8', $title);
$w->plot(with=>'lines', $x, $y, {
xrange => $xrange,
title => $title_octets, # can not pass $title as-is
});
}
=head2 Color specification
There are several contexts where you can specify color of plot elements. In those
places, you can specify colors exactly as in the Gnuplot manual, or more tersely.
In general, a color spec can be any one of the following:
=over 3
=item - an integer
This specifies a recognizable unique color in the same order as used by the plotting engine.
=item - the name of a color
(e.g. "blue"). Supported color names are listed in the variable C<@Alien::Gnuplot::colors>.
=item - an RGB value string
Strings have the form C<#RRGGBB>, where the C<#> is literal and the RR, GG, and BB are hexadecimal bytes.
=item - the word "palette"
"palette" indicates that color is to be drawn from the scaled colorbar
palette (which you can set with the "clut" plot option), by lookup
using an additional column in the associated data tuple.
=item - the word "variable"
"variable" indicates that color is to be drawn from the integer
plotting colors used by the plotting engine, indexed by an additional
column in the associated data tuple.
=item - the phrase "rgb variable"
"rgb variable" indicates that color is to be directly specified by a
24 bit integer specifying 8-bit values for (from most significant byte
to least significant byte) R, G, and B in the output color. The
integer is drawn from an additional column in the associated data tuple.
=back
=head2 Plot styles supported
Gnuplot itself supports a wide range of plot styles, and all are supported by
PDL::Graphics::Gnuplot. Most of the basic plot styles collect tuples of 1-D columns
in 2-D mode (for ordinary plots), or either 1-D or 2-D "columns" in 3-D mode (for
grid surface plots and such). Image modes always collect tuples made of 2-D "columns".
You can pass in 1-D columns as either PDLs or ARRAY refs. That is important for
plot types (such as "labels") that require a collection of strings rather than
numeric data.
Each plot style can by modified to support particular colors or line
style options. These modifications get passed in as curve options (see
below). For example, to plot a blue line you can use
C<with=E<gt>'lines',lc=E<gt>'blue'>. To match the autogenerated style of a
particular line you can use the C<ls> curve option.
The GNuplot plot styles supported are:
=over 3
=item * C<boxerrorbars> - combo of C<boxes> and C<yerrorbars>, below (2D)
=item * C<boxes> - simple boxes around regions on the plot (2D)
=item * C<boxxyerrorbars> - Render X and Y error bars as boxes (2D)
=item * C<candlesticks> - Y error bars with inner and outer limits (2D)
=item * C<circles> - circles with variable radius at each point: X/Y/radius (2D)
=item * C<dots> - tiny points ("dots") at each point, e.g. for scatterplots (2D/3D)
=item * C<ellipses> - ellipses. Accepts X/Y/major/minor/angle (2D)
=item * C<filledcurves> - closed polygons or axis-to-line filled shapes (2D)
=item * C<financebars> - financial style plot. Accepts date/open/low/high/close (2D)
=item * C<fsteps> - square bin plot; delta-Y, then delta-X (see C<steps>, C<histeps>) (2D)
=item * C<histeps> - square bin plot; plateaus centered on X coords (see C<fsteps>, C<steps>) (2D)
=item * C<histogram> - binned histogram of dataset (not direct plot; see C<newhistogram>) (2D)
=item * C<fits> - (PDL-specific) renders FITS image files in scientific coordinates
=item * C<image> - Takes (i), (x,y,i), or (x,y,z,i). See C<rgbimage>, C<rgbalpha>, C<fits>. (2D/3D)
=item * C<impulses> - vertical line from axis to the plotted point (2D/3D)
=item * C<labels> - Text labels at specified locations all over the plot (2D/3D)
=item * C<lines> - regular line plot (2D/3D)
=item * C<linespoints> - line plot with symbols at plotted points (2D/3D)
=item * C<newhistogram> - multiple-histogram-friendly histogram style (see C<histogram>) (2D)
=item * C<points> - symbols at plotted points (2D/3D)
=item * C<rgbalpha> - R/G/B color image with variable transparency (2D/3D)
=item * C<rgbimage> - R/G/B color image (2D/3D)
=item * C<steps> - square bin plot; delta-X, then delta-Y (see C<fsteps>, C<histeps>) (2D)
=item * C<vectors> - Small arrows: (x,y,[z]) -> (x+dx,y+dy,[z+dz]) (2D/3D)
=item * C<xerrorbars> - points with X error bars ("T" form) (2D)
=item * C<xyerrorbars> - points with both X and Y error bars ("T" form) (2D)
=item * C<yerrorbars> - points with Y error bars ("T" form) (2D)
=item * C<xerrorlines> - line plot with X errorbars at each point. (2D)
=item * C<xyerrorlines> - line plot with XY errorbars at each point. (2D)
=item * C<yerrorlines> - line plot with Y error limits at each point. (2D)
=item * C<pm3d> - three-dimensional variable-position surface plot
=back
=head2 Options arguments
The plot options are parameters that affect the whole plot, like the title of
the plot, the axis labels, the extents, 2d/3d selection, etc. All the plot
options are described below in L<"Plot Options"|/"PLOT OPTIONS">. Plot options can be set
in the plot object, or passed to the plotting methods directly. Plot options can
be passed in as a leading interpolated hash, as a leading hash ref, or as a trailing
hash ref in the argument list to any of the main plotting routines (C<gplot>, C<plot>,
C<image>, etc.).
The curve options are parameters that affect only one curve in particular. Each
call to C<plot()> can contain many curves, and options for a particular curve
I<precede> the data for that curve in the argument list. The actual type of curve
(the "with" option) is persistent, but all other curve options and modifiers
are not. An example:
gplot( with => 'points', $x, $a,
{axes=> x1y2}, $x, $b,
with => 'lines', $x, $c );
This plots 3 curves: $a vs. $x plotted with points on the main y-axis (this is
the default), $b vs. $x plotted with points on the secondary y axis, and $c
vs. $x plotted with lines on the main y-axis (the default). Note that the curve
options can be supplied as either an inline hash or a hash ref.
All the curve options are described below in L<"Curve Options"|/"CURVE OPTIONS">.
If you want to plot multiple curves of the same type without setting
any curve options explicitly, you must include an empty hash ref
between the tuples for subsequent lines, as in:
gplot( $x, $a, {}, $x, $b, {}, $x, $c );
=head2 Data arguments
Following the curve options in the C<plot()> argument list is the
actual data being plotted. Each output data point is a "tuple" whose
size varies depending on what is being plotted. For example if we're
making a simple 2D x-y plot, each tuple has 2 values; if we're making
a 3d plot with each point having variable size and color, each tuple
has 5 values (x,y,z,size,color). Each tuple element must be passed
separately. For ordinary 2-D plots, the 0 dim of the tuple elements
runs across plotted point. PDL threading is active, so you can plot
multiple curves with similar curve options on a normal 2-D plot, just
by stacking data inside the passed-in PDLs. (An exception is that
threading is disabled if one or more of the data elements is a list
ref).
=head3 PDLs vs array refs
The usual way to pass in data is as a PDL -- one PDL per column of data
in the tuple. But strings, in particular, cannot easily be hammered into
PDLs. Therefore any column in each tuple can be an array ref containing
values (either numeric or string). The column is interpreted using the
usual polymorphous cast-behind-your-back behavior of Perl. For the sake
of sanity, if even one array ref is present in a tuple, then threading is
disabled in that tuple: everything has to have a nice 1-D shape.
=head3 Implicit domains
When making a simple 2D plot, if exactly 1 dimension is missing,
PDL::Graphics::Gnuplot will use C<sequence(N)> as the domain. This is
why code like C<plot(pdl(1,5,3,4,4) )> works. Only one PDL is given
here, but the plot type ("lines" by default) requires 2 elements per
tuple. We are thus exactly 1 ndarray short; C<sequence(5)> is used as
the missing domain PDL. This is thus equivalent to
C<plot(sequence(5), pdl(1,5,3,4,4) )>.
If plotting in 3d or displaying an image, an implicit domain will be
used if we are exactly 2 ndarrays short. In this case,
PDL::Graphics::Gnuplot will use a 2D grid as a domain. Example:
my $xy = zeros(21,21)->ndcoords - pdl(10,10);
gplot({'3d' => 1},
with => 'points', inner($xy, $xy));
gplot( with => 'image', sin(rvals(51,51)) );
Here the only given ndarray has dimensions (21,21). This is a 3D plot, so we are
exactly 2 ndarrays short. Thus, PDL::Graphics::Gnuplot generates an implicit
domain, corresponding to a 21-by-21 grid.
C<PDL::Graphics::Gnuplot> requires explicit separators between tuples
for different plots, so it is always clear from the arguments you pass
in just how many columns you are supplying. For example,
C<plot($a,$b)> will plot C<$b> vs. C<$a>. If you actually want to
plot an overlay of both C<$a> and C<$b> against array index, you want
C<plot($a,{},$b)> instead. The C<{}> is a hash ref containing a
collection of all the curve options that you are changing between
the two curves -- in this case, zero of them.
=head2 Images
PDL::Graphics::Gnuplot supports four styles of image plot, via the "with" curve option.
The "image" style accepts a single image plane and displays it using
the palette (pseudocolor map) that is specified in the plot options
for that plot. As a special case, if you supply as data a (3xWxH) or
(WxHx3) PDL it is treated as an RGB image and displayed with the
"rgbimage" style (below), provided there are at least 5 pixels in each of the
other two dimensions (just to be sure). For quick image display there
is also an "image" method:
use PDL::Graphics::Gnuplot qw/image gplot/;
$im = sin(rvals(51,51)/2);
image( $im ); # display the image
gplot( with=>'image', $im ); # display the image (longer form)
The colors are autoscaled in both cases. To set a particular color range, use
the 'cbrange' plot option:
image( {cbrange=>[0,1]}, $im );
You can plot rgb images directly with the image style, just by including a
3rd dimension of size 3 on your image:
$rgbim = pdl( xvals($im), yvals($im),rvals($im)/sqrt(2));
image( $rgbim ); # display an RGB image
gplot( with=>'image', $rgbim ); # display an RGB image (longer form)
Some additional plot styles exist to specify RGB and RGB transparent forms
directly. These are the "with" styles "rgbimage" and "rgbalpha". For each
of them you must specify the channels as separate PDLs:
gplot( with=>'rgbimage', $rgbim->dog ); # RGB the long way
gplot( with=>'rgbalpha', $rgbim->dog, 255*($im>0) ); # RGBA the long way
According to the gnuplot specification you can also give X and Y
values for each pixel, as in
gplot( with=>'image', xvals($im), yvals($im), $im )
but this appears not to work properly for anything more complicated
than a trivial matrix of X and Y values.
PDL::Graphics::Gnuplot provides a "fits" plot style that interprets
World Coordinate System (WCS) information supplied in the header of
the scientific image format FITS. The image is displayed in rectified
scientific coordinates, rather than in pixel coordinates. You can plot
FITS images in scientific coordinates with
gplot( with=>'fits', $fitsdata );
The fits plot style accepts a modifier "resample" (which may be
abbreviated), that allows you to downsample and/or rectify the image
before it is passed to the Gnuplot back-end. This is useful either to
cut down on the burden of transferring large blocks of image data or
to rectify images with nonlinear WCS transformations in their headers.
(gnuplot itself has a bug that prevents direct rendering of images in
nonlinear coordinates).
gplot( with=>'fits res 200', $fitsdata );
gplot( with=>'fits res 100,400',$fitsdata );
to specify that the output are to be resampled onto a square 200x200
grid or a 100x400 grid, respectively. The resample sizes must be
positive integers.
=head2 Interactivity
Several of the graphical backends of Gnuplot are interactive, allowing
you to pan, zoom, rotate and measure the data interactively in the plot
window. See the Gnuplot documentation for details about how to do
this. Some terminals (such as C<wxt>) are persistently interactive. Other
terminals (such as C<x11>) maintain their interactivity only while the
underlying gnuplot process is active -- i.e. until another plot is
created with the same PDL::Graphics::Gnuplot object, or until the perl
process exits (whichever comes first). Still others (the hardcopy
devices) aren't interactive at all.
Some interactive devices (notably C<wxt> and C<x11>) also support
mouse input: you can write PDL scripts that accept and manipulate
graphical input from the plotted window.
=head1 PLOT OPTIONS
Gnuplot controls plot style with "plot options" that configure and
specify virtually all aspects of the plot to be produced. Plot
options are tracked as stored state in the PDL::Graphics::Gnuplot
object. You can set them by passing them in to the constructor, to an
C<options> method, or to the C<plot> method itself.
Nearly all the underlying Gnuplot plot options are supported, as well
as some additional options that are parsed by the module itself for
convenience.
There are many, many plot options. For convenience, we've grouped
them by general category below. Each group has a heading "POs for E<lt>fooE<gt>",
describing the category. You can skip below them all if you want to
read about curve options or other aspects of PDL::Graphics::Gnuplot.
=head2 POs for Output: terminal, termoption, output, device, hardcopy
You can send plots to a variety of different devices; Gnuplot calls
devices "terminals". With the object-oriented interface, you must set
the output device with the constructor C<PDL::Graphics::Gnuplot::new>
(or the exported constructor C<gpwin>) or the C<output> method. If you
use the simple non-object interface, you can set the output with the
C<terminal>, C<termoption>, and C<output> plot options.
C<terminal> sets the output device type for Gnuplot, and C<output> sets the
actual output file or window number.
C<device> and C<hardcopy> are for convenience. C<device> offers a
PGPLOT-style device specifier in "filename/device" format (the "filename"
gets sent to the "output" option, the "device" gets sent to the "terminal"
option). C<hardcopy> takes an output file name, attempts to parse out a
file suffix and infer a device type. C<hardcopy> also uses a common set of
terminal options needed to fill an entire letter page with a plot.
For finer grained control of the plotting environment, you can send
"terminal options" to Gnuplot. If you set the terminal directly with
plot options, you can include terminal options by interpolating them
into a string, as in C<terminal jpeg interlace butt crop>, or you can
use the constructor C<new> (also exported as C<gpwin>), which parses
terminal options as an argument list.
The routine C<PDL::Graphics::Gnuplot::terminfo> prints a list of all
available terminals or, if you pass in a terminal name, options accepted
by that terminal.
=head2 POs for Titles
The options described here are
=over
=item title
=item xlabel
=item x2label
=item ylabel
=item y2label
=item zlabel
=item cblabel
=item key
=back
Gnuplot supports "enhanced" text escapes on most terminals; see "text",
below.
The C<title> option lets you set a title for the whole plot.
Individual plot components are labeled with the C<label> options.
C<xlabel>, C<x2label>, C<ylabel>, and C<y2label> specify axis titles
for 2-D plots. The C<zlabel> works for 3-D plots. The C<cblabel> option
sets the label for the color box, in plot types that have one (e.g.
image display).
(Don't be confused by C<clabel>, which doesn't set a label at all, rather
specifies the printf format used by contour labels in contour plots.)
C<key> controls where the plot key (that relates line/symbol style to label)
is placed on the plot. It takes a scalar boolean indicating whether to turn the
key on (with default values) or off, or an array ref containing any of the following
arguments (all are optional) in the order listed:
=over 3
=item * ( on | off ) - turn the key on or off
=item * ( inside | outside | lmargin | rmargin | tmargin | bmargin | at <pos> )
These keywords set the location of the key -- "inside/outside" is
relative to the plot border; the margin keywords indicate location in
the margins of the plot; and at <pos> (where <pos> is a comma-delimited string
containing (x,y): C<key=E<gt>[at=E<gt>"0.5,0.5"]>) is an exact location to place the key.
=item * ( left | right | center ) ( top | bottom | center ) - horiz./vert. alignment
=item * ( vertical | horizontal ) - stacking direction within the key
=item * ( Left | Right ) - justification of plot labels within the key (note case)
=item * [no]reverse - switch order of label and sample line
=item * [no]invert - invert the stack order of the labels
=item * samplen <length> - set the length of the sample lines
=item * spacing <dist> - set the spacing between adjacent labels in the list
=item * [no]autotitle - control whether labels are generated when not specified
=item * title "<text>" - set a title for the key
=item * [no]enhanced - override terminal settings for enhanced text interpretation
=item * font "<face>,<size>" - set font for the labels
=item * textcolor <colorspec>
=item * [no]box linestyle <ls> linetype <lt> linewidth <lw> - control box around the key
=back
=head2 POs for axes, grids, & borders
The options described here are
=over
=item grid
=item xzeroaxis
=item x2zeroaxis
=item yzeroaxis
=item y2zeroaxis
=item zzeroaxis
=item border
=back
Normally, tick marks and their labels are applied to the border of a plot,
and no extra axes (e.g. the y=0 line) nor coordinate grids are shown. You can
specify which (if any) zero axes should be drawn, and which (if any)
borders should be drawn.
The C<border> option controls whether the plot itself has a border
drawn around it. You can feed it a scalar boolean value to indicate
whether borders should be drawn around the plot -- or you can feed in a list
ref containing options. The options are all optional but must be supplied
in the order given.
=over 3
=item * <integer> - packed bit flags for which border lines to draw
The default if you set a true value for C<border> is to draw all border lines.
You can feed in a single integer value containing a bit mask, to draw only some
border lines. From LSB to MSB, the coded lines are bottom, left, top, right for
2D plots -- e.g. 5 will draw bottom and top borders but neither left nor right.
In three dimensions, 12 bits are used to describe the twelve edges of
a cube surrounding the plot. In groups of three, the first four
control the bottom (xy) plane edges in the same order as in the 2-D
plots; the middle four control the vertical edges that rise from the
clockwise end of the bottom plane edges; and the last four control the
top plane edges.
=item * ( back | front ) - draw borders first or last (controls hidden line appearance)
=item * linewidth <lw>, linestyle <ls>, linetype <lt>
These are Gnuplot's usual three options for line control.
=back
The C<grid> option indicates whether gridlines should be drawn on
each axis. It takes an array ref of arguments, each of which is either "no" or "m" or "",
followed by an axis name and "tics" --
e.g. C<< grid=>["noxtics","ymtics"] >> draws no X gridlines and draws
(horizontal) Y gridlines on Y axis major and minor tics, while
C<< grid=>["xtics","ytics"] >> or C<< grid=>["xtics ytics"] >> will draw both
vertical (X) and horizontal (Y) grid lines on major tics.
To draw a coordinate grid with default values, set C<< grid=>1 >>. For more
control, feed in an array ref with zero or more of the following parameters, in order:
The C<zeroaxis> keyword indicates whether to actually draw each axis
line at the corresponding zero along its indicated dimension. For
example, to draw the X axis (y=0), use C<< xzeroaxis=>1 >>. If you just
want the axis turned on with default values, you can feed in a Boolean
scalar; if you want to set its parameters, you can feed in an array ref
containing linewidth, linestyle, and linetype (with appropriate
parameters for each), e.g. C<< xzeroaxis=>[linewidth=>2] >>.
=head2 POs for axis range and mode
The options described here are
=over
=item xrange
=item x2range
=item yrange
=item y2range
=item zrange
=item rrange
=item cbrange
=item trange
=item urange
=item vrange
=item autoscale
=item logscale
=back
Gnuplot accepts explicit ranges as plot options for all axes. Each option
accepts an array ref with (min, max). If either min or max is missing, then
the opposite limit is autoscaled. The x and y ranges refer to the usual
ordinate and abscissa of the plot; x2 and y2 refer to alternate ordinate and
abscissa; z if for 3-D plots; r is for polar plots; t, u, and v are for parametric
plots. cb is for the color box on plots that include it (see "color", below).
C<rrange> is used for radial coordinates (which
are accessible using the C<mapping> plot option, below).
C<cbrange> (for 'color box range') sets the range of values over which
palette colors (either gray or pseudocolor) are matched. It is valid
in any color-mapped plot (including images or palette-mapped lines or
points), even if no color box is being displayed for this plot.
C<trange>, C<urange>, and C<vrange> set ranges for the parametric coordinates
if you are plotting a parametric curve.
By default all axes are autoscaled unless you specify a range on that
axis, and partially (min or max) autoscaled if you specify a partial
range on that axis. C<autoscale> allows more explicit control of how
autoscaling is performed, on an axis-by-axis basis. It accepts a hash
ref, each element of which specifies how a single axis should be
autoscaled. Each keyword contains an axis name followed by one of
"fix", "min", "max", "fixmin", or "fixmax". You can set all the axes at
once by setting the keyword name to ' '. Examples:
autoscale=>{x=>'max',y=>'fix'};
There is an older array ref syntax which is deprecated but still accepted.
To not autoscale an axis at all, specify a range for it. The fix style of
autoscaling forces the autoscaler to use the actual min/max of the data as
the limit for the corresponding axis -- by default the axis gets extended
to the next minor tic (as set by the autoticker or by a tic specification, see
below).
C<logscale> allows you to turn on logarithmic scaling for any or all
axes, and to set the base of the logarithm. It takes an array ref, the
first element of which is a string mushing together the names of all
the axes to scale logarithmically, and the second of which is the base
of the logarithm: C<< logscale=>[xy=>10] >>. You can also leave off the
base if you want base-10 logs: C<< logscale=>['xy'] >>.
=head2 POs for Axis tick marks
The options described here are
=over
=item xtics
=item x2tics
=item ytics
=item y2tics
=item ztics
=item cbtics
=item mxtics
=item mx2tics
=item mytics
=item my2tics
=item mztics
=item mcbtics
=back
Axis tick marks are called "tics" within Gnuplot, and they are extensively
controllable via the "{axis}tics" options. In particular, major and minor
ticks are supported, as are arbitrarily variable length ticks, non-equally
spaced ticks, and arbitrarily labelled ticks. Support exists for time formatted
ticks (see C<POs for time data values> below).
By default, gnuplot will automatically place major and minor ticks.
You can turn off ticks on an axis by setting the appropriate {foo}tics
option to a defined, false scalar value (e.g. C<< xtics=>0 >>). If you
want to set major tics to happen at a regular specified intervals, you can set the
appropriate tics option to a nonzero scalar value (e.g. C<< xtics=>2 >> to
specify a tic every 2 units on the X axis). To use default values for the
tick positioning, specify an empty hash or array ref (e.g. C<< xtics=>{} >>), or
a string containing only whitespace (e.g. C<< xtics=>' ' >>).
If you prepend an 'm' to any tics option, it affects minor tics instead of
major tics (major tics typically show units; minor tics typically show fractions
of a unit).
Each tics option can accept a hash ref containing options to pass to
Gnuplot. You can also pass in a snippet of gnuplot command, as either
a string or an array ref -- but those techniques are deprecated and may
disappear in a future version of C<PDL:Graphics::Gnuplot>.
The keywords are case-insensitive and may be abbreviated, just as with
other option types. They are:
=over 2
=item * axis - set to 1 to place tics on the axis (the default)
=item * border - set to 1 to place tics on the border (not the default)
=item * mirror - set to 1 to place mirrored tics on the opposite axis/border (the default, unless an alternate axis interferes -- e.g. y2)
=item * in - set to 1 to draw tics inward from the axis/border
=item * out - set to 1 to draw tics outward from the axis/border
=item * scale - multiplier on tic length compared to the default
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.
=item * rotate - turn label text by the given angle (in degrees) on the drawing plane
=item * offset - offset label text from default position, (units: characters; requires array ref containing x,y)
=item * locations - sets tic locations. Gets an array ref: [incr], [start, incr], or [start, incr, stop].
=item * labels - sets tic locations explicitly, with text labels for each. If you specify both C<locations> and C<labels>, you get both sets of tics on the same axis.
The labels should be a nested array ref that is a collection of duals
or triplets. Each dual or triplet should contain [label, position, minorflag],
as in C<< labels=>[["one",1,0],["three-halves",1.5,1],["two",2,0]] >>.
=item * format - printf-style format string for tic labels. There are
some extensions to the gnuplot format tags -- see the gnuplot manual.
Gnuplot 4.8 and higher have C<%h>, which works like C<%g> but uses
extended text formatting if it is available.
=item * font - set font name and size (system font name)
=item * rangelimited - set to 1 to limit tics to the range of values actually present in the plot
=item * textcolor - set the color of the tick labels (see L</"Color specification">)
=back
For example, to turn on inward mirrored X axis ticks with diagonal Arial 9 text, use:
xtics => {axis=>1,mirror=>1,in=>1,rotate=>45,font=>'Arial,9'}
or
xtics => ['axis','mirror','in','rotate by 45','font "Arial,9"']
=head2 POs for time data values
The options described here are
=over
=item xmtics
=item x2mtics
=item ymtics
=item y2mtics
=item zmtics
=item cbmtics
=item xdtics
=item x2dtics
=item ydtics
=item y2dtics
=item zdtics
=item cbdtics
=item xdata
=item x2data
=item ydata
=item y2data
=item zdata
=item cbdata
=back
Gnuplot contains support for plotting absolute time and date on any of its axes,
with conventional formatting. There are three main methods, which are mutually exclusive
(i.e. you should not attempt to use two at once on the same axis).
=over 3
=item B<Plotting timestamps using UNIX times>
You can set any axis to plot timestamps rather than numeric values by
setting the corresponding "data" plot option to "time",
e.g. C<< xdata=>"time" >>. If you do so, then numeric values in the
corresponding data are interpreted as UNIX time (seconds since the