.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "PDL::Graphics::Gnuplot 3pm" .TH PDL::Graphics::Gnuplot 3pm "2023-04-01" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" PDL::Graphics::Gnuplot \- Gnuplot\-based plotting for PDL .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& pdl> use PDL::Graphics::Gnuplot; \& \& pdl> $x = sequence(101) \- 50; \& pdl> gplot($x**2); \& pdl> gplot($x**2,{xr=>[0,50]}); \& \& pdl> gplot( {title => \*(AqParabola with error bars\*(Aq}, \& with => \*(Aqxyerrorbars\*(Aq, legend => \*(AqParabola\*(Aq, \& $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 => \*(AqHeat map\*(Aq, \& trid => 1, \& view => [0,0] \& }, \& with => \*(Aqimage\*(Aq, 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 .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module allows \s-1PDL\s0 data to be plotted using Gnuplot as a backend for 2D and 3D plotting and image display. Gnuplot (not affiliated with the \s-1GNU\s0 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 . .PP 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. .PP For a very quick demonstration of the power of this module, see this YouTube demo video , and others on visualisation of tesseract assembly and rotation . .PP 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. \*(L"\s-1PDF\*(R"\s0) that support multipage output, it is necessary to close the device after plotting to ensure a valid file is written out. .PP \&\f(CW\*(C`PDL::Graphics::Gnuplot\*(C'\fR exports two routines by default: a constructor, \f(CW\*(C`gpwin()\*(C'\fR and a general purpose plot routine, \&\f(CW\*(C`gplot()\*(C'\fR. Depending on options, \f(CW\*(C`gplot()\*(C'\fR can produce line plots, scatterplots, error boxes, \*(L"candlesticks\*(R", images, or any overlain combination of these elements; or perspective views of 3\-D renderings such as surface plots. .PP A call to \f(CW\*(C`gplot()\*(C'\fR looks like: .PP .Vb 3 \& gplot({temp_plot_options}, # optional hash ref \& curve_options, data, data, ... , \& curve_options, data, data, ... ); .Ve .PP 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 \*(L"tuple\*(R". Each column must be a separate \s-1PDL\s0 or an \s-1ARRAY\s0 ref. If all the columns are PDLs, you can add extra dimensions to make threaded collections of curves. .PP PDL::Graphics::Gnuplot also implements an object oriented interface. Plot objects track individual gnuplot subprocesses. Direct calls to \f(CW\*(C`gplot()\*(C'\fR are tracked through a global object that stores globally set configuration variables. .PP The \f(CW\*(C`gplot()\*(C'\fR sub (or the \f(CW\*(C`plot()\*(C'\fR method) collects two kinds of options hash: \fBplot options\fR, which describe the overall structure of the plot being produced (e.g. axis specifications, window size, and title), and \fBcurve options\fR, 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. .SS "Basic plotting" .IX Subsection "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. .PP 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 \s-1UNIX\s0 or Linux systems, with an XQuartz windows on MacOS, or with a native window on Microsoft Windows. .PP You select a plot style with the \*(L"with\*(R" curve option, and feed in columns of data (usually ordinate followed by abscissa). The collection of columns is called a \*(L"tuple\*(R". These plots have two columns in their tuples: .PP .Vb 6 \& $x = xvals(51)\-25; $y = $x**2; \& gplot(with=>\*(Aqpoints\*(Aq, $x, $y); # Draw points on a parabola \& gplot(with=>\*(Aqlines\*(Aq, $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); .Ve .PP Normal threading rules apply across the arguments to a given plot. .PP All data are required to be supplied as either PDLs or list refs. If you use a list ref as a data column, then normal threading is disabled. For example: .PP .Vb 4 \& $x = xvals(5); \& $y = xvals(5)**2; \& $labels = [\*(Aqone\*(Aq,\*(Aqtwo\*(Aq,\*(Aqthree\*(Aq,\*(Aqfour\*(Aq,\*(Aqfive\*(Aq]; \& gplot(with=>\*(Aqlabels\*(Aq,$x,$y,$labels); .Ve .PP See below for supported curve styles. .PP \fIModifying plots\fR .IX Subsection "Modifying plots" .PP 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 \*(L"replot\*(R" command: .PP .Vb 5 \& $w=gpwin(x11); \& $x=xvals(101)/100; \& $y=$x; \& $w\->plot($x,$y); \& $w\->replot($x,$y*$y); .Ve .PP For speed, the data are *not* disconnected from their original variables \- so this will plot X vs. sqrt(X): .PP .Vb 5 \& $x = xvals(101)/100; \& $y = xvals(101)/100; \& $w\->plot($x,$y); \& $y\->inplace\->sqrt; \& $w\->replot(); .Ve .PP \fIPlotting to an image file or device\fR .IX Subsection "Plotting to an image file or device" .PP PDL:Graphics::Gnuplot can plot to most of the devices supported by gnuplot itself. You can specify the file type with the \*(L"output\*(R" method or the object constructor \*(L"gplot\*(R". 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. .PP \fIImage plotting\fR .IX Subsection "Image plotting" .PP Several of the plot styles accept image data. The tuple parameters work the same way as for basic plots, but each \*(L"column\*(R" is a 2\-D \s-1PDL\s0 rather than a 1\-D \s-1PDL.\s0 As a special case, the \*(L"with image\*(R" plot style accepts either a 2\-D or a 3\-D \s-1PDL.\s0 If you pass in 3\-D \s-1PDL,\s0 the extra dimension can have size 1, 3, or 4. It is interpreted as running across (R,G,B,A) color planes. .PP \fI3\-D plotting\fR .IX Subsection "3-D plotting" .PP You can plot in 3\-D by setting the plot option \f(CW\*(C`trid\*(C'\fR to a true value. Three dimensional plots accept either 1\-D or 2\-D PDLs as data columns. If you feed in 2\-D \*(L"columns\*(R", 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 \*(L"lines\*(R" style and feed in 2\-D columns instead of 1\-D columns. .SS "Enhanced text" .IX Subsection "Enhanced text" Most gnuplot output devices include the option to markup \*(L"enhanced text\*(R". That means text is interpreted so that you can change its font and size, and insert superscripts and subscripts into labels. Codes are: .IP "{}" 3 Text grouping \- enclose text in braces to group characters, as in LaTeX. .IP "^" 3 Superscript the next character or group (shrinks it slightly too where that is supported). .IP "_" 3 .IX Item "_" Subscript the next character or group (shrinks it slightly too where that is supported). .IP "@" 3 Phantom box (occupies no width; controls height for super\- and subscripting) .IP "&" 3 Controllable-width space, e.g. &{template\-string} .IP "~" 3 overstrike \*(-- e.g. ~a{0.8\-} overprints '\-' on 'a', raised by 0.8xfontsize. .IP "{/[fontname][=fontsize | *fontscale] text}" 3 .IX Item "{/[fontname][=fontsize | *fontscale] text}" Change font to (optional) fontname, and optional absolute font size or relative font scale (\*(L"fontsize\*(R" and \*(L"fontscale\*(R" are numbers). The space after the size parameter is not rendered. .IP "\e" 3 .IX Item "" Backslash escapes control characters to render them as themselves. .SS "Color specification" .IX Subsection "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: .IP "\- an integer" 3 .IX Item "- an integer" This specifies a recognizable unique color in the same order as used by the plotting engine. .IP "\- the name of a color" 3 .IX Item "- the name of a color" (e.g. \*(L"blue\*(R"). Supported color names are listed in the variable \f(CW@Alien::Gnuplot::colors\fR. .IP "\- an \s-1RGB\s0 value string" 3 .IX Item "- an RGB value string" Strings have the form \f(CW\*(C`#RRGGBB\*(C'\fR, where the \f(CW\*(C`#\*(C'\fR is literal and the \s-1RR, GG,\s0 and \s-1BB\s0 are hexadecimal bytes. .ie n .IP "\- the word ""palette""" 3 .el .IP "\- the word ``palette''" 3 .IX Item "- the word palette" \&\*(L"palette\*(R" indicates that color is to be drawn from the scaled colorbar palette (which you can set with the \*(L"clut\*(R" plot option), by lookup using an additional column in the associated data tuple. .ie n .IP "\- the word ""variable""" 3 .el .IP "\- the word ``variable''" 3 .IX Item "- the word variable" \&\*(L"variable\*(R" 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. .ie n .IP "\- the phrase ""rgb variable""" 3 .el .IP "\- the phrase ``rgb variable''" 3 .IX Item "- the phrase rgb variable" \&\*(L"rgb variable\*(R" 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. .SS "Plot styles supported" .IX Subsection "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 \*(L"columns\*(R" in 3\-D mode (for grid surface plots and such). Image modes always collect tuples made of 2\-D \*(L"columns\*(R". .PP You can pass in 1\-D columns as either PDLs or \s-1ARRAY\s0 refs. That is important for plot types (such as \*(L"labels\*(R") that require a collection of strings rather than numeric data. .PP 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 \&\f(CW\*(C`with=>\*(Aqlines\*(Aq,lc=>\*(Aqblue\*(Aq\*(C'\fR. To match the autogenerated style of a particular line you can use the \f(CW\*(C`ls\*(C'\fR curve option. .PP The GNuplot plot styles supported are: .IP "\(bu" 3 \&\f(CW\*(C`boxerrorbars\*(C'\fR \- combo of \f(CW\*(C`boxes\*(C'\fR and \f(CW\*(C`yerrorbars\*(C'\fR, below (2D) .IP "\(bu" 3 \&\f(CW\*(C`boxes\*(C'\fR \- simple boxes around regions on the plot (2D) .IP "\(bu" 3 \&\f(CW\*(C`boxxyerrorbars\*(C'\fR \- Render X and Y error bars as boxes (2D) .IP "\(bu" 3 \&\f(CW\*(C`candlesticks\*(C'\fR \- Y error bars with inner and outer limits (2D) .IP "\(bu" 3 \&\f(CW\*(C`circles\*(C'\fR \- circles with variable radius at each point: X/Y/radius (2D) .IP "\(bu" 3 \&\f(CW\*(C`dots\*(C'\fR \- tiny points (\*(L"dots\*(R") at each point, e.g. for scatterplots (2D/3D) .IP "\(bu" 3 \&\f(CW\*(C`ellipses\*(C'\fR \- ellipses. Accepts X/Y/major/minor/angle (2D) .IP "\(bu" 3 \&\f(CW\*(C`filledcurves\*(C'\fR \- closed polygons or axis-to-line filled shapes (2D) .IP "\(bu" 3 \&\f(CW\*(C`financebars\*(C'\fR \- financial style plot. Accepts date/open/low/high/close (2D) .IP "\(bu" 3 \&\f(CW\*(C`fsteps\*(C'\fR \- square bin plot; delta-Y, then delta-X (see \f(CW\*(C`steps\*(C'\fR, \f(CW\*(C`histeps\*(C'\fR) (2D) .IP "\(bu" 3 \&\f(CW\*(C`histeps\*(C'\fR \- square bin plot; plateaus centered on X coords (see \f(CW\*(C`fsteps\*(C'\fR, \f(CW\*(C`steps\*(C'\fR) (2D) .IP "\(bu" 3 \&\f(CW\*(C`histogram\*(C'\fR \- binned histogram of dataset (not direct plot; see \f(CW\*(C`newhistogram\*(C'\fR) (2D) .IP "\(bu" 3 \&\f(CW\*(C`fits\*(C'\fR \- (PDL-specific) renders \s-1FITS\s0 image files in scientific coordinates .IP "\(bu" 3 \&\f(CW\*(C`image\*(C'\fR \- Takes (i), (x,y,i), or (x,y,z,i). See \f(CW\*(C`rgbimage\*(C'\fR, \f(CW\*(C`rgbalpha\*(C'\fR, \f(CW\*(C`fits\*(C'\fR. (2D/3D) .IP "\(bu" 3 \&\f(CW\*(C`impulses\*(C'\fR \- vertical line from axis to the plotted point (2D/3D) .IP "\(bu" 3 \&\f(CW\*(C`labels\*(C'\fR \- Text labels at specified locations all over the plot (2D/3D) .IP "\(bu" 3 \&\f(CW\*(C`lines\*(C'\fR \- regular line plot (2D/3D) .IP "\(bu" 3 \&\f(CW\*(C`linespoints\*(C'\fR \- line plot with symbols at plotted points (2D/3D) .IP "\(bu" 3 \&\f(CW\*(C`newhistogram\*(C'\fR \- multiple-histogram-friendly histogram style (see \f(CW\*(C`histogram\*(C'\fR) (2D) .IP "\(bu" 3 \&\f(CW\*(C`points\*(C'\fR \- symbols at plotted points (2D/3D) .IP "\(bu" 3 \&\f(CW\*(C`rgbalpha\*(C'\fR \- R/G/B color image with variable transparency (2D/3D) .IP "\(bu" 3 \&\f(CW\*(C`rgbimage\*(C'\fR \- R/G/B color image (2D/3D) .IP "\(bu" 3 \&\f(CW\*(C`steps\*(C'\fR \- square bin plot; delta-X, then delta-Y (see \f(CW\*(C`fsteps\*(C'\fR, \f(CW\*(C`histeps\*(C'\fR) (2D) .IP "\(bu" 3 \&\f(CW\*(C`vectors\*(C'\fR \- Small arrows: (x,y,[z]) \-> (x+dx,y+dy,[z+dz]) (2D/3D) .IP "\(bu" 3 \&\f(CW\*(C`xerrorbars\*(C'\fR \- points with X error bars (\*(L"T\*(R" form) (2D) .IP "\(bu" 3 \&\f(CW\*(C`xyerrorbars\*(C'\fR \- points with both X and Y error bars (\*(L"T\*(R" form) (2D) .IP "\(bu" 3 \&\f(CW\*(C`yerrorbars\*(C'\fR \- points with Y error bars (\*(L"T\*(R" form) (2D) .IP "\(bu" 3 \&\f(CW\*(C`xerrorlines\*(C'\fR \- line plot with X errorbars at each point. (2D) .IP "\(bu" 3 \&\f(CW\*(C`xyerrorlines\*(C'\fR \- line plot with \s-1XY\s0 errorbars at each point. (2D) .IP "\(bu" 3 \&\f(CW\*(C`yerrorlines\*(C'\fR \- line plot with Y error limits at each point. (2D) .IP "\(bu" 3 \&\f(CW\*(C`pm3d\*(C'\fR \- three-dimensional variable-position surface plot .SS "Options arguments" .IX Subsection "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\*(R". 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 (\f(CW\*(C`gplot\*(C'\fR, \f(CW\*(C`plot\*(C'\fR, \&\f(CW\*(C`image\*(C'\fR, etc.). .PP The curve options are parameters that affect only one curve in particular. Each call to \f(CW\*(C`plot()\*(C'\fR can contain many curves, and options for a particular curve \&\fIprecede\fR the data for that curve in the argument list. The actual type of curve (the \*(L"with\*(R" option) is persistent, but all other curve options and modifiers are not. An example: .PP .Vb 3 \& gplot( with => \*(Aqpoints\*(Aq, $x, $a, \& {axes=> x1y2}, $x, $b, \& with => \*(Aqlines\*(Aq, $x, $c ); .Ve .PP This plots 3 curves: \f(CW$a\fR vs. \f(CW$x\fR plotted with points on the main y\-axis (this is the default), \f(CW$b\fR vs. \f(CW$x\fR plotted with points on the secondary y axis, and \f(CW$c\fR vs. \f(CW$x\fR 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. .PP All the curve options are described below in \*(L"Curve Options\*(R". .PP 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: .PP .Vb 1 \& gplot( $x, $a, {}, $x, $b, {}, $x, $c ); .Ve .SS "Data arguments" .IX Subsection "Data arguments" Following the curve options in the \f(CW\*(C`plot()\*(C'\fR argument list is the actual data being plotted. Each output data point is a \*(L"tuple\*(R" 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. \s-1PDL\s0 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). .PP \fIPDLs vs list refs\fR .IX Subsection "PDLs vs list refs" .PP The usual way to pass in data is as a \s-1PDL\s0 \*(-- one \s-1PDL\s0 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 a list 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 list ref is present in a tuple, then threading is disabled in that tuple: everything has to have a nice 1\-D shape. .PP \fIImplicit domains\fR .IX Subsection "Implicit domains" .PP When making a simple 2D plot, if exactly 1 dimension is missing, PDL::Graphics::Gnuplot will use \f(CWsequence(N)\fR as the domain. This is why code like \f(CW\*(C`plot(pdl(1,5,3,4,4) )\*(C'\fR works. Only one \s-1PDL\s0 is given here, but the plot type (\*(L"lines\*(R" by default) requires 2 elements per tuple. We are thus exactly 1 ndarray short; \f(CWsequence(5)\fR is used as the missing domain \s-1PDL.\s0 This is thus equivalent to \&\f(CW\*(C`plot(sequence(5), pdl(1,5,3,4,4) )\*(C'\fR. .PP 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: .PP .Vb 4 \& my $xy = zeros(21,21)\->ndcoords \- pdl(10,10); \& gplot({\*(Aq3d\*(Aq => 1}, \& with => \*(Aqpoints\*(Aq, inner($xy, $xy)); \& gplot( with => \*(Aqimage\*(Aq, sin(rvals(51,51)) ); .Ve .PP 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. .PP \&\f(CW\*(C`PDL::Graphics::Gnuplot\*(C'\fR 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, \&\f(CW\*(C`plot($a,$b)\*(C'\fR will plot \f(CW$b\fR vs. \f(CW$a\fR. If you actually want to plot an overlay of both \f(CW$a\fR and \f(CW$b\fR against array index, you want \&\f(CW\*(C`plot($a,{},$b)\*(C'\fR instead. The \f(CW\*(C`{}\*(C'\fR 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. .SS "Images" .IX Subsection "Images" PDL::Graphics::Gnuplot supports four styles of image plot, via the \*(L"with\*(R" curve option. .PP The \*(L"image\*(R" 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) \s-1PDL\s0 it is treated as an \s-1RGB\s0 image and displayed with the \&\*(L"rgbimage\*(R" 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 \*(L"image\*(R" method: .PP .Vb 4 \& use PDL::Graphics::Gnuplot qw/image gplot/; \& $im = sin(rvals(51,51)/2); \& image( $im ); # display the image \& gplot( with=>\*(Aqimage\*(Aq, $im ); # display the image (longer form) .Ve .PP The colors are autoscaled in both cases. To set a particular color range, use the 'cbrange' plot option: .PP .Vb 1 \& image( {cbrange=>[0,1]}, $im ); .Ve .PP You can plot rgb images directly with the image style, just by including a 3rd dimension of size 3 on your image: .PP .Vb 3 \& $rgbim = pdl( xvals($im), yvals($im),rvals($im)/sqrt(2)); \& image( $rgbim ); # display an RGB image \& gplot( with=>\*(Aqimage\*(Aq, $rgbim ); # display an RGB image (longer form) .Ve .PP Some additional plot styles exist to specify \s-1RGB\s0 and \s-1RGB\s0 transparent forms directly. These are the \*(L"with\*(R" styles \*(L"rgbimage\*(R" and \*(L"rgbalpha\*(R". For each of them you must specify the channels as separate PDLs: .PP .Vb 2 \& gplot( with=>\*(Aqrgbimage\*(Aq, $rgbim\->dog ); # RGB the long way \& gplot( with=>\*(Aqrgbalpha\*(Aq, $rgbim\->dog, 255*($im>0) ); # RGBA the long way .Ve .PP According to the gnuplot specification you can also give X and Y values for each pixel, as in .PP .Vb 1 \& gplot( with=>\*(Aqimage\*(Aq, xvals($im), yvals($im), $im ) .Ve .PP but this appears not to work properly for anything more complicated than a trivial matrix of X and Y values. .PP PDL::Graphics::Gnuplot provides a \*(L"fits\*(R" plot style that interprets World Coordinate System (\s-1WCS\s0) information supplied in the header of the scientific image format \s-1FITS.\s0 The image is displayed in rectified scientific coordinates, rather than in pixel coordinates. You can plot \&\s-1FITS\s0 images in scientific coordinates with .PP .Vb 1 \& gplot( with=>\*(Aqfits\*(Aq, $fitsdata ); .Ve .PP The fits plot style accepts a modifier \*(L"resample\*(R" (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 \s-1WCS\s0 transformations in their headers. (gnuplot itself has a bug that prevents direct rendering of images in nonlinear coordinates). .PP .Vb 2 \& gplot( with=>\*(Aqfits res 200\*(Aq, $fitsdata ); \& gplot( with=>\*(Aqfits res 100,400\*(Aq,$fitsdata ); .Ve .PP 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. .SS "Interactivity" .IX Subsection "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 \f(CW\*(C`wxt\*(C'\fR) are persistently interactive. Other terminals (such as \f(CW\*(C`x11\*(C'\fR) 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. .PP Some interactive devices (notably \f(CW\*(C`wxt\*(C'\fR and \f(CW\*(C`x11\*(C'\fR) also support mouse input: you can write \s-1PDL\s0 scripts that accept and manipulate graphical input from the plotted window. .SH "PLOT OPTIONS" .IX Header "PLOT OPTIONS" Gnuplot controls plot style with \*(L"plot options\*(R" 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 \&\f(CW\*(C`options\*(C'\fR method, or to the \f(CW\*(C`plot\*(C'\fR method itself. .PP Nearly all the underlying Gnuplot plot options are supported, as well as some additional options that are parsed by the module itself for convenience. .PP There are many, many plot options. For convenience, we've grouped them by general category below. Each group has a heading \*(L"POs for \*(R", describing the category. You can skip below them all if you want to read about curve options or other aspects of PDL::Graphics::Gnuplot. .SS "POs for Output: terminal, termoption, output, device, hardcopy" .IX Subsection "POs for Output: terminal, termoption, output, device, hardcopy" You can send plots to a variety of different devices; Gnuplot calls devices \*(L"terminals\*(R". With the object-oriented interface, you must set the output device with the constructor \f(CW\*(C`PDL::Graphics::Gnuplot::new\*(C'\fR (or the exported constructor \f(CW\*(C`gpwin\*(C'\fR) or the \f(CW\*(C`output\*(C'\fR method. If you use the simple non-object interface, you can set the output with the \&\f(CW\*(C`terminal\*(C'\fR, \f(CW\*(C`termoption\*(C'\fR, and \f(CW\*(C`output\*(C'\fR plot options. .PP \&\f(CW\*(C`terminal\*(C'\fR sets the output device type for Gnuplot, and \f(CW\*(C`output\*(C'\fR sets the actual output file or window number. .PP \&\f(CW\*(C`device\*(C'\fR and \f(CW\*(C`hardcopy\*(C'\fR are for convenience. \f(CW\*(C`device\*(C'\fR offers a PGPLOT-style device specifier in \*(L"filename/device\*(R" format (the \*(L"filename\*(R" gets sent to the \*(L"output\*(R" option, the \*(L"device\*(R" gets sent to the \*(L"terminal\*(R" option). \f(CW\*(C`hardcopy\*(C'\fR takes an output file name, attempts to parse out a file suffix and infer a device type. \f(CW\*(C`hardcopy\*(C'\fR also uses a common set of terminal options needed to fill an entire letter page with a plot. .PP For finer grained control of the plotting environment, you can send \&\*(L"terminal options\*(R" to Gnuplot. If you set the terminal directly with plot options, you can include terminal options by interpolating them into a string, as in \f(CW\*(C`terminal jpeg interlace butt crop\*(C'\fR, or you can use the constructor \f(CW\*(C`new\*(C'\fR (also exported as \f(CW\*(C`gpwin\*(C'\fR), which parses terminal options as an argument list. .PP The routine \f(CW\*(C`PDL::Graphics::Gnuplot::terminfo\*(C'\fR prints a list of all available terminals or, if you pass in a terminal name, options accepted by that terminal. .SS "POs for Titles" .IX Subsection "POs for Titles" The options described here are .IP "title" 4 .IX Item "title" .PD 0 .IP "xlabel" 4 .IX Item "xlabel" .IP "x2label" 4 .IX Item "x2label" .IP "ylabel" 4 .IX Item "ylabel" .IP "y2label" 4 .IX Item "y2label" .IP "zlabel" 4 .IX Item "zlabel" .IP "cblabel" 4 .IX Item "cblabel" .IP "key" 4 .IX Item "key" .PD .PP Gnuplot supports \*(L"enhanced\*(R" text escapes on most terminals; see \*(L"text\*(R", below. .PP The \f(CW\*(C`title\*(C'\fR option lets you set a title for the whole plot. .PP Individual plot components are labeled with the \f(CW\*(C`label\*(C'\fR options. \&\f(CW\*(C`xlabel\*(C'\fR, \f(CW\*(C`x2label\*(C'\fR, \f(CW\*(C`ylabel\*(C'\fR, and \f(CW\*(C`y2label\*(C'\fR specify axis titles for 2\-D plots. The \f(CW\*(C`zlabel\*(C'\fR works for 3\-D plots. The \f(CW\*(C`cblabel\*(C'\fR option sets the label for the color box, in plot types that have one (e.g. image display). .PP (Don't be confused by \f(CW\*(C`clabel\*(C'\fR, which doesn't set a label at all, rather specifies the printf format used by contour labels in contour plots.) .PP \&\f(CW\*(C`key\*(C'\fR 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 a list ref containing any of the following arguments (all are optional) in the order listed: .IP "\(bu" 3 ( on | off ) \- turn the key on or off .IP "\(bu" 3 ( inside | outside | lmargin | rmargin | tmargin | bmargin | at ) .Sp These keywords set the location of the key \*(-- \*(L"inside/outside\*(R" is relative to the plot border; the margin keywords indicate location in the margins of the plot; and at (where is a comma-delimited string containing (x,y): \f(CW\*(C`key=>[at=>"0.5,0.5"]\*(C'\fR) is an exact location to place the key. .IP "\(bu" 3 ( left | right | center ) ( top | bottom | center ) \- horiz./vert. alignment .IP "\(bu" 3 ( vertical | horizontal ) \- stacking direction within the key .IP "\(bu" 3 ( Left | Right ) \- justification of plot labels within the key (note case) .IP "\(bu" 3 [no]reverse \- switch order of label and sample line .IP "\(bu" 3 [no]invert \- invert the stack order of the labels .IP "\(bu" 3 samplen \- set the length of the sample lines .IP "\(bu" 3 spacing \- set the spacing between adjacent labels in the list .IP "\(bu" 3 [no]autotitle \- control whether labels are generated when not specified .IP "\(bu" 3 title \*(L"\*(R" \- set a title for the key .IP "\(bu" 3 [no]enhanced \- override terminal settings for enhanced text interpretation .IP "\(bu" 3 font \*(L",\*(R" \- set font for the labels .IP "\(bu" 3 textcolor .IP "\(bu" 3 [no]box linestyle linetype linewidth \- control box around the key .SS "POs for axes, grids, & borders" .IX Subsection "POs for axes, grids, & borders" The options described here are .IP "grid" 4 .IX Item "grid" .PD 0 .IP "xzeroaxis" 4 .IX Item "xzeroaxis" .IP "x2zeroaxis" 4 .IX Item "x2zeroaxis" .IP "yzeroaxis" 4 .IX Item "yzeroaxis" .IP "y2zeroaxis" 4 .IX Item "y2zeroaxis" .IP "zzeroaxis" 4 .IX Item "zzeroaxis" .IP "border" 4 .IX Item "border" .PD .PP 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. .PP The \f(CW\*(C`border\*(C'\fR 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. .IP "\(bu" 3 \- packed bit flags for which border lines to draw .Sp The default if you set a true value for \f(CW\*(C`border\*(C'\fR 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 \s-1LSB\s0 to \s-1MSB,\s0 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. .Sp 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. .IP "\(bu" 3 ( back | front ) \- draw borders first or last (controls hidden line appearance) .IP "\(bu" 3 linewidth , linestyle , linetype .Sp These are Gnuplot's usual three options for line control. .PP The \f(CW\*(C`grid\*(C'\fR option indicates whether gridlines should be drawn on each axis. It takes a list ref of arguments, each of which is either \*(L"no\*(R" or \*(L"m\*(R" or "\*(L", followed by an axis name and \*(R"tics" \*(-- e.g. \f(CW\*(C`grid=>["noxtics","ymtics"]\*(C'\fR draws no X gridlines and draws (horizontal) Y gridlines on Y axis major and minor tics, while \&\f(CW\*(C`grid=>["xtics","ytics"]\*(C'\fR or \f(CW\*(C`grid=>["xtics ytics"]\*(C'\fR will draw both vertical (X) and horizontal (Y) grid lines on major tics. .PP vTo draw a coordinate grid with default values, set \f(CW\*(C`grid=>1\*(C'\fR. For more control, feed in a list ref with zero or more of the following parameters, in order: .PP The \f(CW\*(C`zeroaxis\*(C'\fR 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 \f(CW\*(C`xzeroaxis=>1\*(C'\fR. 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 a list ref containing linewidth, linestyle, and linetype (with appropriate parameters for each), e.g. \f(CW\*(C`xzeroaxis=>[linewidth=>2]\*(C'\fR. .SS "POs for axis range and mode" .IX Subsection "POs for axis range and mode" The options described here are .IP "xrange" 4 .IX Item "xrange" .PD 0 .IP "x2range" 4 .IX Item "x2range" .IP "yrange" 4 .IX Item "yrange" .IP "y2range" 4 .IX Item "y2range" .IP "zrange" 4 .IX Item "zrange" .IP "rrange" 4 .IX Item "rrange" .IP "cbrange" 4 .IX Item "cbrange" .IP "trange" 4 .IX Item "trange" .IP "urange" 4 .IX Item "urange" .IP "vrange" 4 .IX Item "vrange" .IP "autoscale" 4 .IX Item "autoscale" .IP "logscale" 4 .IX Item "logscale" .PD .PP Gnuplot accepts explicit ranges as plot options for all axes. Each option accepts a list 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 \*(L"color\*(R", below). .PP \&\f(CW\*(C`rrange\*(C'\fR is used for radial coordinates (which are accessible using the \f(CW\*(C`mapping\*(C'\fR plot option, below). .PP \&\f(CW\*(C`cbrange\*(C'\fR (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. .PP \&\f(CW\*(C`trange\*(C'\fR, \f(CW\*(C`urange\*(C'\fR, and \f(CW\*(C`vrange\*(C'\fR set ranges for the parametric coordinates if you are plotting a parametric curve. .PP 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. \f(CW\*(C`autoscale\*(C'\fR 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 \&\*(L"fix\*(R", \*(L"min\*(R", \*(L"max\*(R", \*(L"fixmin\*(R", or \*(L"fixmax\*(R". You can set all the axes at once by setting the keyword name to ' '. Examples: .PP .Vb 1 \& autoscale=>{x=>\*(Aqmax\*(Aq,y=>\*(Aqfix\*(Aq}; .Ve .PP There is an older list ref syntax which is deprecated but still accepted. .PP 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). .PP \&\f(CW\*(C`logscale\*(C'\fR allows you to turn on logarithmic scaling for any or all axes, and to set the base of the logarithm. It takes a list 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: \f(CW\*(C`logscale=>[xy=>10]\*(C'\fR. You can also leave off the base if you want base\-10 logs: \f(CW\*(C`logscale=>[\*(Aqxy\*(Aq]\*(C'\fR. .SS "POs for Axis tick marks" .IX Subsection "POs for Axis tick marks" The options described here are .IP "xtics" 4 .IX Item "xtics" .PD 0 .IP "x2tics" 4 .IX Item "x2tics" .IP "ytics" 4 .IX Item "ytics" .IP "y2tics" 4 .IX Item "y2tics" .IP "ztics" 4 .IX Item "ztics" .IP "cbtics" 4 .IX Item "cbtics" .IP "mxtics" 4 .IX Item "mxtics" .IP "mx2tics" 4 .IX Item "mx2tics" .IP "mytics" 4 .IX Item "mytics" .IP "my2tics" 4 .IX Item "my2tics" .IP "mztics" 4 .IX Item "mztics" .IP "mcbtics" 4 .IX Item "mcbtics" .PD .PP Axis tick marks are called \*(L"tics\*(R" within Gnuplot, and they are extensively controllable via the \*(L"{axis}tics\*(R" 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 \f(CW\*(C`POs for time data values\*(C'\fR below). .PP 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. \f(CW\*(C`xtics=>0\*(C'\fR). 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. \f(CW\*(C`xtics=>2\*(C'\fR 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. \f(CW\*(C`xtics=>{}\*(C'\fR), or a string containing only whitespace (e.g. \f(CW\*(C`xtics=>\*(Aq \*(Aq\*(C'\fR). .PP 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). .PP 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 \f(CW\*(C`PDL:Graphics::Gnuplot\*(C'\fR. .PP The keywords are case-insensitive and may be abbreviated, just as with other option types. They are: .IP "\(bu" 2 axis \- set to 1 to place tics on the axis (the default) .IP "\(bu" 2 border \- set to 1 to place tics on the border (not the default) .IP "\(bu" 2 mirror \- set to 1 to place mirrored tics on the opposite axis/border (the default, unless an alternate axis interferes \*(-- e.g. y2) .IP "\(bu" 2 in \- set to 1 to draw tics inward from the axis/border .IP "\(bu" 2 out \- set to 1 to draw tics outward from the axis/border .IP "\(bu" 2 scale \- multiplier on tic length compared to the default .Sp 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. .IP "\(bu" 2 rotate \- turn label text by the given angle (in degrees) on the drawing plane .IP "\(bu" 2 offset \- offset label text from default position, (units: characters; requires array ref containing x,y) .IP "\(bu" 2 locations \- sets tic locations. Gets an array ref: [incr], [start, incr], or [start, incr, stop]. .IP "\(bu" 2 labels \- sets tic locations explicitly, with text labels for each. If you specify both \f(CW\*(C`locations\*(C'\fR and \f(CW\*(C`labels\*(C'\fR, you get both sets of tics on the same axis. .Sp The labels should be a nested list ref that is a collection of duals or triplets. Each dual or triplet should contain [label, position, minorflag], as in \f(CW\*(C`labels=>[["one",1,0],["three\-halves",1.5,1],["two",2,0]]\*(C'\fR. .IP "\(bu" 2 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 \f(CW%h\fR, which works like \f(CW%g\fR but uses extended text formatting if it is available. .IP "\(bu" 2 font \- set font name and size (system font name) .IP "\(bu" 2 rangelimited \- set to 1 to limit tics to the range of values actually present in the plot .IP "\(bu" 2 textcolor \- set the color of the tick labels (see \*(L"Color specification\*(R") .PP For example, to turn on inward mirrored X axis ticks with diagonal Arial 9 text, use: .PP .Vb 1 \& xtics => {axis=>1,mirror=>1,in=>1,rotate=>45,font=>\*(AqArial,9\*(Aq} .Ve .PP or .PP .Vb 1 \& xtics => [\*(Aqaxis\*(Aq,\*(Aqmirror\*(Aq,\*(Aqin\*(Aq,\*(Aqrotate by 45\*(Aq,\*(Aqfont "Arial,9"\*(Aq] .Ve .SS "POs for time data values" .IX Subsection "POs for time data values" The options described here are .IP "xmtics" 4 .IX Item "xmtics" .PD 0 .IP "x2mtics" 4 .IX Item "x2mtics" .IP "ymtics" 4 .IX Item "ymtics" .IP "y2mtics" 4 .IX Item "y2mtics" .IP "zmtics" 4 .IX Item "zmtics" .IP "cbmtics" 4 .IX Item "cbmtics" .IP "xdtics" 4 .IX Item "xdtics" .IP "x2dtics" 4 .IX Item "x2dtics" .IP "ydtics" 4 .IX Item "ydtics" .IP "y2dtics" 4 .IX Item "y2dtics" .IP "zdtics" 4 .IX Item "zdtics" .IP "cbdtics" 4 .IX Item "cbdtics" .IP "xdata" 4 .IX Item "xdata" .IP "x2data" 4 .IX Item "x2data" .IP "ydata" 4 .IX Item "ydata" .IP "y2data" 4 .IX Item "y2data" .IP "zdata" 4 .IX Item "zdata" .IP "cbdata" 4 .IX Item "cbdata" .PD .PP 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). .IP "\fBPlotting timestamps using \s-1UNIX\s0 times\fR" 3 .IX Item "Plotting timestamps using UNIX times" You can set any axis to plot timestamps rather than numeric values by setting the corresponding \*(L"data\*(R" plot option to \*(L"time\*(R", e.g. \f(CW\*(C`xdata=>"time"\*(C'\fR. If you do so, then numeric values in the corresponding data are interpreted as \s-1UNIX\s0 time (seconds since the \&\s-1UNIX\s0 epoch, neglecting leap seconds). No provision is made for \&\s-1UT\s0\f(CW\*(C`\-\*(C'\fR\s-1TAI\s0 conversion. You can format how the times are plotted with the \*(L"format\*(R" option in the various \*(L"tics\*(R" options(above). Output specifiers should be in \s-1UNIX\s0 \fBstrftime\fR\|(3) format \*(-- for example, \&\f(CW\*(C`xdata=>"time",xtics=>{format=>"%Y\-%b\-%dT%H:%M:%S"}\*(C'\fR will plot \s-1UNIX\s0 times as \s-1ISO\s0 timestamps in the ordinate. .Sp Due to limitations within gnuplot, the time resolution in this mode is limited to 1 second \- if you want fractional seconds, you must use numerically formatted times (and/or create your own tick labels using the \f(CW\*(C`labels\*(C'\fR suboption to the \f(CW\*(C`?tics\*(C'\fR option. .Sp \&\fBTimestamp format specifiers\fR .Sp Time format specifiers use the following printf-like codes: .RS 3 .IP "\(bu" 3 \&\fBYear A.D.\fR: \f(CW%Y\fR is 4\-digit year; \f(CW%y\fR is 2\-digit year (1969\-2068) .IP "\(bu" 3 \&\fBMonth of year\fR: \f(CW%m\fR: 01\-12; \f(CW%b\fR or \f(CW%h\fR: abrev. name; \f(CW%B\fR: full name .IP "\(bu" 3 \&\fBWeek of year\fR: \f(CW%W\fR (week starting Monday); \f(CW%U\fR (week starting Sunday) .IP "\(bu" 3 \&\fBDay of year\fR: \f(CW%j\fR (1\-366; boundary is midnight) .IP "\(bu" 3 \&\fBDay of month\fR: \f(CW%d\fR (01\-31) .IP "\(bu" 3 \&\fBDay of week\fR: \f(CW%w\fR (0\-6, Sunday=0), \f(CW%a\fR (abrev. name), \f(CW%A\fR (full name) .IP "\(bu" 3 \&\fBHour of day\fR: \f(CW%k\fR (0\-23); \f(CW%H\fR (00\-23); \f(CW%l\fR (1\-12); \f(CW%I\fR (01\-12) .IP "\(bu" 3 \&\fBAm/pm\fR: \f(CW%p\fR (\*(L"am\*(R" or \*(L"pm\*(R") .IP "\(bu" 3 \&\fBMinute of hour\fR: \f(CW%M\fR (00\-60) .IP "\(bu" 3 \&\fBSecond of minute\fR: \f(CW%S\fR (0\-60) .IP "\(bu" 3 \&\fBTotal seconds since start of 2000 A.D.\fR: \f(CW%s\fR .IP "\(bu" 3 \&\fBTimestamps\fR: \f(CW%T\fR (same as \f(CW\*(C`%H:%M:%S\*(C'\fR); \f(CW%R\fR (same as \f(CW\*(C`%H:%M\*(C'\fR); \f(CW%r\fR (same as \f(CW\*(C`%I:%M:%S %p\*(C'\fR) .IP "\(bu" 3 \&\fBDatestamps\fR: \f(CW%D\fR (same as \f(CW\*(C`%m/%d/%y\*(C'\fR); \f(CW%F\fR (same as \f(CW\*(C`%Y\-%m\-%d\*(C'\fR) .IP "\(bu" 3 \&\fB\s-1ISO\s0 timestamps\fR: use \f(CW\*(C`%DT%T\*(C'\fR. .RE .RS 3 .RE .IP "\fBday-of-week plotting\fR" 3 .IX Item "day-of-week plotting" If you just want to plot named days of the week, you can instead use the \f(CW\*(C`dtics\*(C'\fR options set plotting to day of week, where 0 is Sunday and 6 is Saturday; values are interpreted modulo 7. For example, \f(CW\*(C`xmtics=>1,xrange=>[\-4,9]\*(C'\fR will plot two weeks from Wednesday to Wednesday. As far as output format goes, this is exactly equivalent to using the \f(CW%w\fR option with full formatting \- but you can treat the numeric range in terms of weeks rather than seconds. .IP "\fBmonth-of-year plotting\fR" 3 .IX Item "month-of-year plotting" The \f(CW\*(C`mtics\*(C'\fR options set plotting to months of the year, where 1 is January and 12 is December, so \f(CW\*(C`xdtics=>1, xrange=>[0,4]\*(C'\fR will include Christmas through Easter. This is exactly equivalent to using the \f(CW%d\fR option with full formatting \- but you can treat the numeric range in terms of months rather than seconds. .SS "POs for location/size" .IX Subsection "POs for location/size" The options described here are .IP "tmargin" 4 .IX Item "tmargin" .PD 0 .IP "bmargin" 4 .IX Item "bmargin" .IP "lmargin" 4 .IX Item "lmargin" .IP "rmargin" 4 .IX Item "rmargin" .IP "offsets" 4 .IX Item "offsets" .IP "origin" 4 .IX Item "origin" .IP "size" 4 .IX Item "size" .IP "justify" 4 .IX Item "justify" .IP "clip" 4 .IX Item "clip" .PD .PP Adjusting the size, location, and margins of the plot on the plotting surface is something of a null operation for most single plots \*(-- but you can tweak the placement and size of the plot with these options. That is particularly useful for multiplots, where you might like to make an inset plot or to lay out a set of plots in a custom way. .PP The margin options accept scalar values \*(-- either a positive number of character heights or widths of margin around the plot compared to the edge of the device window, or a string that starts with \*(L"at screen \*(R" and interpolates a number containing the fraction of the plot window offset. The \*(L"at screen\*(R" technique allows exact plot placement and is an alternative to the \f(CW\*(C`origin\*(C'\fR and \f(CW\*(C`size\*(C'\fR options below. .PP The \f(CW\*(C`offsets\*(C'\fR option allows you to put an empty boundary around the data, inside the plot borders, in an autosacaled graph. The offsets only affect the x1 and y1 axes, and only in 2D plot commands. \&\f(CW\*(C`offsets\*(C'\fR accepts a list ref with four values for the offsets, which are given in scientific (plotted) axis units. .PP The \f(CW\*(C`origin\*(C'\fR option lets you specify the origin (lower left corner) of an individual plot on the plotting window. The coordinates are screen coordinates \*(-- i.e. fraction of the total plotting window. .PP The size option lets you adjust the size and aspect ratio of the plot, as an absolute fraction of the plot window size. You feed in fractional ratios, as in \f(CW\*(C`size=>[$xfrac, $yfrac]\*(C'\fR. You can also feed in some keywords to adjust the aspect ratio of the plot. The size option overrides any autoscaling that is done by the auto-layout in multiplot mode, so use with caution \*(-- particularly if you are multiplotting. You can use \&\*(L"size\*(R" to adjust the aspect ratio of a plot, but this is deprecated in favor of the pseudo-option \f(CW\*(C`justify\*(C'\fR. .PP \&\f(CW\*(C`justify\*(C'\fR sets the scientific aspect ratio of a 2\-D plot. Unity yields a plot with a square scientific aspect ratio. Larger numbers yield taller plots. .PP \&\f(CW\*(C`clip\*(C'\fR controls the border between the plotted data and the border of the plot. There are three clip types supported: points, one, and two. You can set them independently by passing in booleans with their names: \f(CW\*(C`clip=>[points=>1,two=>0]\*(C'\fR. .SS "POs for Color: colorbox, palette, clut, pseudocolor, pc, perceptual, pcp" .IX Subsection "POs for Color: colorbox, palette, clut, pseudocolor, pc, perceptual, pcp" Color plots are supported via \s-1RGB\s0 and pseudocolor. Plots that use pseudcolor or grayscale can have a \*(L"color box\*(R" that shows the photometric meaning of the color. .PP The colorbox generally appears when necessary but can be controlled manually with the \f(CW\*(C`colorbox\*(C'\fR option. \f(CW\*(C`colorbox\*(C'\fR accepts a scalar boolean value indicating whether or no to draw a color box, or a list ref containing additional options. The options are all, well, optional but must appear in the order given: .IP "( vertical | horizontal ) \- indicates direction of the gradient in the box" 3 .IX Item "( vertical | horizontal ) - indicates direction of the gradient in the box" .PD 0 .IP "( default | user ) \- indicates user origin and size" 3 .IX Item "( default | user ) - indicates user origin and size" .PD If you specify \f(CW\*(C`default\*(C'\fR the colorbox will be placed on the right-hand side of the plot; if you specify \f(CW\*(C`user\*(C'\fR, you give the location and size in subsequent arguments: .Sp .Vb 1 \& colorbox => [ \*(Aquser\*(Aq, \*(Aqorigin\*(Aq=>"$x,$y", \*(Aqsize\*(Aq => "$x,$y" ] .Ve .IP "( front | back ) \- draws the colorbox before or after the plot" 3 .IX Item "( front | back ) - draws the colorbox before or after the plot" .PD 0 .IP "( noborder | bdefault | border ) \- specify border" 3 .IX Item "( noborder | bdefault | border ) - specify border" .PD The line style is a numeric type as described in the gnuplot manual. .PP The \f(CW\*(C`palette\*(C'\fR option offers many arguments that are not fully documented in this version but are explained in the gnuplot manual. It offers complete control over the pseudocolor mapping function. .PP For simple color maps, \f(CW\*(C`clut\*(C'\fR gives access to a set of named color maps. (from \*(L"Color Look Up Table\*(R"). A few existing color maps are: \&\*(L"default\*(R", \*(L"gray\*(R", \*(L"sepia\*(R", \*(L"ocean\*(R", \*(L"rainbow\*(R", \*(L"heat1\*(R", \*(L"heat2\*(R", and \&\*(L"wheel\*(R". To see a complete list, specify an invalid table, e.g. \f(CW\*(C`clut=>\*(Aqxxx\*(Aq\*(C'\fR. \f(CW\*(C`clut\*(C'\fR is maintained but is superseded by \f(CW\*(C`pc\*(C'\fR and \f(CW\*(C`pcp\*(C'\fR (below), which give access to a better variety of color tables, and have better support for scientific images. .PP \&\f(CW\*(C`pseudocolor\*(C'\fR (synonym \f(CW\*(C`pc\*(C'\fR) gives access to the color tables built in to the \f(CW\*(C`PDL::Transform::Color\*(C'\fR package, if that package is available. It takes either a color table name or a list ref which is a collection of arguments that get sent to the \&\f(CW\*(C`PDL::Transform::Color::t_pc\*(C'\fR transform definition method. Sending the empty string or undef will generate a list of allowable color table names. Many of the color tables are \*(L"photometric\*(R" and will render photometric data correctly without gamma correction. .PP \&\f(CW\*(C`perceptual\*(C'\fR (synonym \f(CW\*(C`pcp\*(C'\fR) gives the same access to \&\f(CW\*(C`PDL::Transform::Color\*(C'\fR as does \f(CW\*(C`pseudocolor\*(C'\fR, but the \&\*(L"equal-perceptual-difference\*(R" scaling is used \*(-- i.e. input values are gamma-corrected by the module so that uniform shifts in numeric value yield approximately uniform perceptual shifts. .PP If you use \f(CW\*(C`pseudocolor\*(C'\fR or \f(CW\*(C`perceptual\*(C'\fR, and if \&\f(CW\*(C`PDL::Transform::Color\*(C'\fR can be loaded, then the external module is used to define a custom Gnuplot palette by linear interpolation across 256 values. That palette is then used to translate your monochrome data to a color image. The Gnuplot output is assumed to be sRGB. This is probably \s-1OK\s0 for most output devices. .SS "POs for 3D: trid, view, pm3d, hidden3d, dgrid3d, surface, xyplane, mapping" .IX Subsection "POs for 3D: trid, view, pm3d, hidden3d, dgrid3d, surface, xyplane, mapping" If \f(CW\*(C`trid\*(C'\fR or its synonym \f(CW\*(C`3d\*(C'\fR is true, Gnuplot renders a 3\-D plot. This changes the default tuple size from 2 to 3. This option is used to switch between the Gnuplot \*(L"plot\*(R" and \*(L"splot\*(R" command, but it is tracked with persistent state just as any other option. .PP The \f(CW\*(C`view\*(C'\fR option controls the viewpoint of the 3\-D plot. It takes a list of numbers: \f(CW\*(C`view=>[$rot_x, $rot_z, $scale, $scale_z]\*(C'\fR. After each number, you can omit the subsequent ones. Alternatively, \&\f(CW\*(C`view=>[\*(Aqmap\*(Aq]\*(C'\fR represents the drawing as a map (e.g. for contour plots) and \f(CW\*(C`view=>[equal=>\*(Aqxy\*(Aq]\*(C'\fR forces equal length scales on the X and Y axes regardless of perspective, while \f(CW\*(C`view=>[equal=>\*(Aqxyz\*(Aq]\*(C'\fR sets equal length scales on all three axes. .PP The \f(CW\*(C`pm3d\*(C'\fR option accepts several parameters to control the pm3d plot style, which is a palette-mapped 3d surface. They are not documented here in this version of the module but are explained in the gnuplot manual. .PP \&\f(CW\*(C`hidden3d\*(C'\fR accepts a list of parameters to control how hidden surfaces are plotted (or not) in 3D. It accepts a boolean argument indicating whether to hide \&\*(L"hidden\*(R" surfaces and lines; or a list ref containing parameters that control how hidden surfaces and lines are handled. For details see the gnuplot manual. .PP \&\f(CW\*(C`xyplane\*(C'\fR sets the location of that plane (which is drawn) relative to the rest of the plot in 3\-space. It takes a single string: \*(L"at\*(R" or \&\*(L"relative\*(R", and a number. \f(CW\*(C`xyplane=>[at=>$z]\*(C'\fR places the \s-1XY\s0 plane at the stated Z value (in scientific units) on the plot. \f(CW\*(C`xyplane=>[relative=>$frac]\*(C'\fR places the \s-1XY\s0 plane \f(CW$frac\fR times the length of the scaled Z axis *below* the Z axis (i.e. 0 places it at the bottom of the plotted Z axis; and \-1 places it at the top of the plotted Z axis). .PP \&\f(CW\*(C`mapping\*(C'\fR takes a single string: \*(L"cartesian\*(R", \*(L"spherical\*(R", or \&\*(L"cylindrical\*(R". It determines the interpretation of data coordinates in 3\-space. (Compare to the \f(CW\*(C`polar\*(C'\fR option in 2\-D). .SS "POs for Contour plots \- contour, cntrparam" .IX Subsection "POs for Contour plots - contour, cntrparam" Contour plots are only implemented in 3D. To make a normal 2D contour plot, use 3\-D mode, but set the view to \*(L"map\*(R" \- which projects the 3\-D plot onto its 2\-D \s-1XY\s0 plane. (This is convoluted, for sure \*(-- future versions of this module may have a cleaner way to do it). .PP \&\f(CW\*(C`contour\*(C'\fR enables contour drawing on surfaces in 3D. It takes a single string, which should be \*(L"base\*(R", \*(L"surface\*(R", or \*(L"both\*(R". .PP \&\f(CW\*(C`cntrparam\*(C'\fR manages how contours are generated and smoothed. It accepts a list ref with a collection of Gnuplot parameters that are issued one per line; refer to the Gnuplot manual for how to operate it. .SS "POs for Polar plots \- polar, angles, mapping" .IX Subsection "POs for Polar plots - polar, angles, mapping" You can make 2\-D polar plots by setting \f(CW\*(C`polar\*(C'\fR to a true value. The ordinate is then plotted as angle, and the abscissa is radius on the plot. The ordinate can be in either radians or degrees, depending on the \&\f(CW\*(C`angles\*(C'\fR parameter .PP \&\f(CW\*(C`angles\*(C'\fR takes either \*(L"degrees\*(R" or \*(L"radians\*(R" (default is radians). .PP \&\f(CW\*(C`mapping\*(C'\fR is used to set 3\-D polar plots, either cylindrical or spherical (see the section on 3\-D plotting, above). .SS "POs for Markup \- label, arrow, object" .IX Subsection "POs for Markup - label, arrow, object" You specify plot markup in advance of the plot command, with plot options (or add it later with the \f(CW\*(C`replot\*(C'\fR method). The options give you access to a collection of (separately) numbered descriptions that are accumulated into the plot object. To add a markup object to the next plot, supply the appropriate options as a list ref or as a single string. To specify all markup objects at once, supply the appropriate options for all of them as a nested list-of-lists. .PP To modify an object, you can specify it by number, either by appending the number to the plot option name (e.g. \f(CW\*(C`arrow3\*(C'\fR) or by supplying it as the first element of the option list for that object. .PP To remove all objects of a given type, supply undef (e.g. \f(CW\*(C`arrow=>undef\*(C'\fR). .PP For example, to place two labels, use the plot option: .PP .Vb 1 \& label => [["Upper left",at=>"10,10"],["lower right",at=>"20,5"]]; .Ve .PP To add a label to an existing plot object, if you don't care about what index number it gets, do this: .PP .Vb 1 \& $w\->options( label=>["my new label",at=>[10,20]] ); .Ve .PP If you do care what index number it gets (or want to replace an existing label), do this: .PP .Vb 1 \& $w\->options( label=>[$n, "my replacement label", at=>"10,20"] ); .Ve .PP where \f(CW$w\fR is a Gnuplot object and \f(CW$n\fR contains the label number you care about. .PP \fIlabel \- add a text label to the plot.\fR .IX Subsection "label - add a text label to the plot." .PP The \f(CW\*(C`label\*(C'\fR option allows adding small bits of text at arbitrary locations on the plot. .PP Each label specifier list ref accepts the following suboptions, in order. All of them are optional \*(-- if no options other than the index tag are given, then any existing label with that index is deleted. .PP For examples, please refer to the Gnuplot 4.4 manual, p. 117. .IP " \- optional index number (integer)" 3 .IX Item " - optional index number (integer)" .PD 0 .IP "