Prima(3pm)

✨ NAME ✨

PDL::Demos::Prima — it's the PDL demo for PDL::Graphics::Prima, bestie 💖

---

🌸 SYNOPSIS 🌸

okay so there are like so many ways to vibe with this demo. pick your fighter:

Option one: summon it straight from the command line, like:

perl -MPDL::Demos::Prima

Option two: do it from inside the pdl shell, iconic:

pdl> demo prima

Option three: all the content lives in the pod documentation, so you can literally just read it?? like right now?? it just won't be quite so interactive. :-)

perldoc PDL::Demos::Prima
podview PDL::Demos::Prima

---

🦋 DESCRIPTION 🦋

So the docs in this module are meant to give you a short, hands-on intro to PDL::Graphics::Prima — that's a plotting library written on top of the Prima GUI toolkit. cute, right? let's go 🫶

🎀 use PDL::Graphics::Prima::Simple 🎀

To get started you're gonna want PDL::Graphics::Prima::Simple. This module hands you 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 GUI toolkit — but for this demo we do not need the full functionality, so we're keeping it lowkey.

use PDL::Graphics::Prima::Simple;
my $x = sequence(100)/10;
line_plot($x, $x->sin);

🌈 More than just lines! 🌈

Not only are there numerous ways to plot x/y data — you can also plot distributions and images. The best run-down of the simple plotting routines lives in the Synopsis for PDL::Graphics::Prima::Simple.

$distribution = grandom(100);
hist_plot($distribution);

$x = sequence(100)/10;
cross_plot($x, $x->sin);

$image = rvals(100, 100);
matrix_plot($image);

💅 Mouse Interaction 💅

Plots allow for mouse interaction, which we're calling twiddling from here on out. You can resize the window, zoom with the scroll wheel, or click and drag the canvas around. There's also a right-click zoom-rectangle, and a right-click context menu. the range of options?? it's giving main character energy 👑

hist_plot(grandom(100));

# Run this, then try using your mouse

In your Perl scripts, and in the PDL 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'.

# 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);

🧚 Multiple plots without blocking 🧚

That blocking behavior we just talked about? It's due to something called autotwiddling. To turn it off, simply send a boolean false value to auto_twiddle. Then — and this is the important part — be sure to invoke twiddling when you're done creating your plots, bestie.

auto_twiddle(0);
hist_plot(grandom(100));
matrix_plot(rvals(100, 100));
twiddle();

Once turned off, autotwiddling will remain off until you turn it back on. periodt.

# autotwiddling still off
hist_plot(grandom(100));
matrix_plot(rvals(100, 100));
twiddle();

⭐ 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. so slay 💖

# 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('Harmonic Oscillator');
$plot->x->label('Time [s]');
$plot->y->label('Displacement [cm]');

# Manually twiddle once everything is finished
twiddle();

🍓 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.

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.

💜 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.

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();

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. mix and match?? obsessed 😭

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();

🔥 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. one command to rule them all fr fr

# 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(\&PDL::sin,
        lineWidth => 3,
        color => cl::LightRed,
    ),
    -note => ds::Note(
        pnote::Text('Incoming Signal',
            x => 0.2,
            y => sin(0.2) . '-3em',
        ),
    ),
    title => 'Noisey Sine Wave',
    x => {
        label => 'Time [s]',
        scaling => sc::Log,
    },
    y => { label => 'Measurement [Amp]' },
);

👑 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! it truly ate 💅

# Thanks!

---

🫶 AUTHOR 🫶

David Mertens "dcmertens.perl@gmail.com"

---

💖 LICENSE AND COPYRIGHT 💖

Copyright (c) 2013, David Mertens. All righs reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

---

and that's the whole page, bestie!! 🌟 this was perl v5.34.0, dated 2022-02-08, and yeah — Prima(3pm), no cap. go make some pretty plots, you've got this 💜🦋✨