1SVG::TT::Graph::TimeSerUiseesr(3C)ontributed Perl DocumeSnVtGa:t:iToTn::Graph::TimeSeries(3)
2
3
4

NAME

6       SVG::TT::Graph::TimeSeries - Create presentation quality SVG line
7       graphs of time series easily
8

SYNOPSIS

10         use SVG::TT::Graph::TimeSeries;
11
12         my @data_cpu = ('2003-09-03 09:30:00',23,'2003-09-03 09:45:00',54,'2003-09-03 10:00:00',67,'2003-09-03 10:15:00',12);
13         my @data_disk = ('2003-09-03 09:00:00',12,'2003-09-03 10:00:00',26,'2003-09-03 11:00:00',23);
14
15         my $graph = SVG::TT::Graph::TimeSeries->new({
16           'height' => '500',
17           'width'  => '300',
18         });
19
20         $graph->add_data({
21           'data'  => \@data_cpu,
22           'title' => 'CPU',
23         });
24
25         $graph->add_data({
26           'data'  => \@data_disk,
27           'title' => 'Disk',
28         });
29
30         print "Content-type: image/svg+xml\n\n";
31         print $graph->burn();
32

DESCRIPTION

34       This object aims to allow you to easily create high quality SVG line
35       graphs of time series. You can either use the default style sheet or
36       supply your own. Either way there are many options which can be
37       configured to give you control over how the graph is generated - with
38       or without a key, data elements at each point, title, subtitle etc.
39       All times must be given a format parseable by HTTP::Date.  The DateTime
40       module is used for all date/time calculations.
41
42       Note that the module is currently limited to the Unix-style epoch-based
43       date range limited by 32 bit signed integers (around 1902 to 2038).
44

METHODS

