Provided by: libsvg-tt-graph-perl_0.21-1_all bug

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\n\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 configured 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,
           'y_label_formatter'   => sub { return @_ },
           'x_label_formatter'   => sub { return @_ },

           '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',

           # Stylesheet defaults
           'style_sheet'         => '/includes/graph.css', # internal stylesheet
           'random_colors'       => 0,
         });

       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.

       compress()
           Whether or not to compress the content of the SVG file (Compress::Zlib required).

       tidy()
           Whether or not to tidy the content of the SVG file (XML::Tidy required).

       style_sheet()
           Set the path to an external stylesheet, set to '' if you want to revert back to using
           the defaut internal version.

           The default stylesheet handles up to 12 data sets. All data series over the 12th will
           have no style and be in black. If you have over 12 data sets you can assign them all
           random colors (see the random_color() method) or create your own stylesheet and add
           the additional settings for the extra data sets.

           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.

       random_colors()
           Use random colors in the internal stylesheet.

       show_data_values()
           Show the value of each element of data on the graph.

       show_data_points()
           Show a small circle on the graph where the line goes from one point to the next.

       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).

       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 skipping missing data sections.  The expected
           form is:
               '<integer> [years | months | days | hours | minutes | seconds]'

       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 strftime() 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 | seconds]' 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.

       x_label_formatter ()
           A callback subroutine which will format a label on the x axis.  For example:

               $graph->x_label_formatter( sub { return '$' . $_[0] } );

       y_label_formatter()
           A callback subroutine which will format a label on the y axis.  For example:

               $graph->y_label_formatter( sub { return '$' . $_[0] } );

EXAMPLES

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

EXPORT

       None by default.

ACKNOWLEDGEMENTS

       Thanks to Foxtons for letting us put this on CPAN, Todd Caine for heads up on reparsing
       the template (but not using atm), David Meibusch for TimeSeries and a load of other ideas,
       Stephen Morgan for creating the TT template and SVG, and thanks for all the patches by
       Andrew Ruthven and others.

AUTHOR

       David Meibusch <David.Meibusch@adc.com>

MAINTAINER

       Florent Angly <florent.angly@gmail.com>

COPYRIGHT AND LICENSE

       Copyright (C) 2003, Leo Lapworth

       This module is free software; you can redistribute it or modify it under the same terms as
       Perl itself.

BUGS

       Please report any bugs or feature requests to bug-graph-svg-tt@rt.cpan.org, or through the
       web interface at http://rt.cpan.org.

       The Graph::SVG::TT development repository is located on GitHub at
       http://github.com/ranguard/svg-tt-graph <http://github.com/ranguard/svg-tt-graph>. Get the
       latest development version using: git clone git://github.com/ranguard/svg-tt-graph.git

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, SVG::TT::Graph::XY, Compress::Zlib,
       XML::Tidy