GD::Graph::Data(3pm)

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

NOTES

260       As with all Modules for Perl: Please stick to using the interface. If
261       you try to fiddle too much with knowledge of the internals of this mod‐
262       ule, you could get burned. I may change them at any time.  Specifi‐
263       cally, I probably won't always keep this implemented as an array refer‐
264       ence.
265

AUTHOR

267       Martien Verbruggen <mgjv@tradingpost.com.au>
268
269       Copyright
270
271       (c) Martien Verbruggen.
272
273       All rights reserved. This package is free software; you can redis‐
274       tribute it and/or modify it under the same terms as Perl itself.
275