Skip to content

Commit

Permalink
"list ref" -> "array ref" - #86
Browse files Browse the repository at this point in the history
  • Loading branch information
mohawk2 committed Apr 13, 2024
1 parent 02c4b27 commit 86001c6
Show file tree
Hide file tree
Showing 3 changed files with 81 additions and 75 deletions.
66 changes: 36 additions & 30 deletions README.pod
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ PDL::Graphics::Gnuplot - Gnuplot-based plotting for PDL

This module allows PDL data to be plotted using Gnuplot as a backend
for 2D and 3D plotting and image display. Gnuplot (not affiliated
with the Gnu project) is a venerable, open-source program that
with the GNU project) is a venerable, open-source program that
produces both interactive and publication-quality plots on many
different output devices. It is available through most Linux
repositories, on MacOS, and from its website
Expand All @@ -54,6 +54,12 @@ basic, or even complex, plots - though the full syntax is available
for advanced users who want the full flexibility of the Gnuplot
backend.

For a very quick demonstration of the power of this module, see
L<this YouTube demo video|https://www.youtube.com/watch?v=hUXDQL3rZ_0>,
and others on visualisation of
L<tesseract assembly|https://www.youtube.com/watch?v=ykQmNrSKqGQ> and
L<rotation|https://www.youtube.com/watch?v=6tpsPYBrHy0>.

Gnuplot recognizes both hard-copy and interactive plotting devices,
and on interactive devices (like X11) it is possible to pan, scale,
and rotate both 2-D and 3-D plots interactively. You can also enter
Expand Down Expand Up @@ -120,8 +126,8 @@ is called a "tuple". These plots have two columns in their tuples:

Normal threading rules apply across the arguments to a given plot.

All data are required to be supplied as either PDLs or list refs.
If you use a list ref as a data column, then normal
All data are required to be supplied as either PDLs or array refs.
If you use an array ref as a data column, then normal
threading is disabled. For example:

$x = xvals(5);
Expand Down Expand Up @@ -394,14 +400,14 @@ by stacking data inside the passed-in PDLs. (An exception is that
threading is disabled if one or more of the data elements is a list
ref).

=head3 PDLs vs list refs
=head3 PDLs vs array refs

The usual way to pass in data is as a PDL -- one PDL per column of data
in the tuple. But strings, in particular, cannot easily be hammered into
PDLs. Therefore any column in each tuple can be a list ref containing
PDLs. Therefore any column in each tuple can be an array ref containing
values (either numeric or string). The column is interpreted using the
usual polymorphous cast-behind-your-back behavior of Perl. For the sake
of sanity, if even one list ref is present in a tuple, then threading is
of sanity, if even one array ref is present in a tuple, then threading is
disabled in that tuple: everything has to have a nice 1-D shape.


Expand Down Expand Up @@ -608,7 +614,7 @@ specifies the printf format used by contour labels in contour plots.)

C<key> controls where the plot key (that relates line/symbol style to label)
is placed on the plot. It takes a scalar boolean indicating whether to turn the
key on (with default values) or off, or a list ref containing any of the following
key on (with default values) or off, or an array ref containing any of the following
arguments (all are optional) in the order listed:

=over 3
Expand Down Expand Up @@ -709,21 +715,21 @@ These are Gnuplot's usual three options for line control.
=back

The C<grid> option indicates whether gridlines should be drawn on
each axis. It takes a list ref of arguments, each of which is either "no" or "m" or "",
each axis. It takes an array ref of arguments, each of which is either "no" or "m" or "",
followed by an axis name and "tics" --
e.g. C<< grid=>["noxtics","ymtics"] >> draws no X gridlines and draws
(horizontal) Y gridlines on Y axis major and minor tics, while
C<< grid=>["xtics","ytics"] >> or C<< grid=>["xtics ytics"] >> will draw both
vertical (X) and horizontal (Y) grid lines on major tics.

vTo draw a coordinate grid with default values, set C<< grid=>1 >>. For more
control, feed in a list ref with zero or more of the following parameters, in order:
To draw a coordinate grid with default values, set C<< grid=>1 >>. For more
control, feed in an array ref with zero or more of the following parameters, in order:

The C<zeroaxis> keyword indicates whether to actually draw each axis
line at the corresponding zero along its indicated dimension. For
example, to draw the X axis (y=0), use C<< xzeroaxis=>1 >>. If you just
want the axis turned on with default values, you can feed in a Boolean
scalar; if you want to set its parameters, you can feed in a list ref
scalar; if you want to set its parameters, you can feed in an array ref
containing linewidth, linestyle, and linetype (with appropriate
parameters for each), e.g. C<< xzeroaxis=>[linewidth=>2] >>.

