{"id":20011287,"url":"https://github.com/pdlporters/pdl-graphics-gnuplot","last_synced_at":"2025-05-04T20:31:01.171Z","repository":{"id":43897938,"uuid":"2966669","full_name":"PDLPorters/PDL-Graphics-Gnuplot","owner":"PDLPorters","description":"Gnuplot-based plotting backend for PDL","archived":false,"fork":false,"pushed_at":"2024-11-21T17:42:57.000Z","size":1548,"stargazers_count":8,"open_issues_count":6,"forks_count":8,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-08T12:01:45.526Z","etag":null,"topics":["gnuplot","pdl","perl","plotting"],"latest_commit_sha":null,"homepage":"https://p3rl.org/PDL::Graphics::Gnuplot","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"dkogan/PDL-Graphics-Gnuplot","license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PDLPorters.png","metadata":{"files":{"readme":"README.pod","changelog":"CHANGES","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2011-12-12T19:10:04.000Z","updated_at":"2024-11-21T17:43:01.000Z","dependencies_parsed_at":"2024-05-07T00:25:45.254Z","dependency_job_id":"4f754354-8df4-44ef-b82a-9fb8d7214557","html_url":"https://github.com/PDLPorters/PDL-Graphics-Gnuplot","commit_stats":{"total_commits":655,"total_committers":27,"mean_commits":24.25925925925926,"dds":0.665648854961832,"last_synced_commit":"636e6d7dbbd14b6b7cacb776d48ec37fe6adec37"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PDLPorters%2FPDL-Graphics-Gnuplot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PDLPorters%2FPDL-Graphics-Gnuplot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PDLPorters%2FPDL-Graphics-Gnuplot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PDLPorters%2FPDL-Graphics-Gnuplot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PDLPorters","download_url":"https://codeload.github.com/PDLPorters/PDL-Graphics-Gnuplot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252395219,"owners_count":21740988,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gnuplot","pdl","perl","plotting"],"created_at":"2024-11-13T07:25:09.535Z","updated_at":"2025-05-04T20:31:01.151Z","avatar_url":"https://github.com/PDLPorters.png","language":"Perl","readme":"=head1 OVERVIEW\n\nThis is a Gnuplot-based plotter for PDL. This repository stores the history for\nthe PDL::Graphics::Gnuplot module on CPAN. Install the module via CPAN. CPAN\npage at L\u003chttp://metacpan.org/pod/PDL::Graphics::Gnuplot\u003e.\n\n=cut\n\n=encoding UTF-8\n\n=head1 NAME\n\nPDL::Graphics::Gnuplot - Gnuplot-based plotting for PDL\n\n=head1 SYNOPSIS\n\n pdl\u003e use PDL::Graphics::Gnuplot;\n\n pdl\u003e $x = sequence(101) - 50;\n pdl\u003e gplot($x**2);\n pdl\u003e gplot($x**2,{xr=\u003e[0,50]});\n\n pdl\u003e gplot( {title =\u003e 'Parabola with error bars'},\n       with =\u003e 'xyerrorbars', legend =\u003e 'Parabola',\n       $x**2 * 10, abs($x)/10, abs($x)*5 );\n\n pdl\u003e $xy = zeroes(21,21)-\u003endcoords - pdl(10,10);\n pdl\u003e $z = inner($xy, $xy);\n pdl\u003e gplot({title  =\u003e 'Heat map',\n             trid   =\u003e 1,\n             view   =\u003e [0,0]\n            },\n            with =\u003e 'image', xvals($z),yvals($z),zeroes($z),$z*2\n           );\n\n pdl\u003e $w = gpwin();                             # constructor\n pdl\u003e $pi    = 3.14159;\n pdl\u003e $theta = zeroes(200)-\u003exlinvals(0, 6*$pi);\n pdl\u003e $z     = zeroes(200)-\u003exlinvals(0, 5);\n pdl\u003e $w-\u003eplot3d(cos($theta), sin($theta), $z);\n pdl\u003e $w-\u003eterminfo();                           # get information\n\n\n=head1 DESCRIPTION\n\nThis module allows PDL data to be plotted using Gnuplot as a backend\nfor 2D and 3D plotting and image display.  Gnuplot (not affiliated\nwith the GNU project) is a venerable, open-source program that\nproduces both interactive and publication-quality plots on many\ndifferent output devices.  It is available through most Linux\nrepositories, on MacOS, and from its website\nL\u003chttp://www.gnuplot.info\u003e.\n\nIt is not necessary to understand the gnuplot syntax to generate\nbasic, or even complex, plots - though the full syntax is available\nfor advanced users who want the full flexibility of the Gnuplot\nbackend.\n\nFor a very quick demonstration of the power of this module, see\nL\u003cthis YouTube demo video|https://www.youtube.com/watch?v=hUXDQL3rZ_0\u003e,\nand others on visualisation of\nL\u003ctesseract assembly|https://www.youtube.com/watch?v=ykQmNrSKqGQ\u003e and\nL\u003crotation|https://www.youtube.com/watch?v=6tpsPYBrHy0\u003e.\n\nGnuplot recognizes both hard-copy and interactive plotting devices,\nand on interactive devices (like X11) it is possible to pan, scale,\nand rotate both 2-D and 3-D plots interactively.  You can also enter\ngraphical data through mouse clicks on the device window.  On some\nhardcopy devices (e.g. \"PDF\") that support multipage output, it is\nnecessary to close the device after plotting to ensure a valid file is\nwritten out.\n\nC\u003cPDL::Graphics::Gnuplot\u003e exports two routines by default: a\nconstructor, C\u003cgpwin()\u003e and a general purpose plot routine,\nC\u003cgplot()\u003e.  Depending on options, C\u003cgplot()\u003e can produce line plots,\nscatterplots, error boxes, \"candlesticks\", images, or any overlain\ncombination of these elements; or perspective views of 3-D renderings\nsuch as surface plots.\n\nA call to C\u003cgplot()\u003e looks like:\n\n gplot({temp_plot_options}, # optional hash ref\n      curve_options, data, data, ... ,\n      curve_options, data, data, ... );\n\nThe data entries are columns to be plotted.  They are normally\nan optional ordinate and a required abscissa, but some plot modes\ncan use more columns than that.  The collection of columns is called\na \"tuple\".  Each column must be a separate PDL or an ARRAY ref.  If\nall the columns are PDLs, you can add extra dimensions to make threaded\ncollections of curves.\n\nPDL::Graphics::Gnuplot also implements an object oriented\ninterface. Plot objects track individual gnuplot subprocesses.  Direct\ncalls to C\u003cgplot()\u003e are tracked through a global object that stores\nglobally set configuration variables.\n\nThe C\u003cgplot()\u003e sub (or the C\u003cplot()\u003e method) collects two kinds of\noptions hash: B\u003cplot options\u003e, which describe the overall structure of\nthe plot being produced (e.g. axis specifications, window size, and\ntitle), and B\u003ccurve options\u003e, which describe the behavior of\nindividual traces or collections of points being plotted.  In\naddition, the module itself supports options that allow direct\npass-through of plotting commands to the underlying gnuplot process.\n\n=head2 Basic plotting\n\nGnuplot generates many kinds of plot, from basic line plots and histograms\nto scaled labels.  Individual plots can be 2-D or 3-D, and different sets\nof plot styles are supported in each mode.  Plots can be sent to a variety\nof devices; see the description of plot options, below.\n\nYou can specify what type of graphics output you want, but in most cases\ndoing nothing will cause a plot to be rendered on your screen: with\nX windows on UNIX or Linux systems, with an XQuartz window on MacOS,\nor with a native window on Microsoft Windows.\n\nYou select a plot style with the \"with\" curve option, and feed in columns\nof data (usually ordinate followed by abscissa).  The collection of columns\nis called a \"tuple\".  These plots have two columns in their tuples:\n\n $x = xvals(51)-25; $y = $x**2;\n gplot(with=\u003e'points', $x, $y);  # Draw points on a parabola\n gplot(with=\u003e'lines', $x, $y);   # Draw a parabola\n gplot({title=\u003e\"Parabolic fit\"},\n       with=\u003e\"yerrorbars\", legend=\u003e\"data\", $x, $y+(random($y)-0.5)*2*$y/20, pdl($y/20),\n       with=\u003e\"lines\",      legend=\u003e\"fit\",  $x, $y);\n\nNormal threading rules apply across the arguments to a given plot.\n\nAll data are required to be supplied as either PDLs or array refs.\nIf you use an array ref as a data column, then normal\nthreading is disabled.  For example:\n\n $x = xvals(5);\n $y = xvals(5)**2;\n $labels = ['one','two','three','four','five'];\n gplot(with=\u003e'labels',$x,$y,$labels);\n\nSee below for supported curve styles.\n\n=head3 Modifying plots\n\nGnuplot is built around a monolithic plot model - it is not possible to\nadd new data directly to a plot without redrawing the entire plot. To support\nreplotting, PDL::Graphics::Gnuplot stores the data you plot in the plot object,\nso that you can add new data with the \"replot\" command:\n\n $w=gpwin(x11);\n $x=xvals(101)/100;\n $y=$x;\n $w-\u003eplot($x,$y);\n $w-\u003ereplot($x,$y*$y);\n\nFor speed, the data are *not* disconnected from their original variables - so\nthis will plot X vs. sqrt(X):\n\n $x = xvals(101)/100;\n $y = xvals(101)/100;\n $w-\u003eplot($x,$y);\n $y-\u003einplace-\u003esqrt;\n $w-\u003ereplot();\n\n=head3 Plotting to an image file or device\n\nPDL:Graphics::Gnuplot can plot to most of the devices supported by\ngnuplot itself.  You can specify the file type with the \"output\"\nmethod or the object constructor \"gplot\".  Either one will allow you\nto name a type of file to produce, and a collection of options speciic to\nthat type of output file.\n\n=head3 Image plotting\n\nSeveral of the plot styles accept image data.  The tuple parameters work the\nsame way as for basic plots, but each \"column\" is a 2-D PDL rather than a 1-D PDL.\nAs a special case, the \"with image\" plot style accepts either a 2-D or a 3-D PDL.\nIf you pass in 3-D PDL, the extra dimension can have size 1, 3, or 4.  It is interpreted\nas running across (R,G,B,A) color planes.\n\n=head3 3-D plotting\n\nYou can plot in 3-D by setting the plot option C\u003ctrid\u003e to a true value.  Three\ndimensional plots accept either 1-D or 2-D PDLs as data columns.  If you feed\nin 2-D \"columns\", many of the common plot styles will generalize appropriately\nto 3-D.  For example, to plot a 2-D surface as a line grid, you can use the \"lines\"\nstyle and feed in 2-D columns instead of 1-D columns.\n\n=head2 Enhanced text\n\nMost gnuplot output devices include the option to markup \"enhanced text\". That means\ntext is interpreted so that you can change its font and size, and insert superscripts\nand subscripts into labels.  Codes are:\n\n=over 3\n\n=item {}\n\nText grouping - enclose text in braces to group characters, as in LaTeX.\n\n=item ^\n\nSuperscript the next character or group (shrinks it slightly too where that is supported).\n\n=item _\n\nSubscript the next character or group (shrinks it slightly too where that is supported).\n\n=item @\n\nPhantom box (occupies no width; controls height for super- and subscripting)\n\n=item \u0026\n\nControllable-width space, e.g. \u0026amp;{template-string}\n\n=item ~\n\noverstrike -- e.g. ~a{0.8-} overprints '-' on 'a', raised by 0.8xfontsize.\n\n=item {/[fontname][=fontsize | *fontscale] text}\n\nChange 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.\n\n=item \\\n\nBackslash escapes control characters to render them as themselves.\n\n=back\n\n=head2 Unicode text\n\nSeparately to \"enhanced\" text above, if you wish to include text that\nis not ASCII, then you will need to pass data that has been UTF-8\nencoded. Sample code to achieve this:\n\n  use utf8;\n  use Encode;\n  use PDL;\n  use PDL::Graphics::Gnuplot;\n  use PDL::Constants qw(PI);\n\n  sub plot_sin {\n    my ($w, $coeff) = @_;\n    my $xrange = [ -2*PI, 2*PI ];\n    my $x = zeroes(1e3)-\u003exlinvals(@$xrange); my $y = sin($coeff * 2 * PI * $x);\n    my $title = \"y = sin( $coeff * 2π * x )\";\n    # to get around sending text through syswrite()\n    my $title_octets = encode('UTF-8', $title);\n    $w-\u003eplot(with=\u003e'lines', $x, $y, {\n      xrange =\u003e $xrange,\n      title =\u003e $title_octets, # can not pass $title as-is\n    });\n  }\n\n=head2 Color specification\n\nThere are several contexts where you can specify color of plot elements.  In those\nplaces, you can specify colors exactly as in the Gnuplot manual, or more tersely.\nIn general, a color spec can be any one of the following:\n\n=over 3\n\n=item - an integer\n\nThis specifies a recognizable unique color in the same order as used by the plotting engine.\n\n=item - the name of a color\n\n(e.g. \"blue\").  Supported color names are listed in the variable C\u003c@Alien::Gnuplot::colors\u003e.\n\n=item - an RGB value string\n\nStrings have the form C\u003c#RRGGBB\u003e, where the C\u003c#\u003e is literal and the RR, GG, and BB are hexadecimal bytes.\n\n=item - the word \"palette\"\n\n\"palette\" indicates that color is to be drawn from the scaled colorbar\npalette (which you can set with the \"clut\" plot option), by lookup\nusing an additional column in the associated data tuple.\n\n=item - the word \"variable\"\n\n\"variable\" indicates that color is to be drawn from the integer\nplotting colors used by the plotting engine, indexed by an additional\ncolumn in the associated data tuple.\n\n=item - the phrase \"rgb variable\"\n\n\"rgb variable\" indicates that color is to be directly specified by a\n24 bit integer specifying 8-bit values for (from most significant byte\nto least significant byte) R, G, and B in the output color.  The\ninteger is drawn from an additional column in the associated data tuple.\n\n=back\n\n\n=head2 Plot styles supported\n\nGnuplot itself supports a wide range of plot styles, and all are supported by\nPDL::Graphics::Gnuplot.  Most of the basic plot styles collect tuples of 1-D columns\nin 2-D mode (for ordinary plots), or either 1-D or 2-D \"columns\" in 3-D mode (for\ngrid surface plots and such).  Image modes always collect tuples made of 2-D \"columns\".\n\nYou can pass in 1-D columns as either PDLs or ARRAY refs.  That is important for\nplot types (such as \"labels\") that require a collection of strings rather than\nnumeric data.\n\nEach plot style can by modified to support particular colors or line\nstyle options.  These modifications get passed in as curve options (see\nbelow). For example, to plot a blue line you can use\nC\u003cwith=E\u003cgt\u003e'lines',lc=E\u003cgt\u003e'blue'\u003e.  To match the autogenerated style of a\nparticular line you can use the C\u003cls\u003e curve option.\n\nThe GNuplot plot styles supported are:\n\n=over 3\n\n=item * C\u003cboxerrorbars\u003e - combo of C\u003cboxes\u003e and C\u003cyerrorbars\u003e, below (2D)\n\n=item * C\u003cboxes\u003e - simple boxes around regions on the plot (2D)\n\n=item * C\u003cboxxyerrorbars\u003e - Render X and Y error bars as boxes (2D)\n\n=item * C\u003ccandlesticks\u003e - Y error bars with inner and outer limits (2D)\n\n=item * C\u003ccircles\u003e - circles with variable radius at each point: X/Y/radius (2D)\n\n=item * C\u003cdots\u003e - tiny points (\"dots\") at each point, e.g. for scatterplots (2D/3D)\n\n=item * C\u003cellipses\u003e - ellipses.  Accepts X/Y/major/minor/angle (2D)\n\n=item * C\u003cfilledcurves\u003e - closed polygons or axis-to-line filled shapes (2D)\n\n=item * C\u003cfinancebars\u003e - financial style plot. Accepts date/open/low/high/close (2D)\n\n=item * C\u003cfsteps\u003e - square bin plot; delta-Y, then delta-X (see C\u003csteps\u003e, C\u003chisteps\u003e) (2D)\n\n=item * C\u003chisteps\u003e - square bin plot; plateaus centered on X coords (see C\u003cfsteps\u003e, C\u003csteps\u003e) (2D)\n\n=item * C\u003chistogram\u003e - binned histogram of dataset (not direct plot; see C\u003cnewhistogram\u003e) (2D)\n\n=item * C\u003cfits\u003e - (PDL-specific) renders FITS image files in scientific coordinates\n\n=item * C\u003cimage\u003e - Takes (i), (x,y,i), or (x,y,z,i).  See C\u003crgbimage\u003e, C\u003crgbalpha\u003e, C\u003cfits\u003e. (2D/3D)\n\n=item * C\u003cimpulses\u003e - vertical line from axis to the plotted point (2D/3D)\n\n=item * C\u003clabels\u003e - Text labels at specified locations all over the plot (2D/3D)\n\n=item * C\u003clines\u003e - regular line plot (2D/3D)\n\n=item * C\u003clinespoints\u003e - line plot with symbols at plotted points (2D/3D)\n\n=item * C\u003cnewhistogram\u003e - multiple-histogram-friendly histogram style (see C\u003chistogram\u003e) (2D)\n\n=item * C\u003cpoints\u003e - symbols at plotted points (2D/3D)\n\n=item * C\u003crgbalpha\u003e - R/G/B color image with variable transparency (2D/3D)\n\n=item * C\u003crgbimage\u003e - R/G/B color image (2D/3D)\n\n=item * C\u003csteps\u003e - square bin plot; delta-X, then delta-Y (see C\u003cfsteps\u003e, C\u003chisteps\u003e) (2D)\n\n=item * C\u003cvectors\u003e - Small arrows: (x,y,[z]) -\u003e (x+dx,y+dy,[z+dz]) (2D/3D)\n\n=item * C\u003cxerrorbars\u003e - points with X error bars (\"T\" form) (2D)\n\n=item * C\u003cxyerrorbars\u003e - points with both X and Y error bars (\"T\" form) (2D)\n\n=item * C\u003cyerrorbars\u003e - points with Y error bars (\"T\" form) (2D)\n\n=item * C\u003cxerrorlines\u003e - line plot with X errorbars at each point.  (2D)\n\n=item * C\u003cxyerrorlines\u003e - line plot with XY errorbars at each point. (2D)\n\n=item * C\u003cyerrorlines\u003e - line plot with Y error limits at each point. (2D)\n\n=item * C\u003cpm3d\u003e - three-dimensional variable-position surface plot\n\n=back\n\n=head2 Options arguments\n\nThe plot options are parameters that affect the whole plot, like the title of\nthe plot, the axis labels, the extents, 2d/3d selection, etc. All the plot\noptions are described below in L\u003c\"Plot Options\"|/\"PLOT OPTIONS\"\u003e.  Plot options can be set\nin the plot object, or passed to the plotting methods directly.  Plot options can\nbe passed in as a leading interpolated hash, as a leading hash ref, or as a trailing\nhash ref in the argument list to any of the main plotting routines (C\u003cgplot\u003e, C\u003cplot\u003e,\nC\u003cimage\u003e, etc.).\n\nThe curve options are parameters that affect only one curve in particular. Each\ncall to C\u003cplot()\u003e can contain many curves, and options for a particular curve\nI\u003cprecede\u003e the data for that curve in the argument list. The actual type of curve\n(the \"with\" option) is persistent, but all other curve options and modifiers\nare not.  An example:\n\n gplot( with =\u003e 'points',  $x, $a,\n        {axes=\u003e x1y2},     $x, $b,\n        with =\u003e 'lines',   $x, $c );\n\nThis plots 3 curves: $a vs. $x plotted with points on the main y-axis (this is\nthe default), $b vs. $x plotted with points on the secondary y axis, and $c\nvs. $x plotted with lines on the main y-axis (the default). Note that the curve\noptions can be supplied as either an inline hash or a hash ref.\n\nAll the curve options are described below in L\u003c\"Curve Options\"|/\"CURVE OPTIONS\"\u003e.\n\nIf you want to plot multiple curves of the same type without setting\nany curve options explicitly, you must include an empty hash ref\nbetween the tuples for subsequent lines, as in:\n\n gplot( $x, $a, {}, $x, $b, {}, $x, $c );\n\n=head2 Data arguments\n\nFollowing the curve options in the C\u003cplot()\u003e argument list is the\nactual data being plotted. Each output data point is a \"tuple\" whose\nsize varies depending on what is being plotted. For example if we're\nmaking a simple 2D x-y plot, each tuple has 2 values; if we're making\na 3d plot with each point having variable size and color, each tuple\nhas 5 values (x,y,z,size,color). Each tuple element must be passed\nseparately.  For ordinary 2-D plots, the 0 dim of the tuple elements\nruns across plotted point.  PDL threading is active, so you can plot\nmultiple curves with similar curve options on a normal 2-D plot, just\nby stacking data inside the passed-in PDLs.  (An exception is that\nthreading is disabled if one or more of the data elements is a list\nref).\n\n=head3 PDLs vs array refs\n\nThe usual way to pass in data is as a PDL -- one PDL per column of data\nin the tuple.  But strings, in particular, cannot easily be hammered into\nPDLs.  Therefore any column in each tuple can be an array ref containing\nvalues (either numeric or string).  The column is interpreted using the\nusual polymorphous cast-behind-your-back behavior of Perl.  For the sake\nof sanity, if even one array ref is present in a tuple, then threading is\ndisabled in that tuple: everything has to have a nice 1-D shape.\n\n\n=head3 Implicit domains\n\nWhen making a simple 2D plot, if exactly 1 dimension is missing,\nPDL::Graphics::Gnuplot will use C\u003csequence(N)\u003e as the domain. This is\nwhy code like C\u003cplot(pdl(1,5,3,4,4) )\u003e works. Only one PDL is given\nhere, but the plot type (\"lines\" by default) requires 2 elements per\ntuple. We are thus exactly 1 ndarray short; C\u003csequence(5)\u003e is used as\nthe missing domain PDL.  This is thus equivalent to\nC\u003cplot(sequence(5), pdl(1,5,3,4,4) )\u003e.\n\nIf plotting in 3d or displaying an image, an implicit domain will be\nused if we are exactly 2 ndarrays short. In this case,\nPDL::Graphics::Gnuplot will use a 2D grid as a domain. Example:\n\n my $xy = zeros(21,21)-\u003endcoords - pdl(10,10);\n gplot({'3d' =\u003e 1},\n        with =\u003e 'points', inner($xy, $xy));\n gplot( with =\u003e 'image',  sin(rvals(51,51)) );\n\nHere the only given ndarray has dimensions (21,21). This is a 3D plot, so we are\nexactly 2 ndarrays short. Thus, PDL::Graphics::Gnuplot generates an implicit\ndomain, corresponding to a 21-by-21 grid.\n\nC\u003cPDL::Graphics::Gnuplot\u003e requires explicit separators between tuples\nfor different plots, so it is always clear from the arguments you pass\nin just how many columns you are supplying. For example,\nC\u003cplot($a,$b)\u003e will plot C\u003c$b\u003e vs. C\u003c$a\u003e.  If you actually want to\nplot an overlay of both C\u003c$a\u003e and C\u003c$b\u003e against array index, you want\nC\u003cplot($a,{},$b)\u003e instead.  The C\u003c{}\u003e is a hash ref containing a\ncollection of all the curve options that you are changing between\nthe two curves -- in this case, zero of them.\n\n=head2 Images\n\nPDL::Graphics::Gnuplot supports four styles of image plot, via the \"with\" curve option.\n\nThe \"image\" style accepts a single image plane and displays it using\nthe palette (pseudocolor map) that is specified in the plot options\nfor that plot.  As a special case, if you supply as data a (3xWxH) or\n(WxHx3) PDL it is treated as an RGB image and displayed with the\n\"rgbimage\" style (below), provided there are at least 5 pixels in each of the\nother two dimensions (just to be sure).  For quick image display there\nis also an \"image\" method:\n\n use PDL::Graphics::Gnuplot qw/image gplot/;\n $im = sin(rvals(51,51)/2);\n image( $im );                # display the image\n gplot( with=\u003e'image', $im );  # display the image (longer form)\n\nThe colors are autoscaled in both cases.  To set a particular color range, use\nthe 'cbrange' plot option:\n\n image( {cbrange=\u003e[0,1]}, $im );\n\nYou can plot rgb images directly with the image style, just by including a\n3rd dimension of size 3 on your image:\n\n $rgbim = pdl( xvals($im), yvals($im),rvals($im)/sqrt(2));\n image( $rgbim );                # display an RGB image\n gplot( with=\u003e'image', $rgbim ); # display an RGB image (longer form)\n\nSome additional plot styles exist to specify RGB and RGB transparent forms\ndirectly.  These are the \"with\" styles \"rgbimage\" and \"rgbalpha\".  For each\nof them you must specify the channels as separate PDLs:\n\n gplot( with=\u003e'rgbimage', $rgbim-\u003edog );               # RGB  the long way\n gplot( with=\u003e'rgbalpha', $rgbim-\u003edog, 255*($im\u003e0) );  # RGBA the long way\n\nAccording to the gnuplot specification you can also give X and Y\nvalues for each pixel, as in\n\n gplot( with=\u003e'image', xvals($im), yvals($im), $im )\n\nbut this appears not to work properly for anything more complicated\nthan a trivial matrix of X and Y values.\n\nPDL::Graphics::Gnuplot provides a \"fits\" plot style that interprets\nWorld Coordinate System (WCS) information supplied in the header of\nthe scientific image format FITS. The image is displayed in rectified\nscientific coordinates, rather than in pixel coordinates.  You can plot\nFITS images in scientific coordinates with\n\n gplot( with=\u003e'fits', $fitsdata );\n\nThe fits plot style accepts a curve option \"resample\" (which may be\nabbreviated), that allows you to downsample and/or rectify the image\nbefore it is passed to the Gnuplot back-end.  This is useful either to\ncut down on the burden of transferring large blocks of image data or\nto rectify images with nonlinear WCS transformations in their headers.\n(gnuplot itself has a bug that prevents direct rendering of images in\nnonlinear coordinates).\n\n gplot( with=\u003e'fits', res=\u003e1, $fitsdata );\n gplot( with=\u003e'fits', res=\u003e[200], $fitsdata );\n gplot( with=\u003e'fits', res=\u003e[100,400],$fitsdata );\n\nto specify that the output are to be resampled onto a square 1024x1024 grid,\na 200x200 grid, or a 100x400 grid, respectively. The resample sizes must be\npositive integers.\nA true non-ref value will be treated as 1024x1024.\n\n=head2 Interactivity\n\nSeveral of the graphical backends of Gnuplot are interactive, allowing\nyou to pan, zoom, rotate and measure the data interactively in the plot\nwindow. See the Gnuplot documentation for details about how to do\nthis. Some terminals (such as C\u003cwxt\u003e) are persistently interactive. Other\nterminals (such as C\u003cx11\u003e) maintain their interactivity only while the\nunderlying gnuplot process is active -- i.e. until another plot is\ncreated with the same PDL::Graphics::Gnuplot object, or until the perl\nprocess exits (whichever comes first).  Still others (the hardcopy\ndevices) aren't interactive at all.\n\nSome interactive devices (notably C\u003cwxt\u003e and C\u003cx11\u003e) also support\nmouse input: you can write PDL scripts that accept and manipulate\ngraphical input from the plotted window.\n\n=head1 PLOT OPTIONS\n\nGnuplot controls plot style with \"plot options\" that configure and\nspecify virtually all aspects of the plot to be produced.   Plot\noptions are tracked as stored state in the PDL::Graphics::Gnuplot\nobject.  You can set them by passing them in to the constructor, to an\nC\u003coptions\u003e method, or to the C\u003cplot\u003e method itself.\n\nNearly all the underlying Gnuplot plot options are supported, as well\nas some additional options that are parsed by the module itself for\nconvenience.\n\nThere are many, many plot options.  For convenience, we've grouped\nthem by general category below.  Each group has a heading \"POs for E\u003clt\u003efooE\u003cgt\u003e\",\ndescribing the category.  You can skip below them all if you want to\nread about curve options or other aspects of PDL::Graphics::Gnuplot.\n\n=head2 POs for Output: terminal, termoption, output, device, hardcopy\n\nYou can send plots to a variety of different devices; Gnuplot calls\ndevices \"terminals\".  With the object-oriented interface, you must set\nthe output device with the constructor C\u003cPDL::Graphics::Gnuplot::new\u003e\n(or the exported constructor C\u003cgpwin\u003e) or the C\u003coutput\u003e method.  If you\nuse the simple non-object interface, you can set the output with the\nC\u003cterminal\u003e, C\u003ctermoption\u003e, and C\u003coutput\u003e plot options.\n\nC\u003cterminal\u003e sets the output device type for Gnuplot, and C\u003coutput\u003e sets the\nactual output file or window number.\n\nC\u003cdevice\u003e and C\u003chardcopy\u003e are for convenience. C\u003cdevice\u003e offers a\nPGPLOT-style device specifier in \"filename/device\" format (the \"filename\"\ngets sent to the \"output\" option, the \"device\" gets sent to the \"terminal\"\noption). C\u003chardcopy\u003e takes an output file name, attempts to parse out a\nfile suffix and infer a device type. C\u003chardcopy\u003e also uses a common set of\nterminal options needed to fill an entire letter page with a plot.\n\nFor finer grained control of the plotting environment, you can send\n\"terminal options\" to Gnuplot.  If you set the terminal directly with\nplot options, you can include terminal options by interpolating them\ninto a string, as in C\u003cterminal jpeg interlace butt crop\u003e, or you can\nuse the constructor C\u003cnew\u003e (also exported as C\u003cgpwin\u003e), which parses\nterminal options as an argument list.\n\nThe routine C\u003cPDL::Graphics::Gnuplot::terminfo\u003e prints a list of all\navailable terminals or, if you pass in a terminal name, options accepted\nby that terminal.\n\n\n=head2 POs for Titles\n\nThe options described here are\n\n=over\n\n=item title\n\n=item xlabel\n\n=item x2label\n\n=item ylabel\n\n=item y2label\n\n=item zlabel\n\n=item cblabel\n\n=item key\n\n=back\n\nGnuplot supports \"enhanced\" text escapes on most terminals; see \"text\",\nbelow.\n\nThe C\u003ctitle\u003e option lets you set a title for the whole plot.\n\nIndividual plot components are labeled with the C\u003clabel\u003e options.\nC\u003cxlabel\u003e, C\u003cx2label\u003e, C\u003cylabel\u003e, and C\u003cy2label\u003e specify axis titles\nfor 2-D plots.  The C\u003czlabel\u003e works for 3-D plots.  The C\u003ccblabel\u003e option\nsets the label for the color box, in plot types that have one (e.g.\nimage display).\n\n(Don't be confused by C\u003cclabel\u003e, which doesn't set a label at all, rather\nspecifies the printf format used by contour labels in contour plots.)\n\nC\u003ckey\u003e controls where the plot key (that relates line/symbol style to label)\nis placed on the plot.  It takes a scalar boolean indicating whether to turn the\nkey on (with default values) or off, or an array ref containing any of the following\narguments (all are optional) in the order listed:\n\n=over 3\n\n=item * ( on | off ) - turn the key on or off\n\n=item * ( inside | outside | lmargin | rmargin | tmargin | bmargin | at \u003cpos\u003e )\n\nThese keywords set the location of the key -- \"inside/outside\" is\nrelative to the plot border; the margin keywords indicate location in\nthe margins of the plot; and at \u003cpos\u003e (where \u003cpos\u003e is a comma-delimited string\ncontaining (x,y): C\u003ckey=E\u003cgt\u003e[at=E\u003cgt\u003e\"0.5,0.5\"]\u003e) is an exact location to place the key.\n\n=item * ( left | right | center ) ( top | bottom | center ) - horiz./vert. alignment\n\n=item * ( vertical | horizontal ) - stacking direction within the key\n\n=item * ( Left | Right ) - justification of plot labels within the key (note case)\n\n=item * [no]reverse - switch order of label and sample line\n\n=item * [no]invert - invert the stack order of the labels\n\n=item * samplen \u003clength\u003e - set the length of the sample lines\n\n=item * spacing \u003cdist\u003e - set the spacing between adjacent labels in the list\n\n=item * [no]autotitle - control whether labels are generated when not specified\n\n=item * title \"\u003ctext\u003e\" - set a title for the key\n\n=item * [no]enhanced - override terminal settings for enhanced text interpretation\n\n=item * font \"\u003cface\u003e,\u003csize\u003e\" - set font for the labels\n\n=item * textcolor \u003ccolorspec\u003e\n\n=item * [no]box linestyle \u003cls\u003e linetype \u003clt\u003e linewidth \u003clw\u003e - control box around the key\n\n=back\n\n=head2 POs for axes, grids, \u0026 borders\n\nThe options described here are\n\n=over\n\n=item grid\n\n=item xzeroaxis\n\n=item x2zeroaxis\n\n=item yzeroaxis\n\n=item y2zeroaxis\n\n=item zzeroaxis\n\n=item border\n\n=back\n\nNormally, tick marks and their labels are applied to the border of a plot,\nand no extra axes (e.g. the y=0 line) nor coordinate grids are shown.  You can\nspecify which (if any) zero axes should be drawn, and which (if any)\nborders should be drawn.\n\nThe C\u003cborder\u003e option controls whether the plot itself has a border\ndrawn around it.  You can feed it a scalar boolean value to indicate\nwhether borders should be drawn around the plot -- or you can feed in a list\nref containing options.  The options are all optional but must be supplied\nin the order given.\n\n=over 3\n\n=item * \u003cinteger\u003e - packed bit flags for which border lines to draw\n\n\nThe default if you set a true value for C\u003cborder\u003e is to draw all border lines.\nYou can feed in a single integer value containing a bit mask, to draw only some\nborder lines.  From LSB to MSB, the coded lines are bottom, left, top, right for\n2D plots -- e.g. 5 will draw bottom and top borders but neither left nor right.\n\nIn three dimensions, 12 bits are used to describe the twelve edges of\na cube surrounding the plot.  In groups of three, the first four\ncontrol the bottom (xy) plane edges in the same order as in the 2-D\nplots; the middle four control the vertical edges that rise from the\nclockwise end of the bottom plane edges; and the last four control the\ntop plane edges.\n\n=item * ( back | front ) - draw borders first or last (controls hidden line appearance)\n\n=item * linewidth \u003clw\u003e, linestyle \u003cls\u003e, linetype \u003clt\u003e\n\nThese are Gnuplot's usual three options for line control.\n\n=back\n\nThe C\u003cgrid\u003e option indicates whether gridlines should be drawn on\neach axis.  It takes an array ref of arguments, each of which is either \"no\" or \"m\" or \"\",\nfollowed by an axis name and \"tics\" --\ne.g. C\u003c\u003c grid=\u003e[\"noxtics\",\"ymtics\"] \u003e\u003e draws no X gridlines and draws\n(horizontal) Y gridlines on Y axis major and minor tics, while\nC\u003c\u003c grid=\u003e[\"xtics\",\"ytics\"] \u003e\u003e or C\u003c\u003c grid=\u003e[\"xtics ytics\"] \u003e\u003e will draw both\nvertical (X) and horizontal (Y) grid lines on major tics.\n\nTo draw a coordinate grid with default values, set C\u003c\u003c grid=\u003e1 \u003e\u003e.  For more\ncontrol, feed in an array ref with zero or more of the following parameters, in order:\n\nThe C\u003czeroaxis\u003e keyword indicates whether to actually draw each axis\nline at the corresponding zero along its indicated dimension.  For\nexample, to draw the X axis (y=0), use C\u003c\u003c xzeroaxis=\u003e1 \u003e\u003e.  If you just\nwant the axis turned on with default values, you can feed in a Boolean\nscalar; if you want to set its parameters, you can feed in an array ref\ncontaining linewidth, linestyle, and linetype (with appropriate\nparameters for each), e.g.  C\u003c\u003c xzeroaxis=\u003e[linewidth=\u003e2] \u003e\u003e.\n\n=head2 POs for axis range and mode\n\nThe options described here are\n\n=over\n\n=item xrange\n\n=item x2range\n\n=item yrange\n\n=item y2range\n\n=item zrange\n\n=item rrange\n\n=item cbrange\n\n=item trange\n\n=item urange\n\n=item vrange\n\n=item autoscale\n\n=item logscale\n\n=back\n\nGnuplot accepts explicit ranges as plot options for all axes.  Each option\naccepts an array ref with (min, max).  If either min or max is missing, then\nthe opposite limit is autoscaled.  The x and y ranges refer to the usual\nordinate and abscissa of the plot; x2 and y2 refer to alternate ordinate and\nabscissa; z if for 3-D plots; r is for polar plots; t, u, and v are for parametric\nplots.  cb is for the color box on plots that include it (see \"color\", below).\n\nC\u003crrange\u003e is used for radial coordinates (which\nare accessible using the C\u003cmapping\u003e plot option, below).\n\nC\u003ccbrange\u003e (for 'color box range') sets the range of values over which\npalette colors (either gray or pseudocolor) are matched.  It is valid\nin any color-mapped plot (including images or palette-mapped lines or\npoints), even if no color box is being displayed for this plot.\n\nC\u003ctrange\u003e, C\u003curange\u003e, and C\u003cvrange\u003e set ranges for the parametric coordinates\nif you are plotting a parametric curve.\n\nBy default all axes are autoscaled unless you specify a range on that\naxis, and partially (min or max) autoscaled if you specify a partial\nrange on that axis.  C\u003cautoscale\u003e allows more explicit control of how\nautoscaling is performed, on an axis-by-axis basis.  It accepts a hash\nref, each element of which specifies how a single axis should be\nautoscaled.  Each keyword contains an axis name followed by one of\n\"fix\", \"min\", \"max\", \"fixmin\", or \"fixmax\".  You can set all the axes at\nonce by setting the keyword name to ' '.  Examples:\n\n autoscale=\u003e{x=\u003e'max',y=\u003e'fix'};\n\nThere is an older array ref syntax which is deprecated but still accepted.\n\nTo not autoscale an axis at all, specify a range for it. The fix style of\nautoscaling forces the autoscaler to use the actual min/max of the data as\nthe limit for the corresponding axis -- by default the axis gets extended\nto the next minor tic (as set by the autoticker or by a tic specification, see\nbelow).\n\nC\u003clogscale\u003e allows you to turn on logarithmic scaling for any or all\naxes, and to set the base of the logarithm.  It takes an array ref, the\nfirst element of which is a string mushing together the names of all\nthe axes to scale logarithmically, and the second of which is the base\nof the logarithm: C\u003c\u003c logscale=\u003e[xy=\u003e10] \u003e\u003e.  You can also leave off the\nbase if you want base-10 logs: C\u003c\u003c logscale=\u003e['xy'] \u003e\u003e.\n\n=head2 POs for Axis tick marks\n\nThe options described here are\n\n=over\n\n=item xtics\n\n=item x2tics\n\n=item ytics\n\n=item y2tics\n\n=item ztics\n\n=item cbtics\n\n=item mxtics\n\n=item mx2tics\n\n=item mytics\n\n=item my2tics\n\n=item mztics\n\n=item mcbtics\n\n=back\n\nAxis tick marks are called \"tics\" within Gnuplot, and they are extensively\ncontrollable via the \"{axis}tics\" options.  In particular, major and minor\nticks are supported, as are arbitrarily variable length ticks, non-equally\nspaced ticks, and arbitrarily labelled ticks.  Support exists for time formatted\nticks (see C\u003cPOs for time data values\u003e below).\n\nBy default, gnuplot will automatically place major and minor ticks.\nYou can turn off ticks on an axis by setting the appropriate {foo}tics\noption to a defined, false scalar value (e.g. C\u003c\u003c xtics=\u003e0 \u003e\u003e).  If you\nwant to set major tics to happen at a regular specified intervals, you can set the\nappropriate tics option to a nonzero scalar value (e.g. C\u003c\u003c xtics=\u003e2 \u003e\u003e to\nspecify a tic every 2 units on the X axis).  To use default values for the\ntick positioning, specify an empty hash or array ref (e.g. C\u003c\u003c xtics=\u003e{} \u003e\u003e), or\na string containing only whitespace (e.g. C\u003c\u003c xtics=\u003e' ' \u003e\u003e).\n\nIf you prepend an 'm' to any tics option, it affects minor tics instead of\nmajor tics (major tics typically show units; minor tics typically show fractions\nof a unit).\n\nEach tics option can accept a hash ref containing options to pass to\nGnuplot.  You can also pass in a snippet of gnuplot command, as either\na string or an array ref -- but those techniques are deprecated and may\ndisappear in a future version of C\u003cPDL:Graphics::Gnuplot\u003e.\n\nThe keywords are case-insensitive and may be abbreviated, just as with\nother option types.  They are:\n\n=over 2\n\n=item * axis - set to 1 to place tics on the axis (the default)\n\n=item * border - set to 1 to place tics on the border (not the default)\n\n=item * mirror - set to 1 to place mirrored tics on the opposite axis/border (the default, unless an alternate axis interferes -- e.g. y2)\n\n=item * in - set to 1 to draw tics inward from the axis/border\n\n=item * out - set to 1 to draw tics outward from the axis/border\n\n=item * scale - multiplier on tic length compared to the default\n\nIf 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.\n\n=item * rotate - turn label text by the given angle (in degrees) on the drawing plane\n\n=item * offset - offset label text from default position, (units: characters; requires array ref containing x,y)\n\n=item * locations - sets tic locations.  Gets an array ref: [incr], [start, incr], or [start, incr, stop].\n\n=item * labels - sets tic locations explicitly, with text labels for each. If you specify both C\u003clocations\u003e and C\u003clabels\u003e, you get both sets of tics on the same axis.\n\nThe labels should be a nested array ref that is a collection of duals\nor triplets.  Each dual or triplet should contain [label, position, minorflag],\nas in C\u003c\u003c labels=\u003e[[\"one\",1,0],[\"three-halves\",1.5,1],[\"two\",2,0]] \u003e\u003e.\n\n=item * format - printf-style format string for tic labels.  There are\nsome extensions to the gnuplot format tags -- see the gnuplot manual.\nGnuplot 4.8 and higher have C\u003c%h\u003e, which works like C\u003c%g\u003e but uses\nextended text formatting if it is available.\n\n=item * font - set font name and size (system font name)\n\n=item * rangelimited - set to 1 to limit tics to the range of values actually present in the plot\n\n=item * textcolor - set the color of the tick labels (see L\u003c/\"Color specification\"\u003e)\n\n=back\n\nFor example, to turn on inward mirrored X axis ticks with diagonal Arial 9 text, use:\n\n xtics =\u003e {axis=\u003e1,mirror=\u003e1,in=\u003e1,rotate=\u003e45,font=\u003e'Arial,9'}\n\nor\n\n xtics =\u003e ['axis','mirror','in','rotate by 45','font \"Arial,9\"']\n\n=head2 POs for time data values\n\nThe options described here are\n\n=over\n\n=item xmtics\n\n=item x2mtics\n\n=item ymtics\n\n=item y2mtics\n\n=item zmtics\n\n=item cbmtics\n\n=item xdtics\n\n=item x2dtics\n\n=item ydtics\n\n=item y2dtics\n\n=item zdtics\n\n=item cbdtics\n\n=item xdata\n\n=item x2data\n\n=item ydata\n\n=item y2data\n\n=item zdata\n\n=item cbdata\n\n=back\n\nGnuplot contains support for plotting absolute time and date on any of its axes,\nwith conventional formatting. There are three main methods, which are mutually exclusive\n(i.e. you should not attempt to use two at once on the same axis).\n\n=over 3\n\n=item B\u003cPlotting timestamps using UNIX times\u003e\n\nYou can set any axis to plot timestamps rather than numeric values by\nsetting the corresponding \"data\" plot option to \"time\",\ne.g. C\u003c\u003c xdata=\u003e\"time\" \u003e\u003e.  If you do so, then numeric values in the\ncorresponding data are interpreted as UNIX time (seconds since the\nUNIX epoch, neglecting leap seconds).  No provision is made for\nUTC\u003c-\u003eTAI conversion.  You can format how the times are plotted with\nthe \"format\" option in the various \"tics\" options(above).  Output\nspecifiers should be in UNIX strftime(3) format -- for example,\nC\u003c\u003c xdata=\u003e\"time\",xtics=\u003e{format=\u003e\"%Y-%b-%dT%H:%M:%S\"} \u003e\u003e\nwill plot UNIX times as ISO timestamps in the ordinate.\n\nDue to limitations within gnuplot, the time resolution in this mode is\nlimited to 1 second - if you want fractional seconds, you must use numerically\nformatted times (and/or create your own tick labels using the C\u003clabels\u003e suboption\nto the C\u003c?tics\u003e option.\n\nB\u003cTimestamp format specifiers\u003e\n\nTime format specifiers use the following printf-like codes:\n\n=over 3\n\n=item * B\u003cYear A.D.\u003e: C\u003c%Y\u003e is 4-digit year; C\u003c%y\u003e is 2-digit year (1969-2068)\n\n=item * B\u003cMonth of year\u003e: C\u003c%m\u003e: 01-12; C\u003c%b\u003e or C\u003c%h\u003e: abrev. name; C\u003c%B\u003e: full name\n\n=item * B\u003cWeek of year\u003e: C\u003c%W\u003e (week starting Monday); C\u003c%U\u003e (week starting Sunday)\n\n=item * B\u003cDay of year\u003e: C\u003c%j\u003e (1-366; boundary is midnight)\n\n=item * B\u003cDay of month\u003e: C\u003c%d\u003e (01-31)\n\n=item * B\u003cDay of week\u003e: C\u003c%w\u003e (0-6, Sunday=0), %a (abrev. name), %A (full name)\n\n=item * B\u003cHour of day\u003e: C\u003c%k\u003e (0-23); C\u003c%H\u003e (00-23); C\u003c%l\u003e (1-12); C\u003c%I\u003e (01-12)\n\n=item * B\u003cAm/pm\u003e: C\u003c%p\u003e (\"am\" or \"pm\")\n\n=item * B\u003cMinute of hour\u003e: C\u003c%M\u003e (00-60)\n\n=item * B\u003cSecond of minute\u003e: C\u003c%S\u003e (0-60)\n\n=item * B\u003cTotal seconds since start of 2000 A.D.\u003e: C\u003c%s\u003e\n\n=item * B\u003cTimestamps\u003e: C\u003c%T\u003e (same as C\u003c%H:%M:%S\u003e); C\u003c%R\u003e (same as C\u003c%H:%M\u003e); C\u003c%r\u003e (same as C\u003c%I:%M:%S %p\u003e)\n\n=item * B\u003cDatestamps\u003e: C\u003c%D\u003e (same as C\u003c%m/%d/%y\u003e); C\u003c%F\u003e (same as C\u003c%Y-%m-%d\u003e)\n\n=item * B\u003cISO timestamps\u003e: use C\u003c%DT%T\u003e.\n\n=back\n\n=item B\u003cday-of-week plotting\u003e\n\nIf you just want to plot named days of the week, you can instead use\nthe C\u003cdtics\u003e options set plotting to day of week, where 0 is Sunday and 6\nis Saturday; values are interpreted modulo 7.  For example, C\u003c\u003c\nxmtics=\u003e1,xrange=\u003e[-4,9] \u003e\u003e will plot two weeks from Wednesday to\nWednesday. As far as output format goes, this is exactly equivalent to\nusing the C\u003c%w\u003e option with full formatting - but you can treat the\nnumeric range in terms of weeks rather than seconds.\n\n=item B\u003cmonth-of-year plotting\u003e\n\nThe C\u003cmtics\u003e options set plotting to months of the year, where 1 is January and 12 is\nDecember, so C\u003c\u003c xdtics=\u003e1, xrange=\u003e[0,4] \u003e\u003e will include Christmas through Easter.\nThis is exactly equivalent to using the C\u003c%d\u003e option with full formatting - but you\ncan treat the numeric range in terms of months rather than seconds.\n\n=back\n\n=head2 POs for location/size\n\nThe options described here are\n\n=over\n\n=item tmargin\n\n=item bmargin\n\n=item lmargin\n\n=item rmargin\n\n=item offsets\n\n=item origin\n\n=item size\n\n=item justify\n\n=item clip\n\n=back\n\nAdjusting the size, location, and margins of the plot on the plotting\nsurface is something of a null operation for most single plots -- but\nyou can tweak the placement and size of the plot with these options.\nThat is particularly useful for multiplots, where you might like to\nmake an inset plot or to lay out a set of plots in a custom way.\n\nThe margin options accept scalar values -- either a positive number of\ncharacter heights or widths of margin around the plot compared to the\nedge of the device window, or a string that starts with \"at screen \"\nand interpolates a number containing the fraction of the plot window\noffset.  The \"at screen\" technique allows exact plot placement and is\nan alternative to the C\u003corigin\u003e and C\u003csize\u003e options below.\n\nThe C\u003coffsets\u003e option allows you to put an empty boundary around the\ndata, inside the plot borders, in an autosacaled graph.  The offsets\nonly affect the x1 and y1 axes, and only in 2D plot commands.\nC\u003coffsets\u003e accepts an array ref with four values for the offsets, which\nare given in scientific (plotted) axis units.\n\nThe C\u003corigin\u003e option lets you specify the origin (lower left corner)\nof an individual plot on the plotting window.  The coordinates are\nscreen coordinates -- i.e. fraction of the total plotting window.\n\nThe size option lets you adjust the size and aspect ratio of the plot,\nas an absolute fraction of the plot window size.  You feed in fractional\nratios, as in C\u003c\u003c size=\u003e[$xfrac, $yfrac] \u003e\u003e.  You can also feed in some keywords\nto adjust the aspect ratio of the plot.  The size option overrides any\nautoscaling that is done by the auto-layout in multiplot mode, so use\nwith caution -- particularly if you are multiplotting.  You can use\n\"size\" to adjust the aspect ratio of a plot, but this is deprecated\nin favor of the pseudo-option C\u003cjustify\u003e.\n\nC\u003cjustify\u003e sets the scientific aspect ratio of a 2-D plot.  Unity\nyields a plot with a square scientific aspect ratio.  Larger\nnumbers yield taller plots.\n\nC\u003cclip\u003e controls the border between the plotted data and the border of the plot.\nThere are three clip types supported:   points, one, and two.  You can set them\nindependently by passing in booleans with their names: C\u003c\u003c clip=\u003e[points=\u003e1,two=\u003e0] \u003e\u003e.\n\n=head2 POs for Color: colorbox, palette, clut, pseudocolor, pc, perceptual, pcp\n\nColor plots are supported via RGB and pseudocolor.  Plots that use pseudcolor or\ngrayscale can have a \"color box\" that shows the photometric meaning of the color.\n\nThe colorbox generally appears when necessary but can be controlled manually\nwith the C\u003ccolorbox\u003e option.  C\u003ccolorbox\u003e accepts a scalar boolean value indicating\nwhether or no to draw a color box, or an array ref containing additional options.\nThe options are all, well, optional but must appear in the order given:\n\n=over 3\n\n=item ( vertical | horizontal ) - indicates direction of the gradient in the box\n\n=item ( default | user ) - indicates user origin and size\n\nIf you specify C\u003cdefault\u003e the colorbox will be placed on the right-hand side of the plot; if you specify C\u003cuser\u003e, you give the location and size in subsequent arguments:\n\n colorbox =\u003e [ 'user', 'origin'=\u003e\"$x,$y\", 'size' =\u003e \"$x,$y\" ]\n\n=item ( front | back ) - draws the colorbox before or after the plot\n\n=item ( noborder | bdefault | border \u003cline style\u003e ) - specify border\n\nThe line style is a numeric type as described in the gnuplot manual.\n\n=back\n\nThe C\u003cpalette\u003e option offers many arguments that are not fully\ndocumented in this version but are explained in the gnuplot manual.\nIt offers complete control over the pseudocolor mapping function.\n\nFor simple color maps, C\u003cclut\u003e gives access to a set of named color\nmaps.  (from \"Color Look Up Table\").  A few existing color maps are:\n\"default\", \"gray\", \"sepia\", \"ocean\", \"rainbow\", \"heat1\", \"heat2\", and\n\"wheel\".  To see a complete list, specify an invalid table,\ne.g. C\u003c\u003c clut=\u003e'xxx' \u003e\u003e.  C\u003cclut\u003e is maintained but is superseded\nby C\u003cpc\u003e and C\u003cpcp\u003e (below), which give access to a better variety\nof color tables, and have better support for scientific images.\n\nC\u003cpseudocolor\u003e (synonym C\u003cpc\u003e) gives access to the color tables built\nin to the C\u003cPDL::Transform::Color\u003e package, if that package is\navailable.  It takes either a color table name or an array ref which\nis a collection of arguments that get sent to the\nC\u003cPDL::Transform::Color::t_pc\u003e transform definition method. Sending\nthe empty string or undef will generate a list of allowable color\ntable names.  Many of the color tables are \"photometric\" and\nwill render photometric data correctly without gamma correction.\n\nC\u003cperceptual\u003e (synonym C\u003cpcp\u003e) gives the same access to\nC\u003cPDL::Transform::Color\u003e as does C\u003cpseudocolor\u003e, but the\n\"equal-perceptual-difference\" scaling is used -- i.e. input\nvalues are gamma-corrected by the module so that uniform\nshifts in numeric value yield approximately uniform perceptual\nshifts.\n\nIf you use C\u003cpseudocolor\u003e or C\u003cperceptual\u003e, and if\nC\u003cPDL::Transform::Color\u003e can be loaded, then the external module\nis used to define a custom Gnuplot palette by linear interpolation\nacross 256 values.  That palette is then used to translate your\nmonochrome data to a color image.  The Gnuplot output is assumed\nto be sRGB.  This is probably OK for most output devices.\n\n=head2 POs for 3D: trid, view, pm3d, hidden3d, dgrid3d, surface, xyplane, mapping\n\nIf C\u003ctrid\u003e or its synonym C\u003c3d\u003e is true, Gnuplot renders a 3-D plot.\nThis changes the default tuple size from 2 to 3.  This\noption is used to switch between the Gnuplot \"plot\" and \"splot\"\ncommand, but it is tracked with persistent state just as any other\noption.\n\nThe C\u003cview\u003e option controls the viewpoint of the 3-D plot.  It takes a\nlist of numbers: C\u003c\u003c view=\u003e[$rot_x, $rot_z, $scale, $scale_z] \u003e\u003e.  After\neach number, you can omit the subsequent ones.  Alternatively,\nC\u003c\u003c view=\u003e['map'] \u003e\u003e represents the drawing as a map (e.g. for contour\nplots) and C\u003c\u003c view=\u003e[equal=\u003e'xy'] \u003e\u003e forces equal length scales on the X\nand Y axes regardless of perspective, while C\u003c\u003c view=\u003e[equal=\u003e'xyz'] \u003e\u003e\nsets equal length scales on all three axes.\n\nThe C\u003cpm3d\u003e option accepts several parameters to control the pm3d plot style,\nwhich is a palette-mapped 3d surface.  They are not documented here in this\nversion of the module but are explained in the gnuplot manual.\n\nC\u003chidden3d\u003e accepts a list of parameters to control how hidden surfaces are\nplotted (or not) in 3D. It accepts a boolean argument indicating whether to hide\n\"hidden\" surfaces and lines; or an array ref containing parameters that control how\nhidden surfaces and lines are handled.  For details see the gnuplot manual.\n\nC\u003cxyplane\u003e sets the location of that plane (which is drawn) relative\nto the rest of the plot in 3-space.  It takes a single string: \"at\" or\n\"relative\", and a number.  C\u003c\u003c xyplane=\u003e[at=\u003e$z] \u003e\u003e places the XY plane at the\nstated Z value (in scientific units) on the plot.  C\u003c\u003c xyplane=\u003e[relative=\u003e$frac] \u003e\u003e\nplaces the XY plane $frac times the length of the scaled Z axis *below* the Z\naxis (i.e. 0 places it at the bottom of the plotted Z axis; and -1 places it\nat the top of the plotted Z axis).\n\nC\u003cmapping\u003e takes a single string: \"cartesian\", \"spherical\", or\n\"cylindrical\".  It determines the interpretation of data coordinates\nin 3-space. (Compare to the C\u003cpolar\u003e option in 2-D).\n\n=head2 POs for Contour plots - contour, cntrparam\n\nContour plots are only implemented in 3D.  To make a normal 2D contour\nplot, use 3-D mode, but set the view to \"map\" - which projects the 3-D\nplot onto its 2-D XY plane. (This is convoluted, for sure -- future\nversions of this module may have a cleaner way to do it).\n\nC\u003ccontour\u003e enables contour drawing on surfaces in 3D.  It takes a\nsingle string, which should be \"base\", \"surface\", or \"both\".\n\nC\u003ccntrparam\u003e manages how contours are generated and smoothed.  It\naccepts an array ref with a collection of Gnuplot parameters that are\nissued one per line; refer to the Gnuplot manual for how to operate\nit.\n\n=head2 POs for Polar plots - polar, angles, mapping\n\nYou can make 2-D polar plots by setting C\u003cpolar\u003e to a true value.  The\nordinate is then plotted as angle, and the abscissa is radius on the plot.\nThe ordinate can be in either radians or degrees, depending on the\nC\u003cangles\u003e parameter\n\nC\u003cangles\u003e takes either \"degrees\" or \"radians\" (default is radians).\n\nC\u003cmapping\u003e is used to set 3-D polar plots, either cylindrical or spherical\n(see the section on 3-D plotting, above).\n\n=head2 POs for Markup - label, arrow, object\n\nYou specify plot markup in advance of the plot command, with plot\noptions (or add it later with the C\u003creplot\u003e method).  The options give\nyou access to a collection of (separately) numbered descriptions that\nare accumulated into the plot object.  To add a markup object to the\nnext plot, supply the appropriate options as an array ref or as a single\nstring.  To specify all markup objects at once, supply the appropriate\noptions for all of them as a nested list-of-lists.\n\nTo modify an object, you can specify it by number, either by appending\nthe number to the plot option name (e.g. C\u003carrow3\u003e) or by supplying it\nas the first element of the option list for that object.\n\nTo remove all objects of a given type, supply undef (e.g. C\u003c\u003c arrow=\u003eundef \u003e\u003e).\n\nFor example, to place two labels, use the plot option:\n\n label =\u003e [[\"Upper left\",at=\u003e\"10,10\"],[\"lower right\",at=\u003e\"20,5\"]];\n\nTo add a label to an existing plot object, if you don't care about what\nindex number it gets, do this:\n\n $w-\u003eoptions( label=\u003e[\"my new label\",at=\u003e[10,20]] );\n\nIf you do care what index number it gets (or want to replace an existing label),\ndo this:\n\n $w-\u003eoptions( label=\u003e[$n, \"my replacement label\", at=\u003e\"10,20\"] );\n\nwhere C\u003c$w\u003e is a Gnuplot object and C\u003c$n\u003e contains the label number\nyou care about.\n\n\n=head3 label - add a text label to the plot.\n\nThe C\u003clabel\u003e option allows adding small bits of text at arbitrary\nlocations on the plot.\n\nEach label specifier array ref accepts the following suboptions, in\norder.  All of them are optional -- if no options other than the index\ntag are given, then any existing label with that index is deleted.\n\nFor examples, please refer to the Gnuplot 4.4 manual, p. 117.\n\n=over 3\n\n=item \u003ctag\u003e - optional index number (integer)\n\n=item \u003clabel text\u003e - text to place on the plot.\n\nYou may supply double-quotes inside the string, but it is not\nnecessary in most cases (only if the string contains just an integer\nand you are not specifying a \u003ctag\u003e.\n\n=item at \u003cposition\u003e - where to place the text (sci. coordinates)\n\nThe \u003cposition\u003e should be a string containing a gnuplot position specifier.\nAt its simplest, the position is just two numbers separated by\na comma, as in C\u003c\u003c label2=\u003e[\"foo\",at=\u003e\"5,3\"] \u003e\u003e, to specify (X,Y) location\non the plot in scientific coordinates.  Each number can be preceded\nby a coordinate system specifier; see the Gnuplot 4.4 manual (page 20)\nfor details.\n\n=item ( left | center | right ) - text placement rel. to position\n\n=item rotate [ by \u003cdegrees\u003e ] - text rotation\n\nIf \"rotate\" appears in the list alone, then the label is rotated 90 degrees\nCCW (bottom-to-top instead of left-to-right).  The following \"by\" clause is\noptional.\n\n=item font \"\u003cname\u003e,\u003csize\u003e\" - font specifier\n\nThe \u003cname\u003e,\u003csize\u003e must be double quoted in the string (this may be fixed\nin a future version), as in\n\n label3=\u003e[\"foo\",at=\u003e\"3,4\",font=\u003e'\"Helvetica,18\"']\n\n=item noenhanced - turn off gnuplot enhanced text processing (if enabled)\n\n=item ( front | back ) - rendering order (last or first)\n\n=item textcolor \u003ccolorspec\u003e\n\n=item (point \u003cpointstyle\u003e | nopoint ) - control whether the exact position is marked\n\n=item offset \u003coffset\u003e - offfset from position (in points).\n\n=back\n\n=head3 arrow - place an arrow or callout line on the plot\n\nWorks similarly to the C\u003clabel\u003e option, but with an arrow instead of text.\n\nThe arguments, all of which are optional but which must be given in the order listed,\nare:\n\n=over 3\n\n=item from \u003cposition\u003e - start of arrow line\n\nThe \u003cposition\u003e should be a string containing a gnuplot position specifier.\nAt its simplest, the position is just two numbers separated by\na comma, as in C\u003c\u003c arrow2=\u003e[\"foo\",at=\u003e\"5,3\"] \u003e\u003e, to specify (X,Y) location\non the plot in scientific coordinates.  Each number can be preceded\nby a coordinate system specifier; see the Gnuplot 4.4 manual (page 20)\nfor details.\n\n=item ( to | rto ) \u003cposition\u003e  - end of arrow line\n\nThese work like C\u003cfrom\u003e.  For absolute placement, use \"to\".  For placement\nrelative to the C\u003cfrom\u003e position, use \"rto\".\n\n=item (arrowstyle | as) \u003carrow_style\u003e\n\nThis specifies that the arrow be drawn in a particular predeclared numerical\nstyle.  If you give this parameter, you should omit all the following ones.\n\n=item ( nohead | head | backhead | heads ) - specify arrowhead placement\n\n=item size \u003clength\u003e,\u003cangle\u003e,\u003cbackangle\u003e - specify arrowhead geometry\n\n=item ( filled | empty | nofilled ) - specify arrowhead fill\n\n=item ( front | back ) - specify drawing order ( last | first )\n\n=item linestyle \u003cline_style\u003e - specify a numeric linestyle\n\n=item linetype \u003cline_type\u003e - specify numeric line type\n\n=item linewidth \u003cline_width\u003e - multiplier on the width of the line\n\n=back\n\n=head3 object - place a shape on the graph\n\nC\u003cobject\u003es are rectangles, ellipses, circles, or polygons that can be placed\narbitrarily on the plotting plane.\n\nThe arguments, all of which are optional but which must be given in the order listed, are:\n\n=over 3\n\n=item \u003cobject-type\u003e \u003cobject-properties\u003e - type name of the shape and its type-specific properties\n\nThe \u003cobject-type\u003e is one of four words: \"rectangle\", \"ellipse\", \"circle\", or \"polygon\".\n\nYou can specify a rectangle with C\u003c\u003c from=\u003e$pos1, [r]to=\u003e$pos2 \u003e\u003e, with C\u003c\u003c center=\u003e$pos1, size=\u003e\"$w,$h\" \u003e\u003e,\nor with C\u003c\u003c at=\u003e$pos1,size=\u003e\"$w,$h\" \u003e\u003e.\n\nYou can specify an ellipse with C\u003c\u003c at=\u003e$pos, size=\u003e\"$w,$h\" \u003e\u003e or C\u003c\u003c center=\u003e$pos, size=\u003e\"$w,$h\" \u003e\u003e, followed\nby C\u003c\u003c angle=\u003e$a \u003e\u003e.\n\nYou can specify a circle with C\u003c\u003c at=\u003e$pos, \u003e\u003e or C\u003c\u003c center=\u003e$pos, \u003e\u003e, followed\nby C\u003c\u003c size=\u003e$radius \u003e\u003e and (optionally) C\u003c\u003c arc=\u003e\"[$begin:$end]\" \u003e\u003e.\n\nYou can specify a polygon with C\u003c\u003c from=\u003e$pos1,to=\u003e$pos2,to=\u003e$pos3,...to=\u003e$posn \u003e\u003e or with\nC\u003c\u003c from=\u003e$pos1,rto=\u003e$diff1,rto=\u003e$diff2,...rto=\u003e$diffn \u003e\u003e.\n\n=item ( front | back | behind ) - draw the object last | first | really-first.\n\n=item fc \u003ccolorspec\u003e - specify fill color\n\n=item fs \u003cfillstyle\u003e - specify fill style\n\n=item lw \u003cwidth\u003e - multiplier on line width\n\n=back\n\n=head2 POs for appearance tweaks - bars, boxwidth, isosamples, pointsize, style\n\nB\u003cC\u003cbars\u003e\u003e sets the width and behavior of the tick marks at the ends of error bars.\nIt takes a list containing at most two elements, both of which are optional:\n\n=over 3\n\n=item * A width specifier, which should be a numeric size multiplier times the usual\nwidth (which is about one character width in the default font size), or the word\nC\u003cfullwidth\u003e to make the ticks the same width as their associated boxes in boxplots\nand histograms.\n\n=item * the word \"front\" or \"back\" to indicate drawing order in plots that might contain\nfilled rectangles (e.g. boxes, candlesticks, or histograms).\n\n=back\n\nIf you pass in the undefined value you get no ticks on errorbars; if you pass in the\nempty array ref you get default ticks.\n\nB\u003cC\u003cboxwidth\u003e\u003e sets the width of drawn boxes in boxplots, candlesticks, and histograms.  It\ntakes a list containing at most two elements:\n\n=over 3\n\n=item * a numeric width\n\n=item * one of the words C\u003cabsolute\u003e or C\u003crelative\u003e.\n\n=back\n\nUnless you set C\u003crelative\u003e, the numeric width sets the width of boxes\nin X-axis scientific units (on log scales, this is measured at x=1 and\nthe same width is used throughout the plot plane).  If C\u003crelative\u003e is\nincluded, the numeric width is taken to be a multiplier on the default\nwidth.\n\nB\u003cC\u003cisosamples\u003e\u003e sets isoline density for plotting functions as\nsurfaces.  You supply one or two numbers.  The first is the number of\niso-u lines and the second is the number of iso-v lines.  If you only\nspecify one, then the two are taken to be the same.  From the gnuplot\nmanual: \"An isoline is a curve parameterized by one of the surface\nparameters while the other surface parameter is fixed.  Isolines\nprovide a simple means to display a surface.  By fixing the u\nparameter of surface s(u,v), the iso-u lines of the form c(v) =\ns(u0,v) are produced, and by fixing the v parameter, the iso-v lines\nof the form c(u)=s(u,v0) are produced\".\n\nB\u003cC\u003cpointsize\u003e\u003e accepts a single number and scales the size of points used in plots.\n\nB\u003cC\u003cstyle\u003e\u003e provides a great deal of customization for individual plot styles.\nIt is not (yet) fully parsed by PDL::Graphics::Gnuplot; please refer to the Gnuplot\nmanual for details (it is pp. 145ff in the Gnuplot 4.6.1 manual).  C\u003cstyle\u003e accepts\na hash ref whose keys are plot styles (such as you would feed to the C\u003cwith\u003e curve option),\nand whose values are array refs containing keywords and other parameters to modify how each\nplot style should be displayed.\n\n=head2 POs for locale/internationalization - locale, decimalsign\n\nC\u003clocale\u003e is used to control date stamp creation.  See the gnuplot manual.\n\nC\u003cdecimalsign\u003e  accepts a character to use in lieu of a \".\" for the decimalsign.\n(e.g. in European countries use C\u003c\u003c decimalsign=\u003e',' \u003e\u003e).\n\nC\u003cglobalwith\u003e is used as a default plot style if no valid 'with' curve option is present for\na given curve.\n\nIf set to a nonzero value, C\u003ctimestamp\u003e causes a time stamp to be\nplaced on the side of the plot, e.g. for keeping track of drafts.\n\nC\u003czero\u003e sets the approximation threshold for zero values within gnuplot.  Its default is 1e-8.\n\nC\u003cfontpath\u003e sets a font search path for gnuplot.  It accepts a collection of file names as an array ref.\n\n=head2 POs for advanced Gnuplot tweaks: topcmds, extracmds, bottomcmds, binary, dump, tee\n\nPlotting is carried out by sending a collection of commands to an underlying\ngnuplot process.  In general, the plot options cause \"set\" commands to be\nsent, configuring gnuplot to make the plot; these are followed by a \"plot\" or\n\"splot\" command and by any cleanup that is necessary to keep gnuplot in a known state.\n\nProvisions exist for sending commands directly to Gnuplot as part of a plot.  You\ncan send commands at the top of the configuration but just under the initial\n\"set terminal\" and \"set output\" commands (with the C\u003ctopcmds\u003e option), at the bottom\nof the configuration and just before the \"plot\" command (with the C\u003cextracmds\u003e option),\nor after the plot command (with the C\u003cbottomcmds\u003e option).  Each of these plot\noptions takes an array ref, each element of which should be one command line for\ngnuplot.\n\nMost plotting is done with binary data transfer to Gnuplot; however, due to\nsome bugs in Gnuplot binary handling, certain types of plot data are sent in ASCII.\nIn particular, time series and label data require transmission in ASCII (as of Gnuplot 4.4).\nYou can force ASCII transmission of all but image data by explicitly setting the\nC\u003c\u003c binary=\u003e0 \u003e\u003e option.\n\nC\u003cdump\u003e is used for debugging. If true, it writes out the gnuplot commands to\nSTDOUT I\u003cinstead\u003e of writing to a gnuplot process. Useful to see what commands\nwould be sent to gnuplot. This is a dry run. Note that if the 'binary' option is\ngiven (see below), then this dump will contain binary data. If this binary data\nshould be suppressed from the dump, set C\u003c\u003c dump =\u003e 'nobinary' \u003e\u003e.\n\nC\u003ctee\u003e is used for debugging. If true, writes out the gnuplot commands to STDERR\nI\u003cin addition\u003e to writing to a gnuplot process. This is I\u003cnot\u003e a dry run: data\nis sent to gnuplot I\u003cand\u003e to the log. Useful for debugging I/O issues. Note that\nif the 'binary' option is given (see below), then this log will contain binary\ndata. If this binary data should be suppressed from the log, set C\u003c\u003c tee =\u003e\n'nobinary' \u003e\u003e.\n\n=head1 CURVE OPTIONS\n\nThe curve options describe details of specific curves within a plot.\nThey are in a hash, whose keys are as follows:\n\n=over 2\n\n=item legend\n\nSpecifies the legend label for this curve\n\n=item axes\n\nLets you specify which X and/or Y axes to plot on.  Gnuplot supports\na main and alternate X and Y axis.  You specify them as a packed string\nwith the x and y axes indicated: for example, C\u003cx1y1\u003e to plot on the main\naxes, or C\u003cx1y2\u003e to plot using an alternate Y axis (normally gridded on\nthe right side of the plot).\n\n=item with\n\nSpecifies the plot style for this curve. The value is passed to gnuplot\nusing its 'with' keyword, so valid values are whatever gnuplot\nsupports.  See above (\"Plot styles supported\") for a list of supported\ncurve styles.\n\nThe following curve options in this list modify the plot style further.\nNot all of them are applicable to all plot styles -- for example, it makes\nno sense to specify a fill style for C\u003c\u003c with=\u003elines \u003e\u003e.\n\nFor historical reasons, you can supply the with modifier curve options\nas a single string in the \"with\" curve option.  That usage is deprecated\nand will disappear in a future version of PDL::Graphics::Gnuplot.\n\n=item linetype (abbrev 'lt')\n\nThis is a numeric selector from the default collection of line styles.\nIt includes automagic selection of dash style, color, and width from the\ndefault set of linetypes for your current output terminal.\n\n=item dashtype (abbrev 'dt')\n\nThis is can be either a numeric type selector (0 for no dashes) or\nan ARRAY ref containing a list of up to 5 pairs of (dash length,\nspace length).  The C\u003cdashtype\u003e curve option is only supported for\nGnuplot versions 5.0 and above.\n\nIf you don't specify a C\u003cdashtype\u003e curve option, the default behavior\nmatches the behavior of earlier gnuplots: many terminals support a\n\"dashed\" terminal/output option, and if you have set that option (with\nthe constructor or with the C\u003coutput\u003e method) then lines are uniquely\ndashed by default.  To make a single curve solid, specify C\u003c\u003c dt=\u003e0 \u003e\u003e as\na curve option for it; or to make all curves solid, use the constructor\nor the C\u003coutput\u003e method to set the terminal option C\u003c\u003c dashed=\u003e0 \u003e\u003e.\n\nIf your gnuplot is older than v5.0, the dashtype curve option is\nignored (and causes a warning to be emitted).\n\n=item linestyle (abbrev 'ls')\n\nThis works exactly like C\u003c\u003c linetype \u003e\u003e above, except that you can modify\nindividual line styles by setting the C\u003c\u003c style line \u003cnum\u003e \u003e\u003e plot option.\nThat is handy for a custom style you might use across several curves either\na single plot or several plots.\n\n=item linewidth (abbrev 'lw')\n\nThis is a numeric multiplier on the usual default line width in your current\nterminal.\n\n=item linecolor (abbrev 'lc')\n\nThis is a color specifier for the color of the line.  See L\u003c/\"Color specification\"\u003e.\nYou can feed in a standard color name (they're listed in the\npackage-global variable C\u003c@PDL::Graphics::Gnuplot::colornames\u003e), a\nsmall integer to index the standard linetype colors, the word\n\"variable\" to indicate that the line color is a standard linetype\ncolor to be drawn from an additional column of data, a string of the\nform #RRGGBB, where the # is literal and the RR, GG, and BB are\nhexadecimal bytes, the words \"rgbcolor variable\" to specify an\nadditional column of data containing 24-bit packed integers with RGB\ncolor values, C\u003c\u003c [palette=\u003e'frac',\u003cval\u003e] \u003e\u003e to specify a single\nfractional position (scaled 0-1) in the current palette, or C\u003c\u003c\n[palette=\u003e'cb',\u003cval\u003e] \u003e\u003e to specify a single value in the scaled\ncbrange.\n\nThere is no C\u003c\u003c linecolor=\u003e[palette=\u003evariable] \u003e\u003e due to Gnuplot's\nnon-orthogonal syntax.  To draw line color from the palette, via an\nadditional data column, see the separate \"palette\" curve option\n(below).\n\n=item textcolor (abbrev 'tc')\n\nFor plot styles like C\u003clabels\u003e that specify text, this sets the color\nof the text.  It has the same format as C\u003clinecolor\u003e (above).\n\n=item pointtype (abbrev 'pt')\n\nSelects a point glyph shape from the built-in list for your terminal,\nfor plots that render points as small glyphs (like C\u003cpoints\u003e and\nC\u003clinespoints\u003e).\n\n=item pointsize (abbrev 'ps')\n\nSelects a fractional size for point glyphs, relative to the default size\non your terminal, for plots that render points as small glyphs.\n\n=item fillcolor (abbrev 'fc')\n\nFills an area plot like C\u003cfilledcurves\u003e with a color.\nIt has the same format as C\u003clinecolor\u003e. This will fill the whole plot with\nthe same color. To fill above a threshold or below a threshold, you need to\nuse C\u003cabove\u003e and C\u003cbelow\u003e options.\n\nAn example to plot data in a single function call is below:\n\n    plot({ with =\u003e 'filledcurves', fillcolor =\u003e 'green', above =\u003e 'y=0' },\n        x, y,\n        { with =\u003e 'filledcurves', fillcolor =\u003e 'red', below =\u003e 'y=0' },\n        x, y);\n\n\n=item below\n\nThis is used for C\u003cfilledcurves\u003e to set a C\u003cfillcolor\u003e below a threshold.\nYou can set the value like \"y=0\" if you want to color below the Y-axis value of 0.\n\n=item above\n\nThis is used for C\u003cfilledcurves\u003e to set a C\u003cfillcolor\u003e above a threshold.\nYou can set the value like \"y=0\" if you want to color above the Y-axis value of 0.\n\n=item fillstyle (abbrev 'fs')\n\nSpecify the way that filled regions should be colored, in plots that\nhave fillable areas (like C\u003cboxes\u003e).  Unlike C\u003clinestyle\u003e above,\nC\u003cfillstyle\u003e accepts a full specification rather than an index into a\nset of predefined styles. You can feed in: C\u003c\u003c 'empty' \u003e\u003e for no fill;\nC\u003c\u003c 'transparent solid \u003cdensity\u003e' \u003e\u003e for a solid fill with optional\n\u003cdensity\u003e from 0.0 to 1.0 (default 1.0); C\u003c\u003c 'transparent pattern \u003cn\u003e'\n\u003e\u003e for a pattern fill--plotting multiple datasets causes the pattern\nto cycle through all available pattern types, starting from pattern\n\u003cn\u003e (be aware that the default \u003cn\u003e=0 may be equivalent to 'empty');\nThe 'transparent' portions of the strings are optional, and are only\neffective on terminals that support transparency. Be aware that the\nquality of the visual output may depend on terminal type and rendering\nsoftware.\n\nAny of those fill style specification strings can have a border\nspecification string appended to it.  To specify a border, append\nC\u003c'border'\u003e, and then optionally either C\u003c\u003c 'lt=\u003e\u003ctype\u003e' \u003e\u003e or C\u003c\u003c\n'lc=\u003e\u003ccolorspec\u003e' \u003e\u003e to the string.  To specify no border, append\nC\u003c'noborder'\u003e.\n\n=item nohidden3d\n\nIf you are making a 3D plot and have used the plot option C\u003chidden3d\u003e to get\nhidden line removal, you can override that for a particular curve by setting\nthe C\u003cnohidden3d\u003e option to a true value.  Only the single curve with C\u003cnohidden3d\u003e\nset will have its hidden points rendered.\n\n=item nocontours\n\nIf you are making a contour 3D plot, you can inhibit rendering of\ncontours for a particular curve by setting C\u003cnocontours\u003e to a true\nvalue.\n\n=item nosurface\n\nIf you are making a surface 3D plot, you can inhibit rendering of the\nsurface associated with a particular curve, by setting C\u003cnosurface\u003e to\na true value.\n\n=item palette\n\nSetting C\u003c\u003c palette =\u003e 1 \u003e\u003e causes line color to be drawn from an additional\ncolumn in the data tuple.  This column is always the very last column in the\ntuple, in case of conflict (e.g. if you set both C\u003c\u003c pointsize=\u003evariable \u003e\u003e and\nC\u003c\u003c palette=\u003e1 \u003e\u003e, then the palette column is the last column and the pointsize\ncolumn is second-to-last).\n\n=item tuplesize\n\nSpecifies how many values represent each data point.  Normally you\ndon't need to set this as individual C\u003cwith\u003e styles implicitly set a\ntuple size (which is automatically extended if you specify additional\nmodifiers such as C\u003cpalette\u003e that require more data); this option\nlets you override PDL::Graphics::Gnuplot's parsing in case of irregularity.\n\n=item cdims\n\nSpecifies the dimensions of of each column in this curve's tuple.  It must\nbe 0, 1, or 2.   Normally you don't need to set this for most plots; the\nmain use is to specify that a 2-D data PDL is to be interpreted as a collection\nof 1-D columns rather than a single 2-D grid (which would be the default\nin a 3-D plot). For example:\n\n    $w=gpwin();\n    $r2 = rvals(21,21)**2;\n    $w-\u003eplot3d( wi=\u003e'lines', xvals($r2), yvals($r2), $r2 );\n\nwill produce a grid of values on a paraboloid. To instead plot a collection\nof lines using the threaded syntax, try\n\n    $w-\u003eplot3d( wi=\u003e'lines', cd=\u003e1, xvals($r2), yvals($r2), $r2 );\n\nwhich will plot 21 separate curves in a threaded manner.\n\n=item resample\n\nFor C\u003c\u003c with=\u003e'fits' \u003e\u003e. See L\u003c/Images\u003e.\n\n=back\n\n=head1 RECIPES\n\nMost of these come directly from Gnuplot commands. See the Gnuplot docs for\ndetails.\n\n=head2 2D plotting\n\nIf we're plotting an ndarray $y of y-values to be plotted sequentially (implicit\ndomain), all you need is\n\n  gplot($y);\n\nIf we also have a corresponding $x domain, we can plot $y vs. $x with\n\n  gplot($x, $y);\n\n=head3 Simple style control\n\nTo change line thickness:\n\n  gplot(with =\u003e 'lines',linewidth=\u003e4, $x, $y);\n  gplot(with =\u003e 'lines', lw=\u003e4, $x, $y);\n\nTo change point size and point type:\n\n  gplot(with =\u003e 'points',pointtype=\u003e8, $x, $y);\n  gplot(with =\u003e 'points',pt=\u003e8, $x, $y);\n\n=head3 Errorbars\n\nTo plot errorbars that show $y +- 1, plotted with an implicit domain\n\n  gplot(with =\u003e 'yerrorbars', $y, $y-\u003eones);\n\nSame with an explicit $x domain:\n\n  gplot(with =\u003e 'yerrorbars', $x, $y, $y-\u003eones);\n\nSymmetric errorbars on both x and y. $x +- 1, $y +- 2:\n\n  gplot(with =\u003e 'xyerrorbars', $x, $y, $x-\u003eones, 2*$y-\u003eones);\n\nTo plot asymmetric errorbars that show the range $y-1 to $y+2 (note that here\nyou must specify the actual errorbar-end positions, NOT just their deviations\nfrom the center; this is how Gnuplot does it)\n\n  gplot(with =\u003e 'yerrorbars', $y, $y - $y-\u003eones, $y + 2*$y-\u003eones);\n\n=head3 More multi-value styles\n\nPlotting with variable-size circles (size given in plot units, requires Gnuplot \u003e= 4.4)\n\n  gplot(with =\u003e 'circles', $x, $y, $radii);\n\nPlotting with a variably-sized arbitrary point type (size given in multiples of\nthe \"default\" point size)\n\n  gplot(with =\u003e 'points', pointtype=\u003e7, pointsize=\u003e'variable',\n        $x, $y, $sizes);\n\nColor-coded points\n\n  gplot(with =\u003e 'points', palette=\u003e1,\n        $x, $y, $colors);\n\nVariable-size AND color-coded circles. A Gnuplot (4.4.0) bug make it necessary to\nspecify the color range here\n\n  gplot(cbmin =\u003e $mincolor, cbmax =\u003e $maxcolor,\n        with =\u003e 'circles', palette=\u003e1,\n        $x, $y, $radii, $colors);\n\n=head2 3D plotting\n\nGeneral style control works identically for 3D plots as in 2D plots.\n\nTo plot a set of 3d points, with a square aspect ratio (squareness requires\nGnuplot \u003e= 4.4):\n\n  splot(square =\u003e 1, $x, $y, $z);\n\nIf $xy is a 2D ndarray, we can plot it as a height map on an implicit domain\n\n  splot($xy);\n\nComplicated 3D plot with fancy styling:\n\n  my $pi    = 3.14159;\n  my $theta = zeros(200)-\u003exlinvals(0, 6*$pi);\n  my $z     = zeros(200)-\u003exlinvals(0, 5);\n\n  splot(title =\u003e 'double helix',\n\n        { with =\u003e 'linespoints',\n          pointsize=\u003e'variable',\n          pointtype=\u003e7,\n          palette=\u003e1,\n          legend =\u003e 'spiral 1' },\n        { legend =\u003e 'spiral 2' },\n\n        # 2 sets of x, 2 sets of y, single z\n        PDL::cat( cos($theta), -cos($theta)),\n        PDL::cat( sin($theta), -sin($theta)),\n        $z,\n\n        # pointsize, color\n        0.5 + abs(cos($theta)), sin(2*$theta) );\n\n3D plots can be plotted as a heat map.\n\n  splot( extracmds =\u003e 'set view 0,0',\n         with =\u003e 'image',\n         $xy );\n\n=head2 Hardcopies\n\nTo send any plot to a file, instead of to the screen, one can simply do\n\n  gplot(hardcopy =\u003e 'output.pdf',\n        $x, $y);\n\nThe C\u003chardcopy\u003e option is a shorthand for the C\u003cterminal\u003e and\nC\u003coutput\u003e options. The output device is chosen from the file name\nsuffix.\n\nIf you want more (any) control over the output options (e.g. page\nsize, font, etc.) then you can specify the output device using the\nC\u003coutput\u003e method or the constructor itself -- or the corresponding plot\noptions in the non-object mode. For example, to generate a PDF of a\nparticular size with a particular font size for the text, one can do\n\n  gplot(terminal =\u003e 'pdfcairo solid color font \",10\" size 11in,8.5in',\n        output   =\u003e 'output.pdf',\n        $x, $y);\n\nThis command is equivalent to the C\u003chardcopy\u003e shorthand used previously, but the\nfonts and sizes can be changed.\n\nUsing the object oriented mode, you could instead say:\n\n  $w = gpwin();\n  $w-\u003eplot( $x, $y );\n  $w-\u003eoutput( pdfcairo, solid=\u003e1, color=\u003e1,font=\u003e',10',size=\u003e[11,8.5,'in'] );\n  $w-\u003ereplot();\n  $w-\u003eclose();\n\nMany hardcopy output terminals (such as C\u003cpdf\u003e and C\u003csvg\u003e) will not\ndump their plot to the file unless the file is explicitly closed with a\nchange of output device or a call to C\u003creset\u003e, C\u003crestart\u003e, or C\u003cclose\u003e.\nThis is because those devices support multipage output and also require\nan end-of-file marker to close the file.\n\n=head1 Plotting examples\n\n=head2 A simple example\n\n   my $win = gpwin('x11');\n   $win-\u003eplot( sin(xvals(45)) * 3.14159/10 );\n\nHere we just plot a simple function.  The default plot style is a\nline.  Line plots take a 2-tuple (X and Y values).  Since we have\nsupplied only one element, C\u003cplot()\u003e understands it to be the Y value\n(abscissa) of the plot, and supplies value indices as X values -- so\nwe get a plot of just over 2 cycles of the sine wave over an X range\nacross X values from 0 to 44.\n\n=head2 A not-so-simple example\n\n   $win = gpwin('x11');\n   $pi = 3.14159;\n   $win-\u003eplot( {with =\u003e line}, xvals(10)**2, xvals(10),\n               {with =\u003e circles}, 2 * xvals(50), 2 * sin(xvals(50) * $pi / 10), xvals(50)/20\n    );\n\nThis plots sqrt(x) in an interesting way, and overplots some circles of varying size.\nThe line plot accepts a 2-tuple, and we supply both X and Y.  The circles plot accepts\na 3-tuple: X, Y, and R.\n\n=head2 A complicated example:\n\n   $pi    = 3.14159;\n   $theta = xvals(201) * 6 * $pi / 200;\n   $z     = xvals(201) * 5 / 200;\n\n   gplot( {trid =\u003e 1, title =\u003e 'double helix',cbr=\u003e[0,1]},\n         {with =\u003e 'linespoints',\n          pointsize=\u003e'variable',\n          pointtype=\u003e2,\n          palette=\u003e1,\n          legend =\u003e ['spiral 1','spiral 2'],\n          cdim=\u003e1},\n         pdl( cos($theta), -cos($theta) ),       # x\n         pdl( sin($theta), -sin($theta) ),       # y\n         $z,                                     # z\n         (0.5 + abs(cos($theta))),               # pointsize\n         sin($theta/3),                          # color\n         { with=\u003e'points',\n           pointsize=\u003e'variable',\n           pointtype=\u003e5,\n           palette=\u003e0\n         },\n         zeroes(6),                         # x\n         zeroes(6),                         # y\n         xvals(6),                          # z\n         xvals(6)+1                         # point size\n   );\n\nThis is a 3d plot with variable size and color. There are 5 values in\nthe tuple.  The first 2 ndarrays have dimensions (N,2); all the other\nndarrays have a single dimension. The \"cdim=\u003e1\" specifies that each column\nof data should be one-dimensional. Thus the PDL threading generates 2\ndistinct curves, with varying values for x,y and identical values for\neverything else.  To label the curves differently, 2 different sets of\ncurve options are given.  Omitting the \"cdim\" curve option would yield\na 201x2 grid with the \"linespoints\" plotstyle, rather than two separate\ncurves.\n\nIn addition to the threaded pair of linespoints curves, there are six\nvariable size points plotted as filled squares, as a secondary curve.\n\nPlot options are passed in in two places:  as a leading hash ref, and as\na trailing hash ref.  Any other hash elements or hash refs must be curve\noptions.\n\nCurves are delimited by non-data arguments.  After the initial hash\nref, curve options for the first curve (the threaded pair of spirals)\nare passed in as a second hash ref.  The curve's data arguments are\nended by the first non-data argument (the hash ref with the curve\noptions for the second curve).\n\n\n=head1 FUNCTIONS\n\n=cut\n=pod\n\n=head2 gpwin\n\n=for usage\n\n use PDL::Graphics::Gnuplot;\n $w = gpwin( @options );\n $w-\u003eplot( @plot_args );\n\n\n=for ref\n\ngpwin is the PDL::Graphics::Gnuplot exported constructor.  It is\nexported by default and is a synonym for \"new\nPDL::Graphics::Gnuplot(...)\".  If given no arguments, it creates a\nplot object with the default terminal settings for your gnuplot.  You\ncan also give it the name of a Gnuplot terminal type (e.g. 'x11') and\nsome terminal and output options (see \"output\").\n\n\n=cut\n=pod\n\n=head2 new\n\n=for usage\n\n    $w = new PDL::Graphics::Gnuplot;\n    $w-\u003eplot( @plot_args );\n    #\n    # Specify plot options alone\n    $w = new PDL::Graphics::Gnuplot( {%plot_options} );\n    #\n    # Specify device and device options (and optional default plot options)\n    $w = new PDL::Graphics::Gnuplot( device, %device_options, {%plot_options} );\n    $w-\u003eplot( @plot_args );\n\n=for ref\n\nCreates a PDL::Graphics::Gnuplot persistent plot object, and connects it to gnuplot.\n\nFor convenience, you can specify the output device and its options\nright here in the constructor.  Because different gnuplot devices\naccept different options, you must specify a device if you want to\nspecify any device configuration options (such as window size, output\nfile, text mode, or default font).\n\nIf you don't specify a device type, then the Gnuplot default device\nfor your system gets used.  You can set that with an environment\nvariable (check the Gnuplot documentation).\n\nGnuplot uses the word \"terminal\" for output devices; you can see a\nlist of terminals supported by PDL::Graphics::Gnuplot by invoking\nC\u003cPDL::Graphics::Gnuplot::terminfo()\u003e (for example in the perldl shell).\n\nFor convenience, you can provide default plot options here.  If the last\nargument to C\u003cnew()\u003e is a trailing hash ref, it is treated as plot options.\n\nAfter you have created an object, you can change its terminal/output\ndevice with the C\u003coutput\u003e method, which is useful for (e.g.) throwing\nup an interactive plot and then sending it to a hardcopy device. See\nC\u003coutput\u003e for a description of terminal options and how to format\nthem.\n\nNormally, the object connects to the command \"gnuplot\" in your path,\nusing the C\u003cAlien::Gnuplot\u003e module.  If you need to specify a binary\nother than this default, check the C\u003cAlien::Gnuplot\u003e documentation.\n\n=for example\n\n  my $plot = PDL::Graphics::Gnuplot-\u003enew({title =\u003e 'Object-oriented plot'});\n  $plot-\u003eplot( legend =\u003e 'curve', sequence(5) );\n\n\n=cut\n=pod\n\n=head2 output\n\n=for usage\n\n    $window-\u003eoutput( $device );\n    $window-\u003eoutput( $device, %device_options );\n    $window-\u003eoutput( $device, %device_options, {plot_options} );\n    $window-\u003eoutput( %device_options, {plot_options} );\n    $window-\u003eoutput( %device_options );\n\n=for ref\n\nSets the output device and options for a Gnuplot object. If you omit\nthe C\u003c$device\u003e name, then you get the gnuplot default device (generally\nC\u003cx11\u003e, C\u003cwxt\u003e, or C\u003caqua\u003e, depending on platform).\n\nYou can control the output device of a PDL::Graphics::Gnuplot object on\nthe fly.  That is useful, for example, to replot several versions of the\nsame plot to different output devices (interactive and hardcopy).\n\nGnuplot interprets terminal options differently per device.\nPDL::Graphics::Gnuplot attempts to interpret some of the more common\nones in a common way.  In particular:\n\n=over 3\n\n=item size\n\nMost drivers support a \"size\" option to specify the size of the output\nplotting surface.  The format is [$width, $height, $unit]; the\ntrailing unit string is optional but recommended, since the default\nunit of length changes from device to device.\n\nThe unit string can be in, cm, mm, px, char, or pt.  Pixels are taken\nto be 1 point in size (72 pixels per inch) and dimensions are computed\naccordingly.  Characters are taken to be 12 point in size (6 per\ninch).\n\n=item output\n\nThis option actually sets the object's \"output\" option for most terminal\ndevices; that changes the file to which the plot will be written.  Some\ndevices, notably X11 and Aqua, don't make proper use of \"output\"; for those\ndevices, specifying \"output\" in the object constructor actually sets the\nappropriate terminal option (e.g. \"window\" in the X11 terminal).\nThis is described as a \"plot option\" in the Gnuplot manual, but it is\ntreated as a setup variable and parsed with the setup/terminal options here\nin the constructor.\n\nIf you don't specify an output device, plots will go to sequentially-numbered\nfiles of the form C\u003cPlot-E\u003clt\u003enE\u003cgt\u003e.E\u003clt\u003esufE\u003cgt\u003e\u003e in your current working\ndirectory.  In that case, PDL::Graphics::Gnuplot will report (on STDERR)\nwhere the plot ended up.\n\n=item enhanced\n\nThis is a flag that indicates whether to enable Gnuplot's enhanced text\nprocessing (e.g. for superscripts and subscripts).  Set it to a false\nvalue for plain text, to a true value for enhanced text (which includes\nLaTeX-like markup for super/sub scripts and fonts).\n\n=item aa\n\nFor certain pixel-grid terminals (currently only C\u003cpncairo\u003e and\nC\u003cpng\u003e, as of v2.012), you can specify an antialiasing factor for the\noutput.  The output is rendered oversized by a factor of C\u003caa\u003e, then\nscaled down using C\u003cPDL::Transform\u003e.  Fixed font sized, line widths,\nand point sizes are autoscaled -- but you must handle variable ones\nexplicitly.\n\nAntialiasing is done in the gamma=2.2 approximation, to match the sRGB\ncoding that most pixel image files use.  (See PDL::Transform::Color\nfor more information).\n\n=back\n\nFor a brief description of the terminal options that any one device supports,\nyou can run PDL::Graphics::Gnuplot::terminfo().\n\nAs with plot options, terminal options can be abbreviated to the shortest\nunique string -- so (e.g.) \"size\" can generally be abbreviated \"si\" and\n\"monochrome\" can be abbreviated \"mono\" or \"mo\".\n\n=cut\n=pod\n\n=head2 close\n\n=for usage\n\n  $w=gpwin();\n  $w-\u003eplot(xvals(5));\n  $w-\u003eclose;\n\n=for ref\n\nClose gnuplot process (actually just a synonym for restart)\n\nSome of the gnuplot terminals (e.g. pdf) don't write out a file\npromptly.  The close method closes the associated gnuplot subprocess,\nforcing the file to be written out.  It is implemented as a simple\nrestart operation.\n\nThe object preserves the plot state, so C\u003creplot\u003e and similar methods\nstill work with the new subprocess.\n\n=cut\n=pod\n\n=head2 restart\n\n=for usage\n\n    $w-\u003erestart();\n    PDL::Graphics::Gnuplot::restart();\n\n=for ref\n\nRestart the gnuplot backend for a plot object\n\nOccasionally the gnuplot backend can get into an unknown state.\nC\u003crestart\u003e kills the gnuplot backend and starts a new one, preserving\nstate in the object.  (i.e. C\u003creplot\u003e and similar functions work even\nwith the new subprocess).\n\nCalled with no arguments, C\u003crestart\u003e applies to the global plot object.\n\n=cut\n=pod\n\n=head2 reset\n\n=for usage\n\n    $w-\u003ereset()\n\n=for ref\n\nClear state from the gnuplot backend\n\nClears all plot option state from the underlying object.  All plot\noptions except \"terminal\", \"termoptions\", \"output\", and \"multiplot\"\nare cleared.  This is similar to the \"reset\" command supported by\ngnuplot itself, and in fact it also causes a \"reset\" to be sent to\ngnuplot.\n\n\n=cut\n=pod\n\n=head2 options\n\n=for usage\n\n  $w = new PDL::Graphics::Gnuplot();\n  $w-\u003eoptions( globalwith=\u003e'lines' );\n  print %{$w-\u003eoptions()};\n\n=for ref\n\nSet/get persistent plot options for a plot object\n\nThe options method parses plot options into a gnuplot object on a\ncumulative basis, and returns the resultant options hash.\n\nIf called as a sub rather than a method, options() changes the\nglobal gnuplot object.\n\n=cut\n=pod\n\n=head2 plot_generate\n\n=for ref\n\nCalled with the same arguments as L\u003c/plot\u003e, it returns the text that\nwould be sent to Gnuplot. Exportable.\nAdded in 2.025.\n\n=cut\n=head2 gplot\n\n=for ref\n\nPlot method exported by default (synonym for \"PDL::Graphics::Gnuplot::plot\")\n\n=head2 plot\n\n=for ref\n\nThis is the main plotting routine in PDL::Graphics::Gnuplot.\n\nEach C\u003cplot()\u003e call creates a new plot from whole cloth, either creating\nor overwriting the output for that device.\n\nIf you want to add features to an existing plot, use C\u003creplot\u003e.\n\nC\u003cplot()\u003e understands the PDL bad value mechanism.  Bad values are omitted\nfrom the plot.\n\n=for usage\n\n $w=gpwin();\n $w-\u003eplot({temp_plot_options},                 # optional\n      curve_options, data, data, ... ,      # curve_options are optional for the first plot\n      curve_options, data, data, ... ,\n       {temp_plot_options});\n\nMost of the arguments are optional.\n\nAll of the extensive array of gnuplot plot styles are supported, including images and 3-D plots.\n\n=for example\n\n use PDL::Graphics::Gnuplot qw(plot);\n my $x = sequence(101) - 50;\n plot($x**2);\n\nSee main POD for PDL::Graphics::Gnuplot for details.\n\nYou can pass plot options into plot as either a leading or trailing hash ref, or both.\nIf you pass both, the trailing hash ref is parsed last and overrides the leading hash.\n\nFor debugging and curiosity purposes, the last plot command issued to gnuplot\nis maintained in a package global: C\u003c$PDL::Graphics::Gnuplot::last_plotcmd\u003e, and also\nin each object as the {last_plotcmd} field.\n\n=cut\n=pod\n\n=head2 replot\n\n=for ref\n\nReplot the last plot (possibly with new arguments).\n\nC\u003creplot\u003e is similar to gnuplot's \"replot\" command - it allows you to\nregenerate the last plot made with this object.  You can change the\nplot by adding new elements to it, modifying options, or even (with the\n\"device\" method) changing the output device.  C\u003creplot\u003e takes the same\narguments as C\u003cplot\u003e.\n\nIf you give no arguments at all (or only a plot object) then the plot\nis simply redrawn.  If you give plot arguments, they are added to the\nnew plot exactly as if you'd included them in the original plot\nelement list, and maintained for subsequent replots.\n\n(Compare to 'markup').\n\n=cut\n=pod\n\n=head2 markup\n\n=for ref\n\nAdd ephemeral markup to the last plot.\n\nC\u003cmarkup\u003e works exactly the same as C\u003creplot\u003e, except that any\nnew arguments are not added to the replot list - so you can\nadd temporary markup to a plot and regenerate the plot later\nwithout it.\n\n=cut\n=pod\n\n=head2 plot3d\n\n=for ref\n\nGenerate 3D plots. Synonym for C\u003cplot(trid =E\u003cgt\u003e 1, ...)\u003e\n\n=cut\n=pod\n\n=head2 splot\n\n=for ref\n\nGenerate 3D plots.  Synonym for C\u003cplot(trid =E\u003cgt\u003e 1, ...)\u003e\n\n=cut\n=pod\n\n=head2 lines\n\n=for ref\n\nGenerates plots with lines, by default. Shorthand for C\u003cplot(globalwith =E\u003cgt\u003e 'lines', ...)\u003e\n\n=cut\n=pod\n\n=head2 points\n\n=for ref\n\nGenerates plots with points, by default. Shorthand for C\u003cplot(globalwith =E\u003cgt\u003e 'points', ...)\u003e\n\n=cut\n=pod\n\n=head2 image\n\n=for ref\n\nDisplays an image (either greyscale or RGB).  Shorthand for C\u003cplot(globalwith =E\u003cgt\u003e 'image', ...)\u003e\n\n=cut\n=pod\n\n=head2 imag\n\n=for ref\n\nSynonym for \"image\", for people who grew up with PDL::Graphics::PGPLOT and can't remember the closing 'e'\n\n=cut\n=pod\n\n=head2 fits\n\n=for ref\n\nDisplays a FITS image.  Synonym for C\u003cplot(globalwith =E\u003cgt\u003e 'fits', ...)\u003e.\n\n=cut\n=pod\n\n=head2 multiplot_generate\n\n=for ref\n\nCalled with the same arguments as L\u003c/multiplot\u003e, it returns the text that\nwould be sent to Gnuplot.\nAdded in 2.025.\n\n=head2 multiplot\n\n=for example\n\n $a = (xvals(101)/100) * 6 * 3.14159/180;\n $b = sin($a);\n\n $w-\u003emultiplot(layout=\u003e[2,2,\"columnsfirst\"]);\n $w-\u003eplot({title=\u003e\"points\"},with=\u003e\"points\",$a,$b);\n $w-\u003eplot({title=\u003e\"lines\"}, with=\u003e\"lines\", $a,$b);\n $w-\u003emultiplot_next; # with Gnuplot 4.7+\n $w-\u003eplot({title=\u003e\"image\"}, with=\u003e\"image\", $a-\u003e(*1) * $b );\n $w-\u003eend_multi();\n\n=for ref\n\nPlot multiple plots into a single page of output.\n\nThe C\u003cmultiplot\u003e method enables multiplot mode in gnuplot, which permits\nmultiple plots on a single pane.  Plots can be lain out in a grid,\nor can be lain out freeform using the C\u003csize\u003e and C\u003corigin\u003e plot\noptions for each of the individual plots.\n\nIt is not possible to change the terminal or output device when in\nmultiplot mode; if you try to do that, by setting one of those plot\noptions, PDL::Graphics::Gnuplot will throw an error.\n\nThe options hash will accept:\n\n=over 3\n\n=item layout - define a regular grid of plots to multiplot\n\nC\u003clayout\u003e should be followed by an ARRAY ref that contains at least\nnumber of columns (\"NX\") followed by number of rows (\"NY).  After\nthat, you may include any of the \"rowsfirst\", \"columnsfirst\",\n\"downwards\", or \"upwards\" keywords to specify traversal order through\nthe grid.  Only the first letter is examined, so (e.g.) \"down\" or even\n\"dog\" works the same as \"downwards\".\n\n=item title - define a title for the entire page\n\nC\u003ctitle\u003e should be followed by a single scalar containing the title string.\n\n=item scale - make gridded plots larger or smaller than their allocated space\n\nC\u003cscale\u003e takes either a scalar or an array ref containing one or two\nvalues.  If only one value is supplied, it is a general scale factor\nof each plot in the grid.  If two values are supplied, the first is an\nX stretch factor for each plot in the grid, and the second is a Y\nstretch factor for each plot in the grid.\n\n=item offset - offset each plot from its grid origin\n\nC\u003coffset\u003e takes an array ref containing two values, that control placement\nof each plot within the grid.\n\n=back\n\n=head2 multiplot_next_generate\n\n=for ref\n\nCalled with the same arguments as L\u003c/multiplot_next\u003e, it returns the text that\nwould be sent to Gnuplot. Exportable.\nAdded in 2.025.\n\n=head2 multiplot_next\n\n=for ref\n\nSkip one plot. Added in 2.025. Requires Gnuplot 4.7+.\n\n=head2 end_multi_generate\n\n=for ref\n\nCalled with the same arguments as L\u003c/end_multi\u003e, it returns the text that\nwould be sent to Gnuplot. Exportable.\nAdded in 2.025.\n\n=head2 end_multi\n\n=for usage\n\n $w=gpwin();\n $w-\u003emultiplot(layout=\u003e[2,1]);\n $w-\u003eplot({title=\u003e\"points\"},with=\u003e'points',$a,$b);\n $w-\u003eplot({title=\u003e\"lines\"},with=\u003e\"lines\",$a,$b);\n $w-\u003eend_multi();\n\n=for ref\n\nEnds a multiplot block (i.e. a block of plots that are meant to render to a single page).\n\n=cut\n=pod\n\n=head2 read_mouse\n\n=for usage\n\n  ($x,$y,$char,$modstring) = $w-\u003eread_mouse($message);\n  $hash = $w-\u003eread_mouse($message);\n\n=for ref\n\nGet a mouse click or keystroke from the active interactive plot window.\n\nFor interactive devices (e.g. x11, wxt, aqua), read_mouse lets you accept a\nkeystroke or mouse button input from the gnuplot window.  In list context, it\nreturns four arguments containing the reported X, Y, keystroke character, and\nmodifiers packed in a string.  In scalar context, it returns a hash ref containing\nthose things.\n\nread_mouse blocks execution for input, but responds gracefully to interrupts.\n\n=cut\n=pod\n\n=head2 read_polygon\n\n=for usage\n\n  $points = $w-\u003eread_polygon(%opt)\n\n=for ref\n\nRead in a polygon by accepting mouse clicks.  The polygon is returned as a 2xN PDL of ($x,$y) values in scientific units. Acceptable options are:\n\n=over 3\n\n=item message - what to print before collecting points\n\nThere are some printf-style escapes for the prompt:\n\n\n* C\u003c%c\u003e - expands to \"an open\" or \"a closed\"\n\n* C\u003c%n\u003e - number of points currently in the polygon\n\n* C\u003c%N\u003e - number of points expected for the polygon\n\n* C\u003c%k\u003e - list of all keys accepted\n\n* C\u003c%%\u003e - %\n\n=item prompt  - what to print to prompt the user for the next point\n\nC\u003cprompt\u003e uses the same escapes as C\u003cmessage\u003e.\n\n=item n_points - number of points to accept (or 0 for indefinite)\n\nWith 0 value, points are accepted until the user presses 'q' or 'ESC' on the keyboard with focus\non the graph.  With other value, points are accepted until that happens *or* until the number\nof points is at least n_points.\n\n=item actions - hash of callback code refs indexed by character for action\n\nYou can optionally call a callback routine when any particular\ncharacter is pressed.  The actions table is a hash ref whose keys are\ncharacters and whose values are either code refs (to be called on the\nassociated keypress) or array refs containing a short description\nstring followed by a code ref.  Non-printable characters (e.g. ESC,\nBS, DEL) are accessed via a hash followed by a three digit decimal\nASCII code -- e.g. \"#127\" for DEL. Button events are indexed with the\nstrings \"BUTTON1\", \"BUTTON2\", and \"BUTTON3\", and modifications must be\nentered as well for shift, control, and\n\nThe code ref receives the arguments ($obj, $c, $poly,$x,$y,$mods), where:\n\n=over 2\n\n=item C\u003c$obj\u003e is the plot object\n\n=item C\u003c$c\u003e is the character (or \"BUTTONC\u003cn\u003e\" string),\n\n=item C\u003c$poly\u003e is a scalar ref; $$poly is the current polygon before the action,\n\n=item C\u003c$x\u003e and C\u003c$y\u003e are the current scientific coordinates, and\n\n=item C\u003c$mods\u003e is the modifier string.\n\nYou can't override the 'q' or '#027' (ESC) callbacks.  You *can* override\nthe BUTTON1 and DEL callbacks, potentially preventing the user from entering points\nat all!  You should do that with caution.\n\n=item closed - (default false): generate a closed polygon\n\nThis works by duplicating the initial point at the end of the point list.\n\n=item markup - (default 'linespoints'): style to use to render the polygon on the fly\n\nIf this is set to a true value, it should be a valid 'with' specifier (curve option).\nThe routine will call markup after each click.\n\n=back\n\n=back\n\n=cut\n=pod\n\n=head2 pause_until_close\n\n=for usage\n\n  $w-\u003epause_until_close;\n\n=for ref\n\nWait until the active interactive plot window is closed (e.g., by clicking the\nclose button, hitting the close key-binding which defaults to C\u003cq\u003e).\n\nC\u003cpause_until_close\u003e blocks execution until the close event.\n\n=cut\n=pod\n\n=head2 terminfo\n\n=for usage\n\n    use PDL::Graphics::Gnuplot qw/terminfo/;\n    terminfo();        # print info about all known terminals\n    terminfo 'aqua';   # print info about the aqua terminal\n\n    $w = gpwin();\n    $w-\u003eterminfo();\n\n=for ref\n\nPrint out information about gnuplot terminals and their custom option syntax.\n\nThe \"terminfo\" routine is a reference tool to describe the Gnuplot\nterminal types and the options they accept.  It's mainly useful in\ninteractive sessions.  It outputs information directly to the terminal.\n\n=cut\n=head1 COMPATIBILITY\n\nEverything should work on all platforms that support Gnuplot and Perl.\nCurrently, MacOS, Fedora and Debian Linux, Cygwin, and Microsoft\nWindows (under both Active State Strawberry Perl) have been tested to\nwork, although the interprocess control link is not as reliable under\nMicrosoft Windows as under POSIX systems.  Please report successes or\nfailures on other platforms to the authors. A transcript of a failed\nrun with {tee =\u003e 1} would be most helpful.\n\n=head1 REPOSITORY\n\nL\u003chttps://github.com/drzowie/PDL-Graphics-Gnuplot\u003e\n\n=head1 AUTHOR\n\nCraig DeForest, C\u003c\u003c \u003ccraig@deforest.org\u003e \u003e\u003e and Dima Kogan, C\u003c\u003c \u003cdima@secretsauce.net\u003e \u003e\u003e\n\n=head1 STILL TO DO\n\n=over 3\n\n=item some plot and curve options need better parsing:\n\n=over 3\n\n=item - labels need attention (plot option labels)\n\nThey need to be handled as hashes, not just as array refs.  Also, they don't seem to be working with timestamps.\nFurther, deeply nested options (e.g. \"at\" for labels) need attention.\n\n=back\n\n=item - new plot styles\n\nThe \"boxplot\" plot style (new to gnuplot 4.6?) requires a different using\nsyntax and will require some hacking to support.\n\n=back\n\n=head1 LICENSE AND COPYRIGHT\n\nCopyright 2011-2013 Craig DeForest and Dima Kogan\n\nThis program is free software; you can redistribute it and/or modify it\nunder the terms of either: the GNU General Public License as published\nby the Free Software Foundation; or the Perl Artistic License included with\nthe Perl language.\n\nSee http://dev.perl.org/licenses/ for more information.\n\n=cut\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpdlporters%2Fpdl-graphics-gnuplot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpdlporters%2Fpdl-graphics-gnuplot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpdlporters%2Fpdl-graphics-gnuplot/lists"}