1SVG::TT::Graph::TimeSerUiseesr(3C)ontributed Perl DocumeSnVtGa:t:iToTn::Graph::TimeSeries(3)
2
6 SVG::TT::Graph::TimeSeries - Create presentation quality SVG line
7 graphs of time series easily
8
10 use SVG::TT::Graph::TimeSeries;
11 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 my $graph = SVG::TT::Graph::TimeSeries->new({
16 'height' => '500',
17 'width' => '300',
18 });
19 $graph->add_data({
21 'data' => \@data_cpu,
22 'title' => 'CPU',
23 });
24 $graph->add_data({
26 'data' => \@data_disk,
27 'title' => 'Disk',
28 });
29 print "Content-type: image/svg+xml\n\n";
31 print $graph->burn();
32
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 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
46 new()
47 use SVG::TT::Graph::TimeSeries;
48 my $graph = SVG::TT::Graph::TimeSeries->new({
50 # Optional - defaults shown
52 'height' => 500,
53 'width' => 300,
54 'show_y_labels' => 1,
56 'scale_divisions' => '',
57 'min_scale_value' => 0,
58 'max_scale_value' => '',
59 '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 'show_data_points' => 1,
71 'show_data_values' => 1,
72 'rollover_values' => 0,
73 'area_fill' => 0,
75 'show_x_title' => 0,
77 'x_title' => 'X Field names',
78 'show_y_title' => 0,
80 'y_title' => 'Y Scale',
81 '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 # Stylesheet defaults
90 'style_sheet' => '/includes/graph.css', # internal stylesheet
91 'random_colors' => 0,
92 });
93 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 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 $graph->add_data({
106 'data' => \@data_cpu,
107 'title' => 'CPU',
108 });
109 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 clear_data()
120 my $graph->clear_data();
121 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 burn()
126 print $graph->burn();
127 This method processes the template with the data and config which has
129 been set and returns the resulting SVG.
130 This method will croak unless at least one data set has been added to
132 the graph object.
133 config methods
135 my $value = $graph->method();
136 my $confirmed_new_value = $graph->method($value);
137 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 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 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 compress()
152 Whether or not to compress the content of the SVG file
153 (Compress::Zlib required).
154 tidy()
156 Whether or not to tidy the content of the SVG file (XML::Tidy
157 required).
158 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 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 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 random_colors()
174 Use random colors in the internal stylesheet.
175 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 show_data_points()
181 Show a small circle on the graph where the line goes from one point
182 to the next.
183 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 data_value_format()
189 Format specifier to for data values (as per printf).
190 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 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 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 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 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 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 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 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 y_label_format()
231 Format string for presenting the Y axis labels (as per printf).
232 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 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 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 rotate_x_labels()
252 This turns the X axis labels by 90 degrees. Default it '0', to
253 turn on set to '1'.
254 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 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 show_x_title()
266 Whether to show the title under the X axis labels, default is 0,
267 set to '1' to show.
268 x_title()
270 What the title under X axis should be, e.g. 'Months'.
271 show_y_title()
273 Whether to show the title under the Y axis labels, default is 0,
274 set to '1' to show.
275 y_title()
277 What the title under Y axis should be, e.g. 'Sales in thousands'.
278 show_graph_title()
280 Whether to show a title on the graph, default is 0, set to '1' to
281 show.
282 graph_title()
284 What the title on the graph should be.
285 show_graph_subtitle()
287 Whether to show a subtitle on the graph, default is 0, set to '1'
288 to show.
289 graph_subtitle()
291 What the subtitle on the graph should be.
292 key()
294 Whether to show a key, defaults to 0, set to '1' if you want to
295 show it.
296 key_position()
298 Where the key should be positioned, defaults to 'right', set to
299 'bottom' if you want to move it.
300 x_label_formatter ()
302 A callback subroutine which will format a label on the x axis. For
303 example:
304 $graph->x_label_formatter( sub { return '$' . $_[0] } );
306 y_label_formatter()
308 A callback subroutine which will format a label on the y axis. For
309 example:
310 $graph->y_label_formatter( sub { return '$' . $_[0] } );
312
314 For examples look at the project home page
315 http://leo.cuckoo.org/projects/SVG-TT-Graph/
316
318 None by default.
319
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
324perl v5.28.0 2015-04-14 SVG::TT::Graph::TimeSeries(3)