.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Prima 3pm"
.TH Prima 3pm "2022-01-30" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
PDL::Demos::Prima \- PDL demo for PDL::Graphics::Prima
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
You can enjoy this demo in any number of ways. First, you can invoke the
demo from the command line by saying
.PP
.Vb 1
\& perl \-MPDL::Demos::Prima
.Ve
.PP
Second, you can invoke the demo from with the pdl shell by saying
.PP
.Vb 1
\& pdl> demo prima
.Ve
.PP
Finally, all of the content is in the pod documentation, so you can simply
read this, though it won't be quite so interactive. :\-)
.PP
.Vb 2
\& perldoc PDL::Demos::Prima
\& podview PDL::Demos::Prima
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The documentation in this module is meant to give a short, hands-on
introduction to PDL::Graphics::Prima, a plotting
library written on top of the Prima \s-1GUI\s0 toolkit.
.SS "use PDL::Graphics::Prima::Simple"
.IX Subsection "use PDL::Graphics::Prima::Simple"
To get started, you will want to use
PDL::Graphics::Prima::Simple. This
module provides a set of friendly wrappers for simple, first-cut data
visualization. PDL::Graphics::Prima, the underlying
library, is a general-purpose 2D plotting library built as a widget in the
Prima \s-1GUI\s0 toolkit, but we don't need the full functionality for
the purposes of this demo.
.PP
.Vb 3
\& use PDL::Graphics::Prima::Simple;
\& my $x = sequence(100)/10;
\& line_plot($x, $x\->sin);
.Ve
.SS "More than just lines!"
.IX Subsection "More than just lines!"
In addition to numerous ways to plot x/y data, you can also plot
distributions and images. The best run-down of the simple plotting routines
can be found in
the Synopsis for PDL::Graphics::Prima::Simple.
.PP
.Vb 2
\& $distribution = grandom(100);
\& hist_plot($distribution);
\& 
\& $x = sequence(100)/10;
\& cross_plot($x, $x\->sin);
\& 
\& $image = rvals(100, 100);
\& matrix_plot($image);
.Ve
.SS "Mouse Interaction"
.IX Subsection "Mouse Interaction"
Plots allow for
mouse interaction,
herein referred to as twiddling. You can resize the window, zoom with the
scroll wheel, or click and drag the canvas around. There is also a
right-click zoom-rectangle, and a right-click context menu.
.PP
.Vb 1
\& hist_plot(grandom(100));
\& 
\& # Run this, then try using your mouse
.Ve
.PP
In your Perl scripts, and in the \s-1PDL\s0 shell for some operating systems and
some versions of Term::ReadLine, twiddling will cause your script to pause
when you create a new plot. To resume your script or return execution to the
shell, either close the window or press 'q'.
.PP
.Vb 3
\& # If your PDL shell supports simultaneous
\& # input and plot interaction, running this
\& # should display both plots simultaneously:
\& 
\& $x = sequence(100)/10;
\& cross_plot($x, $x\->sin);
\& line_plot($x, $x\->cos);
.Ve
.SS "Multiple plots without blocking"
.IX Subsection "Multiple plots without blocking"
The blocking behavior just discussed is due to what is called autotwiddling.
To turn this off, simply send a boolean false value to auto_twiddle. Then,
be sure to invoke twiddling when you're done creating your plots.
.PP
.Vb 4
\& auto_twiddle(0);
\& hist_plot(grandom(100));
\& matrix_plot(rvals(100, 100));
\& twiddle();
.Ve
.PP
Once turned off, autotwiddling will remain off until you turn it back on.
.PP
.Vb 4
\& # autotwiddling still off
\& hist_plot(grandom(100));
\& matrix_plot(rvals(100, 100));
\& twiddle();
.Ve
.SS "Adding a title and axis labels"
.IX Subsection "Adding a title and axis labels"
Functions like 
hist_plot,
cross_plot, and
matrix_plot actually create and
return plot objects which you can subsequently modify. For example,
adding a title and axis labels are pretty easy. For titles, you call the
title method on the plot object. For axis
labels, you call the
label method on the axis objects.
.PP
.Vb 2
\& # Make sure autotwiddling is off in your script
\& auto_twiddle(0);
\& 
\& # Build the plot
\& my $x = sequence(100)/10;
\& my $plot = line_plot($x, $x\->sin);
\& 
\& # Add the title and labels
\& $plot\->title(\*(AqHarmonic Oscillator\*(Aq);
\& $plot\->x\->label(\*(AqTime [s]\*(Aq);
\& $plot\->y\->label(\*(AqDisplacement [cm]\*(Aq);
\& 
\& # Manually twiddle once everything is finished
\& twiddle();
.Ve
.SS "Saving to a file"
.IX Subsection "Saving to a file"
PDL::Graphics::Prima::Simple excels at user interaction, but you can save
your plots to a file using save_to_file
or save_to_postscript methods, or
by right-clicking and selecting the appropriate menu option.
.PP
.Vb 3
\& auto_twiddle(0);
\& $x = sequence(100)/10;
\& line_plot($x, $x\->sin)\->save_to_postscript;
\& 
\& # You can supply a filename to the method if you like.
\& # Also available is save_to_file, which saves to raster
\& # file formats. Expect save_to_postscript to be merged
\& # into save_to_file in the future.
.Ve
.SS "Adding additional data to the plot"
.IX Subsection "Adding additional data to the plot"
Once you have created a plot, you can
add additional data to it. You
achieve this by adding a new
DataSet with the data you want displayed.
.PP
.Vb 2
\& auto_twiddle(0);
\& my $plot = hist_plot(grandom(100));
\& 
\& # Add a Gaussian curve that "fits" the data
\& use PDL::Constants qw(PI);
\& my $fit_xs = zeroes(100)\->xlinvals(\-2, 2);
\& my $fit_ys = exp(\-$fit_xs**2 / 2) / sqrt(2*PI);
\& $plot\->dataSets\->{fit_curve} = ds::Pair($fit_xs, $fit_ys);
\& 
\& twiddle();
.Ve
.PP
The default plot type for
pairwise data is
Diamonds. You can choose a
different pairwise plot type, or
even mix and match multiple pairwise plot types.
.PP
.Vb 2
\& auto_twiddle(0);
\& my $plot = hist_plot(grandom(100));
\& 
\& # Add a Gaussian curve that "fits" the data
\& use PDL::Constants qw(PI);
\& my $fit_xs = zeroes(200)\->xlinvals(\-5, 5);
\& my $fit_ys = exp(\-$fit_xs**2 / 2) / sqrt(2*PI);
\& $plot\->dataSets\->{fit_curve} = ds::Pair($fit_xs, $fit_ys,
\&     # Use lines
\&     plotTypes => [
\&         ppair::Lines(
\&             # with a thickness of three pixels
\&             lineWidth => 3,
\&             # And the color red
\&             color => cl::LightRed,
\&         ),
\&         ppair::Diamonds,
\&     ],
\& );
\& 
\& twiddle();
.Ve
.SS "The plot command"
.IX Subsection "The plot command"
If you want to specify everything in one command, you can use the plot
function. This lets you put everything together that we've already discussed,
including multiple DataSets in a single command, title specification, and
x and y axis options.
.PP
.Vb 4
\& # Generate some data:
\& my $xs = sequence(100)/10 + 0.1;
\& my $ys = $xs\->sin + $xs\->grandom / 10;
\& my $y_err = $ys\->grandom/10;
\& 
\& # Plot the data and the fit
\& plot(
\&     \-data => ds::Pair($xs, $ys,
\&         plotTypes => [
\&             ppair::Triangles(filled => 1),
\&             ppair::ErrorBars(y_err => $y_err),
\&         ],
\&     ),
\&     \-fit  => ds::Func(\e&PDL::sin,
\&         lineWidth => 3,
\&         color => cl::LightRed,
\&     ),
\&     \-note => ds::Note(
\&         pnote::Text(\*(AqIncoming Signal\*(Aq,
\&             x => 0.2,
\&             y => sin(0.2) . \*(Aq\-3em\*(Aq,
\&         ),
\&     ),
\&     title => \*(AqNoisey Sine Wave\*(Aq,
\&     x => {
\&         label => \*(AqTime [s]\*(Aq,
\&         scaling => sc::Log,
\&     },
\&     y => { label => \*(AqMeasurement [Amp]\*(Aq },
\& );
.Ve
.SS "Enjoy PDL::Graphics::Prima!"
.IX Subsection "Enjoy PDL::Graphics::Prima!"
I hope you've enjoyed the tour, and I hope you find
PDL::Graphics::Prima to be a useful plotting tool!
.PP
.Vb 1
\& # Thanks!
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
David Mertens \f(CW\*(C`dcmertens.perl@gmail.com\*(C'\fR
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright (c) 2013, David Mertens. All righs reserved.
.PP
This module is free software; you can redistribute it and/or modify it under the
same terms as Perl itself. See perlartistic.