1Graph::Data(3)        User Contributed Perl Documentation       Graph::Data(3)
2
3
4

NAME

6       GD::Graph::Data - Data set encapsulation for GD::Graph
7

SYNOPSIS

9       use GD::Graph::Data;
10

DESCRIPTION

12       This module encapsulates the data structure that is needed for
13       GD::Graph and friends. An object of this class contains a list of X
14       values, and a number of lists of corresponding Y values. This only
15       really makes sense if the Y values are numerical, but you can basically
16       store anything.  Undefined values have a special meaning to GD::Graph,
17       so they are treated with care when stored.
18
19       Many of the methods of this module are intended for internal use by
20       GD::Graph and the module itself, and will most likely not be useful to
21       you. Many won't even seem useful to you...
22

EXAMPLES

24         use GD::Graph::Data;
25         use GD::Graph::bars;
26
27         my $data = GD::Graph::Data->new();
28
29         $data->read(file => '/data/sales.dat', delimiter => ',');
30         $data = $data->copy(wanted => [2, 4, 5]);
31
32         # Add the newer figures from the database
33         use DBI;
34         # do DBI things, like connecting to the database, statement
35         # preparation and execution
36
37         while (@row = $sth->fetchrow_array)
38         {
39             $data->add_point(@row);
40         }
41
42         my $chart = GD::Graph::bars->new();
43         my $gd = $chart->plot($data);
44
45       or for quick changes to legacy code
46
47         # Legacy code builds array like this
48         @data = ( [qw(Jan Feb Mar)], [1, 2, 3], [5, 4, 3], [6, 3, 7] );
49
50         # And we quickly need to do some manipulations on that
51         my $data = GD::Graph::Data->new();
52         $data->copy_from(\@data);
53
54         # And now do all the new stuff that's wanted.
55         while (@foo = bar_baz())
56         {
57             $data->add_point(@foo);
58         }
59

METHODS

