Graph::Data(3)

💖 GD::Graph::Data — the manual, but make it group chat 💖

okay so this is the Graph::Data(3) page from the User Contributed Perl Documentation corner of the internet, and bestie, we're gonna get through it together. It's GD::Graph::Data — the data set encapsulation situation for GD::Graph. Buckle up, it's giving "necessary but kind of a lot" ✨

---

🌸 NAME 🌸

GD::Graph::Data — data set encapsulation for GD::Graph. That's the whole vibe. It holds your data. It's the container. It's not the star of the show but the show literally cannot happen without it 💅

---

🎀 SYNOPSIS 🎀

use GD::Graph::Data;

That's it. That's the synopsis. Short and iconic, honestly.

---

🦋 DESCRIPTION 🦋

So this module wraps up the data structure that GD::Graph and all its little friends need. An object of this class contains a list of X values, plus a bunch of lists of corresponding Y values. Like, it really only makes sense if the Y values are numbers, but lowkey you can store literally anything in there. Nobody's gonna stop you. Undefined values have a special meaning to GD::Graph, so the module treats those with extra care when storing them — respect the undef, fr fr 🙏

Real talk though: a lot of the methods in here are meant for internal use by GD::Graph and by the module itself, and they will most likely not be useful to you. Many won't even seem useful to you... not me calling out the entire API like that 💀

---

🍓 EXAMPLES 🍓

Here's the whole flow, bestie:

use GD::Graph::Data;
use GD::Graph::bars;

my $data = GD::Graph::Data->new();

$data->read(file => '/data/sales.dat', delimiter => ',');
$data = $data->copy(wanted => [2, 4, 5]);

# Add the newer figures from the database
use DBI;
# do DBI things, like connecting to the database, statement
# preparation and execution

while (@row = $sth->fetchrow_array)
{
    $data->add_point(@row);
}

my $chart = GD::Graph::bars->new();
my $gd = $chart->plot($data);

