1Graph::Data(3) User Contributed Perl Documentation Graph::Data(3)
2
6 GD::Graph::Data - Data set encapsulation for GD::Graph
7
9 use GD::Graph::Data;
10
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 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
24 use GD::Graph::Data;
25 use GD::Graph::bars;
26 my $data = GD::Graph::Data->new();
28 $data->read(file => '/data/sales.dat', delimiter => ',');
30 $data = $data->copy(wanted => [2, 4, 5]);
31 # 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 while (@row = $sth->fetchrow_array)
38 {
39 $data->add_point(@row);
40 }
41 my $chart = GD::Graph::bars->new();
43 my $gd = $chart->plot($data);
44 or for quick changes to legacy code
46 # Legacy code builds array like this
48 @data = ( [qw(Jan Feb Mar)], [1, 2, 3], [5, 4, 3], [6, 3, 7] );
49 # And we quickly need to do some manipulations on that
51 my $data = GD::Graph::Data->new();
52 $data->copy_from(\@data);
53 # And now do all the new stuff that's wanted.
55 while (@foo = bar_baz())
56 {
57 $data->add_point(@foo);
58 }
59
61 $data = GD::Graph::Data->new()
62 Create a new GD::Graph::Data object.
63 $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 $data->get_x($np)
69 Get the X value of point $np. See "set_x".
70 $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 $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 $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 $data->get_min_max_x
88 Returns a list of the minimum and maximum x value or the empty list on
89 failure.
90 $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 $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 $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 (X1, X2)
105 (Y11, Y12)
106 (Y21)
107 (Y31, Y32, Y33, Y34)
108 a $data->add_point(Xx, Y1x, Y2x, Y3x, Y4x) will result in
110 (X1, X2, Xx )
112 (Y11, Y12, Y1x)
113 (Y21, undef, Y2x)
114 (Y31, Y32, Y3x, Y34)
115 (undef, undef, Y4x)
116 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 $data->num_sets()
121 Returns the number of data sets.
122 $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 $data->x_values()
131 Return a list of all the X values.
132 $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 $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 $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 $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 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 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 $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 To remove all data sets except the first, sixth and second, in that
169 order:
170 $data->wanted(1, 6, 2) or die $data->error;
172 $data->reverse
174 Reverse the order of the data sets.
175 $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 $data->copy()
182 Returns a copy of the object, or undef on failure.
183 $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 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 # 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 Valid arguments are:
203 file, mandatory. The file name of the file to read from, or a reference
205 to a file handle or glob.
206 $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 no_comment, optional. Give this a true value if you don't want lines
212 with an initial # to be skipped.
213 $data->read(file => '/data/foo.dat', no_comment => 1);
215 delimiter, optional. A regular expression that will become the
217 delimiter instead of a single tab.
218 $data->read(file => '/data/foo.dat', delimiter => '\s+');
220 $data->read(file => '/data/foo.dat', delimiter => qr/\s+/);
221 $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 This method is inherited, see GD::Graph::Error for more information.
228 $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 This method is inherited, see GD::Graph::Error for more information.
234
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
243 Martien Verbruggen <mgjv@tradingpost.com.au>
244 Copyright
246 (c) Martien Verbruggen.
247 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
252 GD::Graph, GD::Graph::Error
253perl v5.12.0 2007-04-26 Graph::Data(3)