46   new()
47         use SVG::TT::Graph::TimeSeries;
48
49         my $graph = SVG::TT::Graph::TimeSeries->new({
50
51           # Optional - defaults shown
52           'height'              => 500,
53           'width'               => 300,
54
55           'show_y_labels'       => 1,
56           'scale_divisions'     => '',
57           'min_scale_value'     => 0,
58           'max_scale_value'     => '',
59
60           'show_x_labels'       => 1,
61           'timescale_divisions' => '',
62           'min_timescale_value' => '',
63           'max_timescale_value' => '',
64           'x_label_format'      => '%Y-%m-%d %H:%M:%S',
65           'stagger_x_labels'    => 0,
66           'rotate_x_labels'     => 0,
67           'y_label_formatter'   => sub { return @_ },
68           'x_label_formatter'   => sub { return @_ },
69
70           'show_data_points'    => 1,
71           'show_data_values'    => 1,
72           'rollover_values'     => 0,
73
74           'area_fill'           => 0,
75
76           'show_x_title'        => 0,
77           'x_title'             => 'X Field names',
78
79           'show_y_title'        => 0,
80           'y_title'             => 'Y Scale',
81
82           'show_graph_title'    => 0,
83           'graph_title'         => 'Graph Title',
84           'show_graph_subtitle' => 0,
85           'graph_subtitle'      => 'Graph Sub Title',
86           'key'                 => 0,
87           'key_position'        => 'right',
88
89           # Stylesheet defaults
90           'style_sheet'         => '/includes/graph.css', # internal stylesheet
91           'random_colors'       => 0,
92         });
93
94       The constructor takes a hash reference with values defaulted to those
95       shown above - with the exception of style_sheet which defaults to using
96       the internal style sheet.
97
98   add_data()
99         my @data_cpu = ('2003-09-03 09:30:00',23,'2003-09-03 09:45:00',54,'2003-09-03 10:00:00',67,'2003-09-03 10:15:00',12);
100         or
101         my @data_cpu = (['2003-09-03 09:30:00',23],['2003-09-03 09:45:00',54],['2003-09-03 10:00:00',67],['2003-09-03 10:15:00',12]);
102         or
103         my @data_cpu = (['2003-09-03 09:30:00',23,'23%'],['2003-09-03 09:45:00',54,'54%'],['2003-09-03 10:00:00',67,'67%'],['2003-09-03 10:15:00',12,'12%']);
104
105         $graph->add_data({
106           'data' => \@data_cpu,
107           'title' => 'CPU',
108         });
109
110       This method allows you to add data to the graph object.  The data are
111       expected to be either a list of scalars (in which case pairs of
112       elements are taken to be time, value pairs) or a list of array
113       references.  In the latter case, the first two elements in each
114       referenced array are taken to be time and value, and the optional third
115       element (if present) is used as the text to display for that point for
116       show_data_values and rollover_values (otherwise the value itself is
117       displayed).  It can be called several times to add more data sets in.
118
119   clear_data()
120         my $graph->clear_data();
121
122       This method removes all data from the object so that you can reuse it
123       to create a new graph but with the same config options.
124
125   burn()
126         print $graph->burn();
127
128       This method processes the template with the data and config which has
129       been set and returns the resulting SVG.
130
131       This method will croak unless at least one data set has been added to
132       the graph object.
133
134   config methods
135         my $value = $graph->method();
136         my $confirmed_new_value = $graph->method($value);
137
138       The following is a list of the methods which are available to change
139       the config of the graph object after it has been created.
140
141       height()
142           Set the height of the graph box, this is the total height of the
143           SVG box created - not the graph it self which auto scales to fix
144           the space.
145
146       width()
147           Set the width of the graph box, this is the total width of the SVG
148           box created - not the graph it self which auto scales to fix the
149           space.
150
151       compress()
152           Whether or not to compress the content of the SVG file
153           (Compress::Zlib required).
154
155       tidy()
156           Whether or not to tidy the content of the SVG file (XML::Tidy
157           required).
158
159       style_sheet()
160           Set the path to an external stylesheet, set to '' if you want to
161           revert back to using the default internal version.
162
163           The default stylesheet handles up to 12 data sets. All data series
164           over the 12th will have no style and be in black. If you have over
165           12 data sets you can assign them all random colors (see the
166           random_color() method) or create your own stylesheet and add the
167           additional settings for the extra data sets.
168
169           To create an external stylesheet create a graph using the default
170           internal version and copy the stylesheet section to an external
171           file and edit from there.
172
173       random_colors()
174           Use random colors in the internal stylesheet.
175
176       show_data_values()
177           Show the value of each element of data on the graph (or optionally
178           a user-defined label; see add_data).
179
180       show_data_points()
181           Show a small circle on the graph where the line goes from one point
182           to the next.
183
184       rollover_values()
185           Shows data values and data points when the mouse is over the point.
186           Used in combination with show_data_values and/or show_data_points.
187
188       data_value_format()
189           Format specifier to for data values (as per printf).
190
191       max_time_span()
192           Maximum timespan for a line between data points. If this span is
193           exceeded, the points are not connected.  This is useful for
194           skipping missing data sections.  The expected form is:
195               '<integer> [years | months | days | hours | minutes | seconds]'
196
197       stacked()
198           Accumulates each data set. (i.e. Each point increased by sum of all
199           previous series at same time). Default is 0, set to '1' to show.
200           All data series have the same number of points and must have the
201           same sequence of time values for this option.
202
203       min_scale_value()
204           The point at which the Y axis starts, defaults to '0', if set to ''
205           it will default to the minimum data value.
206
207       max_scale_value()
208           The point at which the Y axis ends, if set to '' it will default to
209           the maximum data value.
210
211       scale_divisions()
212           This defines the gap between markers on the Y axis, default is a
213           10th of the range, e.g. you will have 10 markers on the Y axis.
214           NOTE: do not set this too low - you are limited to 999 markers,
215           after that the graph won't generate.
216
217       show_x_labels()
218           Whether to show labels on the X axis or not, defaults to 1, set to
219           '0' if you want to turn them off.
220
221       x_label_format()
222           Format string for presenting the X axis labels.  The POSIX
223           strftime() function is used for formatting (see strftime man pages
224           and LC_TIME locale information).
225
226       show_y_labels()
227           Whether to show labels on the Y axis or not, defaults to 1, set to
228           '0' if you want to turn them off.
229
230       y_label_format()
231           Format string for presenting the Y axis labels (as per printf).
232
233       timescale_divisions()
234           This defines the gap between markers on the X axis.  Default is the
235           entire range (only start and end axis labels).  The expected form
236           is:
237               '<integer> [years | months | days | hours | minutes | seconds]'
238           The default time period if not provided is 'days'.  These time
239           periods are used by the DateTime::Duration methods.
240
241       timescale_time_zone
242           This determines the time zone used for the date intervals on the X
243           axis.  Values are those that DateTime accepts for its constructor's
244           'time_zone' parameter. The default is 'floating'.
245
246       stagger_x_labels()
247           This puts the labels at alternative levels so if they are long
248           field names they will not overlap so easily.  Default it '0', to
249           turn on set to '1'.
250
251       rotate_x_labels()
252           This turns the X axis labels by 90 degrees.  Default it '0', to
253           turn on set to '1'.
254
255       min_timescale_value()
256           This sets the minimum timescale value (X axis).  Any data points
257           before this time will not be shown.  The date/time is expected in
258           ISO format: YYYY-MM-DD hh:mm:ss.
259
260       max_timescale_value()
261           This sets the maximum timescale value (X axis).  Any data points
262           after this time will not be shown.  The date/time is expected in
263           ISO format: YYYY-MM-DD hh:mm:ss.
264
265       show_x_title()
266           Whether to show the title under the X axis labels, default is 0,
267           set to '1' to show.
268
269       x_title()
270           What the title under X axis should be, e.g. 'Months'.
271
272       show_y_title()
273           Whether to show the title under the Y axis labels, default is 0,
274           set to '1' to show.
275
276       y_title()
277           What the title under Y axis should be, e.g. 'Sales in thousands'.
278
279       show_graph_title()
280           Whether to show a title on the graph, default is 0, set to '1' to
281           show.
282
283       graph_title()
284           What the title on the graph should be.
285
286       show_graph_subtitle()
287           Whether to show a subtitle on the graph, default is 0, set to '1'
288           to show.
289
290       graph_subtitle()
291           What the subtitle on the graph should be.
292
293       key()
294           Whether to show a key, defaults to 0, set to '1' if you want to
295           show it.
296
297       key_position()
298           Where the key should be positioned, defaults to 'right', set to
299           'bottom' if you want to move it.
300
301       x_label_formatter ()
302           A callback subroutine which will format a label on the x axis.  For
303           example:
304
305               $graph->x_label_formatter( sub { return '$' . $_[0] } );
306
307       y_label_formatter()
308           A callback subroutine which will format a label on the y axis.  For
309           example:
310
311               $graph->y_label_formatter( sub { return '$' . $_[0] } );
312

EXAMPLES

314       For examples look at the project home page
315       http://leo.cuckoo.org/projects/SVG-TT-Graph/
316

EXPORT

318       None by default.
319

SEE ALSO

321       SVG::TT::Graph, SVG::TT::Graph::Line, SVG::TT::Graph::Bar,
322       SVG::TT::Graph::BarHorizontal, SVG::TT::Graph::BarLine,
323       SVG::TT::Graph::Pie, SVG::TT::Graph::XY, Compress::Zlib, XML::Tidy
324
325
326
327perl v5.28.0                      2015-04-14     SVG::TT::Graph::TimeSeries(3)
Impressum