61   $data = GD::Graph::Data->new()
62       Create a new GD::Graph::Data object.
63
64   $data->set_x($np, $value);
65       Set the X value of point $np to $value. Points are numbered starting
66       with 0. You probably will never need this. Returns undef on failure.
67
68   $data->get_x($np)
69       Get the X value of point $np. See "set_x".
70
71   $data->set_y($nd, $np, $value);
72       Set the Y value of point $np in data set $nd to $value. Points are
73       numbered starting with 0, data sets are numbered starting with 1.  You
74       probably will never need this. Returns undef on failure.
75
76   $data->get_y($nd, $np)
77       Get the Y value of point $np in data set $nd. See "set_y". This will
78       return undef on an error, but the fact that it returns undef does not
79       mean there was an error (since undefined values can be stored, and
80       therefore returned).
81
82   $data->get_y_cumulative($nd, $np)
83       Get the cumulative value of point $np in data set<$nd>. The cumulative
84       value is obtained by adding all the values of the points $np in the
85       data sets 1 to $nd.
86
87   $data->get_min_max_x
88       Returns a list of the minimum and maximum x value or the empty list on
89       failure.
90
91   $data->get_min_max_y($nd)
92       Returns a list of the minimum and maximum y value in data set $nd or
93       the empty list on failure.
94
95   $data->get_min_max_y_all()
96       Returns a list of the minimum and maximum y value in all data sets or
97       the empty list on failure.
98
99   $data->add_point($X, $Y1, $Y2 ...)
100       Adds a point to the data set. The base for the addition is the current
101       number of X values. This means that if you have a data set with the
102       contents
103
104         (X1,  X2)
105         (Y11, Y12)
106         (Y21)
107         (Y31, Y32, Y33, Y34)
108
109       a $data->add_point(Xx, Y1x, Y2x, Y3x, Y4x) will result in
110
111         (X1,    X2,    Xx )
112         (Y11,   Y12,   Y1x)
113         (Y21,   undef, Y2x)
114         (Y31,   Y32,   Y3x,  Y34)
115         (undef, undef, Y4x)
116
117       In other words: beware how you use this. As long as you make sure that
118       all data sets are of equal length, this method is safe to use.
119
120   $data->num_sets()
121       Returns the number of data sets.
122
123   $data->num_points()
124       In list context, returns a list with its first element the number of X
125       values, and the subsequent elements the number of respective Y values
126       for each data set. In scalar context returns the number of points that
127       have an X value set, i.e. the number of data sets that would result
128       from a call to "make_strict".
129
130   $data->x_values()
131       Return a list of all the X values.
132
133   $data->y_values($nd)
134       Return a list of the Y values for data set $nd. Data sets are numbered
135       from 1. Returns the empty list if $nd is out of range, or if the data
136       set at $nd is empty.
137
138   $data->reset() OR GD::Graph::Data->reset()
139       As an object method: Reset the data container, get rid of all data and
140       error messages. As a class method: get rid of accumulated error
141       messages and possible other crud.
142
143   $data->make_strict()
144       Make all data set lists the same length as the X list by truncating
145       data sets that are too long, and filling data sets that are too short
146       with undef values. always returns a true value.
147
148   $data->cumulate(preserve_undef => boolean)
149       The cumulate parameter will summarise the Y value sets as follows: the
150       first Y value list will be unchanged, the second will contain a sum of
151       the first and second, the third will contain the sum of first, second
152       and third, and so on.  Returns undef on failure.
153
154       if the argument preserve_undef is set to a true value, then the sum of
155       exclusively undefined values will be preserved as an undefined value.
156       If it is not present or a false value, undef will be treated as zero.
157       Note that this still will leave undefined values in the first data set
158       alone.
159
160       Note: Any non-numerical defined Y values will be treated as 0, but you
161       really shouldn't be using this to store that sort of Y data.
162
163   $data->wanted(indexes)
164       Removes all data sets except the ones in the argument list. It will
165       also reorder the data sets in the order given. Returns undef on
166       failure.
167
168       To remove all data sets except the first, sixth and second, in that
169       order:
170
171         $data->wanted(1, 6, 2) or die $data->error;
172
173   $data->reverse
174       Reverse the order of the data sets.
175
176   $data->copy_from($data_ref)
177       Copy an 'old' style GD::Graph data structure or another GD::Graph::Data
178       object into this object. This will remove the current data. Returns
179       undef on failure.
180
181   $data->copy()
182       Returns a copy of the object, or undef on failure.
183
184   $data->read(arguments)
185       Read a data set from a file. This will remove the current data. returns
186       undef on failure. This method uses the standard module Text::ParseWords
187       to parse lines. If you don't have this for some odd reason, don't use
188       this method, or your program will die.
189
190       Data file format: The default data file format is tab separated data
191       (which can be changed with the delimiter argument). Comment lines are
192       any lines that start with a #. In the following example I have replaced
193       literal tabs with <tab> for clarity
194
195         # This is a comment, and will be ignored
196         Jan<tab>12<tab>24
197         Feb<tab>13<tab>37
198         # March is missing
199         Mar<tab><tab>
200         Apr<tab>9<tab>18
201
202       Valid arguments are:
203
204       file, mandatory. The file name of the file to read from, or a reference
205       to a file handle or glob.
206
207         $data->read(file => '/data/foo.dat') or die $data->error;
208         $data->read(file => \*DATA) or die $data->error;
209         $data->read(file => $file_handle) or die $data->error;
210
211       no_comment, optional. Give this a true value if you don't want lines
212       with an initial # to be skipped.
213
214         $data->read(file => '/data/foo.dat', no_comment => 1);
215
216       delimiter, optional. A regular expression that will become the
217       delimiter instead of a single tab.
218
219         $data->read(file => '/data/foo.dat', delimiter => '\s+');
220         $data->read(file => '/data/foo.dat', delimiter => qr/\s+/);
221
222   $data->error() OR GD::Graph::Data->error()
223       Returns a list of all the errors that the current object has
224       accumulated. In scalar context, returns the last error. If called as a
225       class method it works at a class level.
226
227       This method is inherited, see GD::Graph::Error for more information.
228
229   $data->has_error() OR GD::Graph::Data->has_error()
230       Returns true if the object (or class) has errors pending, false if not.
231       In some cases (see "copy") this is the best way to check for errors.
232
233       This method is inherited, see GD::Graph::Error for more information.
234

NOTES

236       As with all Modules for Perl: Please stick to using the interface. If
237       you try to fiddle too much with knowledge of the internals of this
238       module, you could get burned. I may change them at any time.
239       Specifically, I probably won't always keep this implemented as an array
240       reference.
241

AUTHOR

243       Martien Verbruggen <mgjv@tradingpost.com.au>
244
245   Copyright
246       (c) Martien Verbruggen.
247
248       All rights reserved. This package is free software; you can
249       redistribute it and/or modify it under the same terms as Perl itself.
250

SEE ALSO

252       GD::Graph, GD::Graph::Error
253
254
255
256perl v5.32.0                      2020-07-28                    Graph::Data(3)
Impressum