or, if you need to make quick changes to legacy code (we've all been there 🫶):

# Legacy code builds array like this
@data = ( [qw(Jan Feb Mar)], [1, 2, 3], [5, 4, 3], [6, 3, 7] );

# And we quickly need to do some manipulations on that
my $data = GD::Graph::Data->new();
$data->copy_from(\@data);

# And now do all the new stuff that's wanted.
while (@foo = bar_baz())
{
    $data->add_point(@foo);
}

---

👑 METHODS 👑

💫 $data = GD::Graph::Data->new()

Create a brand new GD::Graph::Data object. A fresh start. A clean slate. Main character energy ✨

💫 $data->set_x($np, $value);

Set the X value of point $np to $value. Points are numbered starting with 0. You probably will never need this. Returns undef on failure.

💫 $data->get_x($np)

Get the X value of point $np. Go read "set_x" above, it's the same energy but in reverse.

💫 $data->set_y($nd, $np, $value);

Set the Y value of point $np in data set $nd to $value. Points are numbered starting with 0, data sets are numbered starting with 1. You probably will never need this either. Returns undef on failure.

💫 $data->get_y($nd, $np)

Get the Y value of point $np in data set $nd. See "set_y". This will return undef on an error, but — and this is the important part — the fact that it returns undef does not mean there was an error, because undefined values can be stored, and therefore returned. So like, undef is ambiguous. It's giving "it's complicated" 😭

💫 $data->get_y_cumulative($nd, $np)

Get the cumulative value of point $np in data set $nd. The cumulative value is obtained by adding all the values of the points $np in the data sets 1 to $nd. Math! We love her 💅

💫 $data->get_min_max_x

Returns a list of the minimum and maximum x value, or the empty list on failure.

💫 $data->get_min_max_y($nd)

Returns a list of the minimum and maximum y value in data set $nd, or the empty list on failure.

💫 $data->get_min_max_y_all()

Returns a list of the minimum and maximum y value in all data sets, or the empty list on failure.

💫 $data->add_point($X, $Y1, $Y2 ...)

Adds a point to the data set. The base for the addition is the current number of X values. So if you've got a data set with the contents

(X1,  X2)
(Y11, Y12)
(Y21)
(Y31, Y32, Y33, Y34)

then a $data->add_point(Xx, Y1x, Y2x, Y3x, Y4x) will result in

(X1,    X2,    Xx )
(Y11,   Y12,   Y1x)
(Y21,   undef, Y2x)
(Y31,   Y32,   Y3x,  Y34)
(undef, undef, Y4x)

In other words: beware how you use this, bestie. As long as you make sure all data sets are of equal length, this method is safe to use. Unequal lengths? That's on you 💀

💫 $data->num_sets()

Returns the number of data sets.

💫 $data->num_points()

In list context, returns a list with its first element the number of X values, and the subsequent elements the number of respective Y values for each data set. In scalar context returns the number of points that have an X value set, i.e. the number of data sets that would result from a call to "make_strict". Context matters, bestie — that's the whole lesson 🌈

💫 $data->x_values()

Return a list of all the X values. All of them. The whole collection.

💫 $data->y_values($nd)

Return a list of the Y values for data set $nd. Data sets are numbered from 1. Returns the empty list if $nd is out of range, or if the data set at $nd is empty. No drama, just an empty list 🎀

💫 $data->reset() OR GD::Graph::Data->reset()

As an object method: reset the data container, get rid of all data and error messages. As a class method: get rid of accumulated error messages and possible other crud. Spring cleaning, but for memory ✨

💫 $data->make_strict()

Make all data set lists the same length as the X list by truncating data sets that are too long, and filling data sets that are too short with undef values. Always returns a true value. It's a fixer. It fixes. Periodt.

💫 $data->cumulate(preserve_undef => boolean)

The cumulate parameter will summarise the Y value sets like this: the first Y value list will be unchanged, the second will contain a sum of the first and second, the third will contain the sum of first, second and third, and so on. Returns undef on failure.

If the argument preserve_undef is set to a true value, then the sum of exclusively undefined values will be preserved as an undefined value. If it is not present or is a false value, undef will be treated as zero. Note that this still will leave undefined values in the first data set alone — the first data set is apparently too iconic to touch 👑

Note: any non-numerical defined Y values will be treated as 0, but you really shouldn't be using this to store that sort of Y data. Like, genuinely. Don't. 🙈

💫 $data->wanted(indexes)

Removes all data sets except the ones in the argument list. It will also reorder the data sets in the order given. Returns undef on failure.

To remove all data sets except the first, sixth and second, in that order:

$data->wanted(1, 6, 2) or die $data->error;

💫 $data->reverse

Reverse the order of the data sets. That's it. That's the method. Short queen 💅

💫 $data->copy_from($data_ref)

Copy an 'old' style GD::Graph data structure or another GD::Graph::Data object into this object. This will remove the current data, so like, say goodbye to whatever was in there. Returns undef on failure.

💫 $data->copy()

Returns a copy of the object, or undef on failure.

💫 $data->read(arguments)

Read a data set from a file. This will remove the current data. Returns undef on failure. This method uses the standard module Text::ParseWords to parse lines. If you don't have this for some odd reason, don't use this method, or your program will die. Not a vibe. Not a slay. Just death 💀

Data file format: the default data file format is tab separated data (which can be changed with the delimiter argument). Comment lines are any lines that start with a #. In the following example the literal tabs have been replaced with <tab> for clarity:

# This is a comment, and will be ignored
Jan<tab>12<tab>24
Feb<tab>13<tab>37
# March is missing
Mar<tab><tab>
Apr<tab>9<tab>18

Valid arguments are:

• file — mandatory. The file name of the file to read from, or a reference to a file handle or glob.

$data->read(file => '/data/foo.dat') or die $data->error;
$data->read(file => \*DATA) or die $data->error;
$data->read(file => $file_handle) or die $data->error;

• no_comment — optional. Give this a true value if you don't want lines with an initial # to be skipped.

$data->read(file => '/data/foo.dat', no_comment => 1);

• delimiter — optional. A regular expression that will become the delimiter instead of a single tab.

$data->read(file => '/data/foo.dat', delimiter => '\s+');
$data->read(file => '/data/foo.dat', delimiter => qr/\s+/);

💫 $data->error() OR GD::Graph::Data->error()

Returns a list of all the errors that the current object has accumulated. In scalar context, returns the last error. If called as a class method it works at a class level. Error history, honestly — it remembers everything 📚

This method is inherited, see GD::Graph::Error for more information.

💫 $data->has_error() OR GD::Graph::Data->has_error()

Returns true if the object (or class) has errors pending, false if not. In some cases (see "copy") this is the best way to check for errors — like, sometimes the return value just won't tell you the truth, so ask directly 🫶

This method is inherited, see GD::Graph::Error for more information.

---

⭐ NOTES ⭐

As with all Modules for Perl: please stick to using the interface. If you try to fiddle too much with knowledge of the internals of this module, you could get burned. Like, actually burned. I may change them at any time. Specifically, I probably won't always keep this implemented as an array reference. So don't peek behind the curtain expecting it to stay put 🔥

---

🧚 AUTHOR 🧚

Martien Verbruggen <mgjv@tradingpost.com.au>

💜 Copyright 💜

(c) Martien Verbruggen.

All rights reserved. This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

🌈 SEE ALSO 🌈

GD::Graph, GD::Graph::Error

---

okay that's the whole page, you ate that 💅 and for the cute sign-off: this little beauty corresponds to perl v5.42.0, dated 2024-03-22, filed under Graph::Data(3). go forth and graph, bestie 🦋✨