Expand Down Expand Up @@ -760,7 +766,7 @@ The options described here are
=back

Gnuplot accepts explicit ranges as plot options for all axes. Each option
accepts a list ref with (min, max). If either min or max is missing, then
accepts an array ref with (min, max). If either min or max is missing, then
the opposite limit is autoscaled. The x and y ranges refer to the usual
ordinate and abscissa of the plot; x2 and y2 refer to alternate ordinate and
abscissa; z if for 3-D plots; r is for polar plots; t, u, and v are for parametric
Expand Down Expand Up @@ -788,7 +794,7 @@ once by setting the keyword name to ' '. Examples:

autoscale=>{x=>'max',y=>'fix'};

There is an older list ref syntax which is deprecated but still accepted.
There is an older array ref syntax which is deprecated but still accepted.

To not autoscale an axis at all, specify a range for it. The fix style of
autoscaling forces the autoscaler to use the actual min/max of the data as
Expand All @@ -797,7 +803,7 @@ to the next minor tic (as set by the autoticker or by a tic specification, see
below).

C<logscale> allows you to turn on logarithmic scaling for any or all
axes, and to set the base of the logarithm. It takes a list ref, the
axes, and to set the base of the logarithm. It takes an array ref, the
first element of which is a string mushing together the names of all
the axes to scale logarithmically, and the second of which is the base
of the logarithm: C<< logscale=>[xy=>10] >>. You can also leave off the
Expand Down Expand Up @@ -886,7 +892,7 @@ If you pass in undef, tics get the default length. If you pass in a scalar, maj

=item * labels - sets tic locations explicitly, with text labels for each. If you specify both C<locations> and C<labels>, you get both sets of tics on the same axis.

The labels should be a nested list ref that is a collection of duals
The labels should be a nested array ref that is a collection of duals
or triplets. Each dual or triplet should contain [label, position, minorflag],
as in C<< labels=>[["one",1,0],["three-halves",1.5,1],["two",2,0]] >>.

Expand Down Expand Up @@ -1076,7 +1082,7 @@ an alternative to the C<origin> and C<size> options below.
The C<offsets> option allows you to put an empty boundary around the
data, inside the plot borders, in an autosacaled graph. The offsets
only affect the x1 and y1 axes, and only in 2D plot commands.
C<offsets> accepts a list ref with four values for the offsets, which
C<offsets> accepts an array ref with four values for the offsets, which
are given in scientific (plotted) axis units.

The C<origin> option lets you specify the origin (lower left corner)
Expand Down Expand Up @@ -1107,7 +1113,7 @@ grayscale can have a "color box" that shows the photometric meaning of the color

The colorbox generally appears when necessary but can be controlled manually
with the C<colorbox> option. C<colorbox> accepts a scalar boolean value indicating
whether or no to draw a color box, or a list ref containing additional options.
whether or no to draw a color box, or an array ref containing additional options.
The options are all, well, optional but must appear in the order given:

=over 3
Expand Down Expand Up @@ -1142,7 +1148,7 @@ of color tables, and have better support for scientific images.

C<pseudocolor> (synonym C<pc>) gives access to the color tables built
in to the C<PDL::Transform::Color> package, if that package is
available. It takes either a color table name or a list ref which
available. It takes either a color table name or an array ref which
is a collection of arguments that get sent to the
C<PDL::Transform::Color::t_pc> transform definition method. Sending
the empty string or undef will generate a list of allowable color
Expand Down Expand Up @@ -1185,7 +1191,7 @@ version of the module but are explained in the gnuplot manual.

C<hidden3d> accepts a list of parameters to control how hidden surfaces are
plotted (or not) in 3D. It accepts a boolean argument indicating whether to hide
"hidden" surfaces and lines; or a list ref containing parameters that control how
"hidden" surfaces and lines; or an array ref containing parameters that control how
hidden surfaces and lines are handled. For details see the gnuplot manual.

C<xyplane> sets the location of that plane (which is drawn) relative
Expand All @@ -1211,7 +1217,7 @@ C<contour> enables contour drawing on surfaces in 3D. It takes a
single string, which should be "base", "surface", or "both".

C<cntrparam> manages how contours are generated and smoothed. It
accepts a list ref with a collection of Gnuplot parameters that are
accepts an array ref with a collection of Gnuplot parameters that are
issued one per line; refer to the Gnuplot manual for how to operate
it.

