SVG::TT::Graph::TimeSeries
SVG::TT::Graph::TimeSUsersContributed Perl DocumSVG::TT::Graph::TimeSeries(3)
NAME
SVG::TT::Graph::TimeSeries - Create presentation quality SVG line
graphs of time series easily
SYNOPSIS
use SVG::TT::Graph::TimeSeries;
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);
my @data_disk = (’2003-09-03 09:00:00’,12,’2003-09-03 10:00:00’,26,’2003-09-03 11:00:00’,23);
my $graph = SVG::TT::Graph::TimeSeries->new({
’height’ => ’500’,
’width’ => ’300’,
});
$graph->add_data({
’data’ => \@data_cpu,
’title’ => ’CPU’,
});
$graph->add_data({
’data’ => \@data_disk,
’title’ => ’Disk’,
});
print "Content-type: image/svg+xml\r\n\r\n";
print $graph->burn();
DESCRIPTION
This object aims to allow you to easily create high quality SVG line
graphs of time series. You can either use the default style sheet or
supply your own. Either way there are many options which can be con-
figured to give you control over how the graph is generated - with or
without a key, data elements at each point, title, subtitle etc. All
times must be given a format parseable by HTTP::Date. The DateTime
module is used for all date/time calculations.
Note that the module is currently limited to the Unix-style epoch-
based date range limited by 32 bit signed integers (around 1902 to
2038).
METHODS
new()
use SVG::TT::Graph::TimeSeries;
my $graph = SVG::TT::Graph::TimeSeries->new({
# Optional - defaults shown
’height’ => 500,
’width’ => 300,
’show_y_labels’ => 1,
’scale_divisions’ => ’’,
’min_scale_value’ => 0,
’max_scale_value’ => ’’,
’show_x_labels’ => 1,
’timescale_divisions’ => ’’,
’min_timescale_value’ => ’’,
’max_timescale_value’ => ’’,
’x_label_format’ => ’%Y-%m-%d %H:%M:%S’,
’stagger_x_labels’ => 0,
’rotate_x_labels’ => 0,
’show_data_points’ => 1,
’show_data_values’ => 1,
’rollover_values’ => 0,
’area_fill’ => 0,
’show_x_title’ => 0,
’x_title’ => ’X Field names’,
’show_y_title’ => 0,
’y_title’ => ’Y Scale’,
’show_graph_title’ => 0,
’graph_title’ => ’Graph Title’,
’show_graph_subtitle’ => 0,
’graph_subtitle’ => ’Graph Sub Title’,
’key’ => 0,
’key_position’ => ’right’,
# Optional - defaults to using internal stylesheet
’style_sheet’ => ’/includes/graph.css’,
});
The constructor takes a hash reference with values defaulted to those
shown above - with the exception of style_sheet which defaults to
using the internal style sheet.
add_data()
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);
or
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]);
$graph->add_data({
’data’ => \@data_cpu,
’title’ => ’CPU’,
});
This method allows you to add data to the graph object. The data is
expected to be a list of time, value pairs. It can be called several
times to add more data sets in.
clear_data()
my $graph->clear_data();
This method removes all data from the object so that you can reuse it
to create a new graph but with the same config options.
burn()
print $graph->burn();
This method processes the template with the data and config which has
been set and returns the resulting SVG.
This method will croak unless at least one data set has been added to
the graph object.
config methods
my $value = $graph->method();
my $confirmed_new_value = $graph->method($value);
The following is a list of the methods which are available to change
the config of the graph object after it has been created.
height()
Set the height of the graph box, this is the total height of the
SVG box created - not the graph it self which auto scales to fix
the space.
width()
Set the width of the graph box, this is the total width of the SVG
box created - not the graph it self which auto scales to fix the
space.
style_sheet()
Set the path to an external stylesheet, set to ’’ if you want to
revert back to using the defaut internal version.
To create an external stylesheet create a graph using the default
internal version and copy the stylesheet section to an external
file and edit from there.
show_data_values()
Show the value of each element of data on the graph.
rollover_values()
Shows data values and data points when the mouse is over the
point. Used in combination with show_data_values and/or
show_data_points.
data_value_format()
Format specifier to for data values (as per printf).
show_data_points()
Show a small circle on the graph where the line goes from one
point to the next.
max_time_span()
Maximum timespan for a line between data points. If this span is
exceeded, the points are not connected. This is useful for skip-
ping missing data sections. The expected form is:
’<integer> [years │ months │ days │ hours │ minutes │ sec-
onds]’
stacked()
Accumulates each data set. (i.e. Each point increased by sum of
all previous series at same time). Default is 0, set to ’1’ to
show. All data series have the same number of points and must
have the same sequence of time values for this option.
min_scale_value()
The point at which the Y axis starts, defaults to ’0’, if set to
’’ it will default to the minimum data value.
max_scale_value()
The point at which the Y axis ends, if set to ’’ it will default
to the maximum data value.
scale_divisions()
This defines the gap between markers on the Y axis, default is a
10th of the range, e.g. you will have 10 markers on the Y axis.
NOTE: do not set this too low - you are limited to 999 markers,
after that the graph won’t generate.
show_x_labels()
Whether to show labels on the X axis or not, defaults to 1, set to
’0’ if you want to turn them off.
x_label_format()
Format string for presenting the X axis labels. The POSIX strf-
time() function is used for formatting (see strftime man pages and
LC_TIME locale information).
show_y_labels()
Whether to show labels on the Y axis or not, defaults to 1, set to
’0’ if you want to turn them off.
y_label_format()
Format string for presenting the Y axis labels (as per printf).
timescale_divisions()
This defines the gap between markers on the X axis. Default is
the entire range (only start and end axis labels). The expected
form is:
’<integer> [years │ months │ days │ hours │ minutes │ sec-
onds]’ The default time period if not provided is ’days’. These
time periods are used by the DateTime::Duration methods.
stagger_x_labels()
This puts the labels at alternative levels so if they are long
field names they will not overlap so easily. Default it ’0’, to
turn on set to ’1’.
rotate_x_labels()
This turns the X axis labels by 90 degrees. Default it ’0’, to
turn on set to ’1’.
min_timescale_value()
This sets the minimum timescale value (X axis). Any data points
before this time will not be shown. The date/time is expected in
ISO format: YYYY-MM-DD hh:mm:ss.
max_timescale_value()
This sets the maximum timescale value (X axis). Any data points
after this time will not be shown. The date/time is expected in
ISO format: YYYY-MM-DD hh:mm:ss.
show_x_title()
Whether to show the title under the X axis labels, default is 0,
set to ’1’ to show.
x_title()
What the title under X axis should be, e.g. ’Months’.
show_y_title()
Whether to show the title under the Y axis labels, default is 0,
set to ’1’ to show.
y_title()
What the title under Y axis should be, e.g. ’Sales in thousands’.
show_graph_title()
Whether to show a title on the graph, default is 0, set to ’1’ to
show.
graph_title()
What the title on the graph should be.
show_graph_subtitle()
Whether to show a subtitle on the graph, default is 0, set to ’1’
to show.
graph_subtitle()
What the subtitle on the graph should be.
key()
Whether to show a key, defaults to 0, set to ’1’ if you want to
show it.
key_position()
Where the key should be positioned, defaults to ’right’, set to
’bottom’ if you want to move it.
NOTES
The default stylesheet handles upto 12 data sets, if you use more you
must create your own stylesheet and add the additional settings for
the extra data sets. You will know if you go over 12 data sets as they
will have no style and be in black.
EXAMPLES
For examples look at the project home page
http://leo.cuckoo.org/projects/SVG-TT-Graph/
EXPORT
None by default.
ACKNOWLEDGEMENTS
Leo Lapworth for SVG-TT-Graph. Stephen Morgan for creating the TT
template and SVG.
AUTHOR
David Meibusch (David.Meibusch@adc.com)
SEE ALSO
SVG::TT::Graph, SVG::TT::Graph::Line, SVG::TT::Graph::Bar,
SVG::TT::Graph::BarHorizontal, SVG::TT::Graph::BarLine,
SVG::TT::Graph::Pie
perl v5.8.8 2009-02-16 SVG::TT::Graph::TimeSeries(3)
