SVG::T...Series(3pm)

📦

version 1.04 · 4 versions

1.04 · debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
1.04 · fedora 43
1.04 · ubuntu jammy
1.04 · fedora 44

, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

SVG::T...Series(3pm) 💖

okay bestie, welcome to the manual page for SVG::T...Series(3pm) from the User Contributed Perl Documentation collection — and yes, you read that right, that's literally how the header renders, it's giving ✨truncated✨ and we're just gonna vibe with it 🫶

🌸 NAME 🌸

SVG::TT::Graph::TimeSeries — make presentation quality SVG line graphs of time series, and make them easily 💅

Like. That's the whole assignment. Line graphs. Time series. Looking expensive. Slay.

✨ SYNOPSIS ✨

here's the whole vibe, copy-paste coded for your convenience:

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();

see how the data is just timestamp, value, timestamp, value back to back?? alternating?? no cap that's the whole format 😭 beautiful honestly

and then you burn() it and print your content type and boom 💥 graph. iconic.

🦋 DESCRIPTION 🦋

okay so the whole point of this object is to let you easily create high quality SVG line graphs of time series. that's it. that's the mission. 🎀

you've got options on the styling front:

use the default style sheet and just go, or
supply your own if you're feeling like a main character 💅

either way there are many options you can configure, and they give you control over how the graph gets generated — with or without a key, data elements at each point, title, subtitle, etc. ✨

heads up bestie: all times must be given a format that's parseable by HTTP::Date. that's non-negotiable, she's picky 🙈

and for all the date/time math under the hood? that's DateTime doing the work. every single calculation. she's carrying the team fr fr 🫶

⚠️ important caveat, do not skip this one: the module is currently limited to the Unix-style epoch-based date range limited by 32 bit signed integers — which lands you around 1902 to 2038. so like, don't come crying to me in 2039 😭💀

more of this manual is coming, bestie — this was just part 1, don't go anywhere 🧚

💖 METHODS 💖

✨ `new()` — the constructor, aka where it all starts ✨

  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 all the values defaulted to exactly what's up there 👆 — with one exception: style_sheet, which defaults to using the internal style sheet instead. Bestie, everything else just works out of the box, no cap. 🫶

🌸 `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]);
  or
  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%']);

  $graph->add_data({
    'data' => \@data_cpu,
    'title' => 'CPU',
  });

This method lets you add data to the graph object. 🦋 Here's the tea on the shape of the data: it's expected to be either a list of scalars — in which case pairs of elements get read as time, value pairs — or a list of array references. In that second case, the first two elements in each referenced array are taken as the time and the value, and the optional third element (only if it's actually there) is used as the text to display for that point for show_data_values and rollover_values — otherwise the value itself is what gets displayed. You can call this several times to pile more data sets in. ✨

🎀 `clear_data()` 🎀

  my $graph->clear_data();

This one removes all data from the object so you can reuse it to make a brand new graph while keeping the same config options. Recycle era 💅

🔥 `burn()` 🔥

  print $graph->burn();

This processes the template with the data and config that's been set, and returns the resulting SVG. That's the whole point, bestie, this is the moment. 👑

⚠️ Heads up: this method will croak unless at least one data set has been added to the graph object. No data = no graph, no exceptions. 😭

💜 config methods 💜

  my $value = $graph->method();
  my $confirmed_new_value = $graph->method($value);

Here's the full lineup of methods you can use to change the config of the graph object after it's been created. Iconic behaviour, honestly. 🌈

`height()`

Set the height of the graph box — and yes this is the total height of the SVG box that gets created, not the graph itself, which auto scales to fit the space. 🦋

`width()`

Set the width of the graph box — again, the total width of the SVG box that gets created, not the graph itself, which auto scales to fit 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, or set it to '' if you wanna revert back to using the default internal version. 💅

You can also set it to "inline:<style>...</style>" with your CSS tucked in between the tags — so you can override the default style without needing an external URL. Obsessed with the convenience.

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

To create an external stylesheet: create a graph using the default internal version, copy the stylesheet section to an external file, and edit from there. 🎀

`random_colors()`

Use random colors in the internal stylesheet. Surprise palette, let's go 🌈

`show_data_values()`

Show the value of each element of data on the graph (or optionally a user-defined label; see add_data).

`show_data_points()`

Show a small circle on the graph where the line goes from one point to the next. Cute little dots, lowkey satisfying. ⭐

`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. 🫶

⚠️ For this option, all data series must have the same number of points and must have the same sequence of time values. No mixing and matching, bestie.

`min_scale_value()`

The point at which the Y axis starts, defaults to '0' — and if you set it to '' it'll default to the minimum data value. 🦋

`max_scale_value()`

The point at which the Y axis ends — and if you set it to '' it'll 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'll have 10 markers on the Y axis.

🚨 NOTE: do not set this too low — you are limited to 999 markers, and after that the graph won't generate. Do not test fate, she will not pass the vibe check.

`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 after calling the POSIX tzset() function with the timezone specified in timescale_time_zone if present (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 (so 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. 🌸

`timescale_time_zone`

This determines the time zone used for the date intervals on the X axis. Values are those that DateTime accepts for its constructor's 'time_zone' parameter. The default is 'floating'.

💡 If you're passing in data for a different timezone than the one set for your system, note that you also must embed the timezone information into the values passed to add_data — for example by formatting your DateTime objects with DateTime::Format::RFC3339. Don't skip this step, iykyk. 🙈

`stagger_x_labels()`

This puts the labels at alternative levels, so if they're long field names they won't overlap so easily. Default is '0', to turn on set to '1'. ✨

`rotate_x_labels()`

This turns the X axis labels by 90 degrees. Default is '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/ — go peek, it's giving inspo. 💖

🎁 EXPORT 🎁

None by default. Nada. Nothing exported, it's a clean slate, bestie. ✨

👀 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

That's the whole page, bestie — this one's from perl v5.36.0, dated 2022-11-19, and it's the SVG::T...Series(3pm) manual. Go make some truly gorgeous time series graphs, you absolute icon. 💅✨🦋

📦 where this page comes from

debian bookworm: libsvg-tt-graph-perl 1.04-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
debian trixie: libsvg-tt-graph-perl 1.04-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu noble: libsvg-tt-graph-perl 1.04-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu resolute: libsvg-tt-graph-perl 1.04-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu stonking: libsvg-tt-graph-perl 1.04-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

SVG::T...Series(3pm)

SVG::T...Series(3pm) 💖

🌸 NAME 🌸

✨ SYNOPSIS ✨

🦋 DESCRIPTION 🦋

💖 METHODS 💖

✨ new() — the constructor, aka where it all starts ✨

🌸 add_data() 🌸

🎀 clear_data() 🎀

🔥 burn() 🔥

💜 config methods 💜

height()

width()

compress()

tidy()

style_sheet()

random_colors()

show_data_values()

show_data_points()

rollover_values()

data_value_format()

max_time_span()

stacked()

min_scale_value()

max_scale_value()

scale_divisions()

show_x_labels()

x_label_format()

show_y_labels()

y_label_format()

timescale_divisions()

timescale_time_zone

stagger_x_labels()

rotate_x_labels()

min_timescale_value()

max_timescale_value()

show_x_title()

x_title()

show_y_title()

y_title()

show_graph_title()

graph_title()

show_graph_subtitle()

graph_subtitle()

key()

key_position()

x_label_formatter ()

y_label_formatter()