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 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 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 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 random_colors()
178 Use random colors in the internal stylesheet.
179 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 show_data_points()
185 Show a small circle on the graph where the line goes from one point
186 to the next.
187 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 data_value_format()
193 Format specifier to for data values (as per printf).
194 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 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 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 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 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 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 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 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 y_label_format()
236 Format string for presenting the Y axis labels (as per printf).
237 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 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 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 rotate_x_labels()
261 This turns the X axis labels by 90 degrees. Default it '0', to
262 turn on set to '1'.
263 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 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 show_x_title()
275 Whether to show the title under the X axis labels, default is 0,
276 set to '1' to show.
277 x_title()
279 What the title under X axis should be, e.g. 'Months'.
280 show_y_title()
282 Whether to show the title under the Y axis labels, default is 0,
283 set to '1' to show.
284 y_title()
286 What the title under Y axis should be, e.g. 'Sales in thousands'.
287 show_graph_title()
289 Whether to show a title on the graph, default is 0, set to '1' to
290 show.
291 graph_title()
293 What the title on the graph should be.
294 show_graph_subtitle()
296 Whether to show a subtitle on the graph, default is 0, set to '1'
297 to show.
298 graph_subtitle()
300 What the subtitle on the graph should be.
301 key()
303 Whether to show a key, defaults to 0, set to '1' if you want to
304 show it.
305 key_position()
307 Where the key should be positioned, defaults to 'right', set to
308 'bottom' if you want to move it.
309 x_label_formatter ()
311 A callback subroutine which will format a label on the x axis. For
312 example:
313 $graph->x_label_formatter( sub { return '$' . $_[0] } );
315 y_label_formatter()
317 A callback subroutine which will format a label on the y axis. For
318 example:
319 $graph->y_label_formatter( sub { return '$' . $_[0] } );
321
323 For examples look at the project home page
324 http://leo.cuckoo.org/projects/SVG-TT-Graph/
325
327 None by default.
328
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
333perl v5.34.0 2022-01-21 SVG::TT::Graph::TimeSeries(3)