Graph::Data(3)
Contents
GD::Graph::Data - Data set encapsulation for GD::Graph
use GD::Graph::Data;
This module encapsulates the data structure that is needed
for GD::Graph and friends. An object of this class con-
tains a list of X values, and a number of lists of corre-
sponding Y values. This only really makes sense if the Y
values are numerical, but you can basically store any-
thing. Undefined values have a special meaning to
GD::Graph, so they are treated with care when stored.
Many of the methods of this module are intended for inter-
nal use by GD::Graph and the module itself, and will most
likely not be useful to you. Many won't even seem useful
to you...
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 for quick changes to legacy code
# 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);
}
$data = GD::Graph::Data->new()
Create a new GD::Graph::Data object.
$data->set_x($np, $value);
Set the X value of point $np to $value. Points are num-
bered starting with 0. You probably will never need this.
Returns undef on failure.
$data->get_x($np)
Get the X value of point $np. See "set_x".
$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 num-
bered starting with 1. You probably will never need this.
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 the fact that it
returns undef does not mean there was an error (since
undefined values can be stored, and therefore returned).
$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.
$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. This means that if you
have a data set with the contents
(X1, X2)
(Y11, Y12)
(Y21)
(Y31, Y32, Y33, Y34)
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. As long as you
make sure that all data sets are of equal length, this
method is safe to use.
$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 con-
text 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".
$data->x_values()
Return a list of all the X values.
$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.
$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.
$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.
$data->cumulate(preserve_undef => boolean)
The cumulate parameter will summarise the Y value sets as
follows: 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 pre-
served as an undefined value. If it is not present or a
false value, undef will be treated as zero. Note that
this still will leave undefined values in the first data
set alone.
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.
$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 sec-
ond, in that order:
$data->wanted(1, 6, 2) or die $data->error;
$data->reverse
Reverse the order of the data sets.
$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. 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 stan-
dard 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.
Data file format: The default data file format is tab sep-
arated data (which can be changed with the delimiter argu-
ment). Comment lines are any lines that start with a #. In
the following example I have replaced literal tabs 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.
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.
This method is inherited, see GD::Graph::Error for more
information.
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. I may
change them at any time. Specifically, I probably won't
always keep this implemented as an array reference.
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.
GD::Graph, GD::Graph::Error
perl v5.8.0 2003-06-16 Graph::Data(3)
[ Index ] [ Back ]