Expand All @@ -1233,7 +1239,7 @@ You specify plot markup in advance of the plot command, with plot
options (or add it later with the C<replot> method). The options give
you access to a collection of (separately) numbered descriptions that
are accumulated into the plot object. To add a markup object to the
next plot, supply the appropriate options as a list ref or as a single
next plot, supply the appropriate options as an array ref or as a single
string. To specify all markup objects at once, supply the appropriate
options for all of them as a nested list-of-lists.

Expand Down Expand Up @@ -1266,7 +1272,7 @@ you care about.
The C<label> option allows adding small bits of text at arbitrary
locations on the plot.

Each label specifier list ref accepts the following suboptions, in
Each label specifier array ref accepts the following suboptions, in
order. All of them are optional -- if no options other than the index
tag are given, then any existing label with that index is deleted.

Expand Down Expand Up @@ -1415,7 +1421,7 @@ filled rectangles (e.g. boxes, candlesticks, or histograms).
=back

If you pass in the undefined value you get no ticks on errorbars; if you pass in the
empty list ref you get default ticks.
empty array ref you get default ticks.

B<C<boxwidth>> sets the width of drawn boxes in boxplots, candlesticks, and histograms. It
takes a list containing at most two elements:
Expand Down Expand Up @@ -1451,7 +1457,7 @@ B<C<style>> provides a great deal of customization for individual plot styles.
It is not (yet) fully parsed by PDL::Graphics::Gnuplot; please refer to the Gnuplot
manual for details (it is pp. 145ff in the Gnuplot 4.6.1 maual). C<style> accepts
a hash ref whose keys are plot styles (such as you would feed to the C<with> curve option),
and whose values are list refs containing keywords and other parameters to modify how each
and whose values are array refs containing keywords and other parameters to modify how each
plot style should be displayed.

=head2 POs for locale/internationalization - locale, decimalsign
Expand All @@ -1469,7 +1475,7 @@ placed on the side of the plot, e.g. for keeping track of drafts.

C<zero> sets the approximation threshold for zero values within gnuplot. Its default is 1e-8.

C<fontpath> sets a font search path for gnuplot. It accepts a collection of file names as a list ref.
C<fontpath> sets a font search path for gnuplot. It accepts a collection of file names as an array ref.

=head2 POs for advanced Gnuplot tweaks: topcmds, extracmds, bottomcmds, binary, dump, tee

Expand All @@ -1483,7 +1489,7 @@ can send commands at the top of the configuration but just under the initial
"set terminal" and "set output" commands (with the C<topcmds> option), at the bottom
of the configuration and just before the "plot" command (with the C<extracmds> option),
or after the plot command (with the C<bottomcmds> option). Each of these plot
options takes a list ref, each element of which should be one command line for
options takes an array ref, each element of which should be one command line for
gnuplot.

Most plotting is done with binary data transfer to Gnuplot; however, due to
Expand Down Expand Up @@ -1556,9 +1562,9 @@ If you don't specify a C<dashtype> curve option, the default behavior
matches the behavior of earlier gnuplots: many terminals support a
"dashed" terminal/output option, and if you have set that option (with
the constructor or with the C<output> method) then lines are uniquely
dashed by default. To make a single curve solid, specify C<dt=>0> as
dashed by default. To make a single curve solid, specify C<< dt=>0 >> as
a curve option for it; or to make all curves solid, use the constructor
or the C<output> method to set the terminal option C<dashed=>0>.
or the C<output> method to set the terminal option C<< dashed=>0 >>.

If your gnuplot is older than v5.0, the dashtype curve option is
ignored (and causes a warning to be emitted).
Expand Down Expand Up @@ -2367,15 +2373,15 @@ C<title> should be followed by a single scalar containing the title string.

=item scale - make gridded plots larger or smaller than their allocated space

C<scale> takes either a scalar or a list ref containing one or two
C<scale> takes either a scalar or an array ref containing one or two
values. If only one value is supplied, it is a general scale factor
of each plot in the grid. If two values are supplied, the first is an
X stretch factor for each plot in the grid, and the second is a Y
stretch factor for each plot in the grid.

=item offset - offset each plot from its grid origin

C<offset> takes a list ref containing two values, that control placement
C<offset> takes an array ref containing two values, that control placement
of each plot within the grid.

=back
Expand Down
Loading

0 comments on commit 86001c6

Please sign in to comment.