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           Set to "inline:<style>...</style>" with your CSS in between the
164           tags.  You can thus override the default style without requireing
165           an external URL.
166
167           The default stylesheet handles up to 12 data sets. All data series
168           over the 12th will have no style and be in black. If you have over
169           12 data sets you can assign them all random colors (see the
170           random_color() method) or create your own stylesheet and add the
171           additional settings for the extra data sets.
172
173           To create an external stylesheet create a graph using the default
174           internal version and copy the stylesheet section to an external
175           file and edit from there.
176
177       random_colors()
178           Use random colors in the internal stylesheet.
179
180       show_data_values()
181           Show the value of each element of data on the graph (or optionally
182           a user-defined label; see add_data).
183
184       show_data_points()
185           Show a small circle on the graph where the line goes from one point
186           to the next.
187
188       rollover_values()
189           Shows data values and data points when the mouse is over the point.
190           Used in combination with show_data_values and/or show_data_points.
191
192       data_value_format()
193           Format specifier to for data values (as per printf).
194
195       max_time_span()
196           Maximum timespan for a line between data points. If this span is
197           exceeded, the points are not connected.  This is useful for
198           skipping missing data sections.  The expected form is:
199               '<integer> [years | months | days | hours | minutes | seconds]'
200
201       stacked()
202           Accumulates each data set. (i.e. Each point increased by sum of all
203           previous series at same time). Default is 0, set to '1' to show.
204           All data series have the same number of points and must have the
205           same sequence of time values for this option.
206
207       min_scale_value()
208           The point at which the Y axis starts, defaults to '0', if set to ''
209           it will default to the minimum data value.
210
211       max_scale_value()
212           The point at which the Y axis ends, if set to '' it will default to
213           the maximum data value.
214
215       scale_divisions()
216           This defines the gap between markers on the Y axis, default is a
217           10th of the range, e.g. you will have 10 markers on the Y axis.
218           NOTE: do not set this too low - you are limited to 999 markers,
219           after that the graph won't generate.
220
221       show_x_labels()
222           Whether to show labels on the X axis or not, defaults to 1, set to
223           '0' if you want to turn them off.
224
225       x_label_format()
226           Format string for presenting the X axis labels.  The POSIX
227           strftime() function is used for formatting after calling the POSIX
228           tzset() function with the timezone specified in timescale_time_zone
229           if present (see strftime man pages and LC_TIME locale information).
230
231       show_y_labels()
232           Whether to show labels on the Y axis or not, defaults to 1, set to
233           '0' if you want to turn them off.
234
235       y_label_format()
236           Format string for presenting the Y axis labels (as per printf).
237
238       timescale_divisions()
239           This defines the gap between markers on the X axis.  Default is the
240           entire range (only start and end axis labels).  The expected form
241           is:
242               '<integer> [years | months | days | hours | minutes | seconds]'
243           The default time period if not provided is 'days'.  These time
244           periods are used by the DateTime::Duration methods.
245
246       timescale_time_zone
247           This determines the time zone used for the date intervals on the X
248           axis.  Values are those that DateTime accepts for its constructor's
249           'time_zone' parameter. The default is 'floating'.  If passing in
250           data for a different timezone than that set for your system, note
251           that you also must embed the timezone information into the values
252           passed to 'add_data', for example by formatting your DateTime
253           objects with DateTime::Format::RFC3339.
254
255       stagger_x_labels()
256           This puts the labels at alternative levels so if they are long
257           field names they will not overlap so easily.  Default it '0', to
258           turn on set to '1'.
259
260       rotate_x_labels()
261           This turns the X axis labels by 90 degrees.  Default it '0', to
262           turn on set to '1'.
263
264       min_timescale_value()
265           This sets the minimum timescale value (X axis).  Any data points
266           before this time will not be shown.  The date/time is expected in
267           ISO format: YYYY-MM-DD hh:mm:ss.
268
269       max_timescale_value()
270           This sets the maximum timescale value (X axis).  Any data points
271           after this time will not be shown.  The date/time is expected in
272           ISO format: YYYY-MM-DD hh:mm:ss.
273
274       show_x_title()
275           Whether to show the title under the X axis labels, default is 0,
276           set to '1' to show.
277
278       x_title()
279           What the title under X axis should be, e.g. 'Months'.
280
281       show_y_title()
282           Whether to show the title under the Y axis labels, default is 0,
283           set to '1' to show.
284
285       y_title()
286           What the title under Y axis should be, e.g. 'Sales in thousands'.
287
288       show_graph_title()
289           Whether to show a title on the graph, default is 0, set to '1' to
290           show.
291
292       graph_title()
293           What the title on the graph should be.
294
295       show_graph_subtitle()
296           Whether to show a subtitle on the graph, default is 0, set to '1'
297           to show.
298
299       graph_subtitle()
300           What the subtitle on the graph should be.
301
302       key()
303           Whether to show a key, defaults to 0, set to '1' if you want to
304           show it.
305
306       key_position()
307           Where the key should be positioned, defaults to 'right', set to
308           'bottom' if you want to move it.
309
310       x_label_formatter ()
311           A callback subroutine which will format a label on the x axis.  For
312           example:
313
314               $graph->x_label_formatter( sub { return '$' . $_[0] } );
315
316       y_label_formatter()
317           A callback subroutine which will format a label on the y axis.  For
318           example:
319
320               $graph->y_label_formatter( sub { return '$' . $_[0] } );
321

EXAMPLES

323       For examples look at the project home page
324       http://leo.cuckoo.org/projects/SVG-TT-Graph/
325

EXPORT

327       None by default.
328

SEE ALSO

330       SVG::TT::Graph, SVG::TT::Graph::Line, SVG::TT::Graph::Bar,
331       SVG::TT::Graph::BarHorizontal, SVG::TT::Graph::BarLine,
332       SVG::TT::Graph::Pie, SVG::TT::Graph::XY, Compress::Zlib, XML::Tidy
333
334
335
336perl v5.34.0                      2021-07-22     SVG::TT::Graph::TimeSeries(3)
Impressum