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 'show_data_points' => 1,
69 'show_data_values' => 1,
70 'rollover_values' => 0,
71 'area_fill' => 0,
73 'show_x_title' => 0,
75 'x_title' => 'X Field names',
76 'show_y_title' => 0,
78 'y_title' => 'Y Scale',
79 'show_graph_title' => 0,
81 'graph_title' => 'Graph Title',
82 'show_graph_subtitle' => 0,
83 'graph_subtitle' => 'Graph Sub Title',
84 'key' => 0,
85 'key_position' => 'right',
86 # Stylesheet defaults
88 'style_sheet' => '/includes/graph.css', # internal stylesheet
89 'random_colors' => 0,
90 });
91 The constructor takes a hash reference with values defaulted to those
93 shown above - with the exception of style_sheet which defaults to using
94 the internal style sheet.
95 add_data()
97 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);
98 or
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 $graph->add_data({
102 'data' => \@data_cpu,
103 'title' => 'CPU',
104 });
105 This method allows you to add data to the graph object. The data is
107 expected to be a list of time, value pairs. It can be called several
108 times to add more data sets in.
109 clear_data()
111 my $graph->clear_data();
112 This method removes all data from the object so that you can reuse it
114 to create a new graph but with the same config options.
115 burn()
117 print $graph->burn();
118 This method processes the template with the data and config which has
120 been set and returns the resulting SVG.
121 This method will croak unless at least one data set has been added to
123 the graph object.
124 config methods
126 my $value = $graph->method();
127 my $confirmed_new_value = $graph->method($value);
128 The following is a list of the methods which are available to change
130 the config of the graph object after it has been created.
131 height()
133 Set the height of the graph box, this is the total height of the
134 SVG box created - not the graph it self which auto scales to fix
135 the space.
136 width()
138 Set the width of the graph box, this is the total width of the SVG
139 box created - not the graph it self which auto scales to fix the
140 space.
141 compress()
143 Whether or not to compress the content of the SVG file
144 (Compress::Zlib required).
145 tidy()
147 Whether or not to tidy the content of the SVG file (XML::Tidy
148 required).
149 style_sheet()
151 Set the path to an external stylesheet, set to '' if you want to
152 revert back to using the defaut internal version.
153 The default stylesheet handles up to 12 data sets. All data series
155 over the 12th will have no style and be in black. If you have over
156 12 data sets you can assign them all random colors (see the
157 random_color() method) or create your own stylesheet and add the
158 additional settings for the extra data sets.
159 To create an external stylesheet create a graph using the default
161 internal version and copy the stylesheet section to an external
162 file and edit from there.
163 random_colors()
165 Use random colors in the internal stylesheet.
166 show_data_values()
168 Show the value of each element of data on the graph.
169 show_data_points()
171 Show a small circle on the graph where the line goes from one point
172 to the next.
173 rollover_values()
175 Shows data values and data points when the mouse is over the point.
176 Used in combination with show_data_values and/or show_data_points.
177 data_value_format()
179 Format specifier to for data values (as per printf).
180 max_time_span()
182 Maximum timespan for a line between data points. If this span is
183 exceeded, the points are not connected. This is useful for
184 skipping missing data sections. The expected form is:
185 '<integer> [years | months | days | hours | minutes | seconds]'
186 stacked()
188 Accumulates each data set. (i.e. Each point increased by sum of all
189 previous series at same time). Default is 0, set to '1' to show.
190 All data series have the same number of points and must have the
191 same sequence of time values for this option.
192 min_scale_value()
194 The point at which the Y axis starts, defaults to '0', if set to ''
195 it will default to the minimum data value.
196 max_scale_value()
198 The point at which the Y axis ends, if set to '' it will default to
199 the maximum data value.
200 scale_divisions()
202 This defines the gap between markers on the Y axis, default is a
203 10th of the range, e.g. you will have 10 markers on the Y axis.
204 NOTE: do not set this too low - you are limited to 999 markers,
205 after that the graph won't generate.
206 show_x_labels()
208 Whether to show labels on the X axis or not, defaults to 1, set to
209 '0' if you want to turn them off.
210 x_label_format()
212 Format string for presenting the X axis labels. The POSIX
213 strftime() function is used for formatting (see strftime man pages
214 and LC_TIME locale information).
215 show_y_labels()
217 Whether to show labels on the Y axis or not, defaults to 1, set to
218 '0' if you want to turn them off.
219 y_label_format()
221 Format string for presenting the Y axis labels (as per printf).
222 timescale_divisions()
224 This defines the gap between markers on the X axis. Default is the
225 entire range (only start and end axis labels). The expected form
226 is:
227 '<integer> [years | months | days | hours | minutes | seconds]'
228 The default time period if not provided is 'days'. These time
229 periods are used by the DateTime::Duration methods.
230 stagger_x_labels()
232 This puts the labels at alternative levels so if they are long
233 field names they will not overlap so easily. Default it '0', to
234 turn on set to '1'.
235 rotate_x_labels()
237 This turns the X axis labels by 90 degrees. Default it '0', to
238 turn on set to '1'.
239 min_timescale_value()
241 This sets the minimum timescale value (X axis). Any data points
242 before this time will not be shown. The date/time is expected in
243 ISO format: YYYY-MM-DD hh:mm:ss.
244 max_timescale_value()
246 This sets the maximum timescale value (X axis). Any data points
247 after this time will not be shown. The date/time is expected in
248 ISO format: YYYY-MM-DD hh:mm:ss.
249 show_x_title()
251 Whether to show the title under the X axis labels, default is 0,
252 set to '1' to show.
253 x_title()
255 What the title under X axis should be, e.g. 'Months'.
256 show_y_title()
258 Whether to show the title under the Y axis labels, default is 0,
259 set to '1' to show.
260 y_title()
262 What the title under Y axis should be, e.g. 'Sales in thousands'.
263 show_graph_title()
265 Whether to show a title on the graph, default is 0, set to '1' to
266 show.
267 graph_title()
269 What the title on the graph should be.
270 show_graph_subtitle()
272 Whether to show a subtitle on the graph, default is 0, set to '1'
273 to show.
274 graph_subtitle()
276 What the subtitle on the graph should be.
277 key()
279 Whether to show a key, defaults to 0, set to '1' if you want to
280 show it.
281 key_position()
283 Where the key should be positioned, defaults to 'right', set to
284 'bottom' if you want to move it.
285
287 For examples look at the project home page
288 http://leo.cuckoo.org/projects/SVG-TT-Graph/
289
291 None by default.
292
294 Leo Lapworth for SVG-TT-Graph. Stephen Morgan for creating the TT
295 template and SVG.
296
298 David Meibusch (David.Meibusch@adc.com)
299
301 SVG::TT::Graph, SVG::TT::Graph::Line, SVG::TT::Graph::Bar,
302 SVG::TT::Graph::BarHorizontal, SVG::TT::Graph::BarLine,
303 SVG::TT::Graph::Pie, Compress::Zlib, XML::Tidy
304perl v5.12.0 2010-04-17 SVG::TT::Graph::TimeSeries(3)