NAME

SVG::Sparkline::Manual - Documentation for the SVG::Sparkline module

VERSION

This document describes SVG::Sparkline version 0.34

SYNOPSIS

  use SVG::Sparkline;

  my $sl1 = SVG::Sparkline->new( Whisker => { values=>\@values, color=>'#eee', height=>12 } );
  print $sl1->to_string();

  my $sl2 = SVG::Sparkline->new( Line => { values=>\@values, color=>'blue', height=>12 } );
  print $sl2->to_string();

  my $sl3 = SVG::Sparkline->new( Area => { values=>\@values, color=>'green', height=>10 } );
  print $sl3->to_string();

  my $sl4 = SVG::Sparkline->new( Bar => { values=>\@values, color=>'#66f', height=>10 } );
  print $sl4->to_string();

  my $sl5 = SVG::Sparkline->new( RangeBar => { values=>\@value_pairs, color=>'#66f', height=>10 } );
  print $sl5->to_string();

DESCRIPTION

In the book Beautiful Evidence, Edward Tufte describes sparklines as small, high-resolution, graphics embedded in a context of words, numbers, images.

This module provides a relatively easy interface for creating different kinds of sparklines. This class is not intended to be used to build large, complex graphs (there are other modules much more suited to that job). The focus here is on the kinds of data well-suited to the sparklines concept.

Although the basics are there, this module is not yet feature complete.

LIBRARY INTERFACE

SVG::Sparkline->new( $type, $args_hr )

Create a new SVG::Sparkline object of the specified type, using the parameters in the $args_hr hash reference. There are two groups of parameters. Parameters that start with a - character control the SVG::Sparkline object. Parameters that do not start with - are used in attributes in the sparkline itself.

Configuration Parameters

Configuration parameters are independent of the type of sparkline being generated. The parameters are generally discussed below, but see the section "SPARKLINE TYPES" for a full description of the parameters as they apply to each type.

-allns

The value of this parameter is a boolean that specifies whether to supply all potential namespace attributes relating to SVG.

If the value of the parameter is 0 or the parameter is not supplied, only the default SVG namespace is included in the sparkline.

If the value of the parameter is 1, a namespace is supplied for the prefix svg and the prefix xlink.

-sized

The value of this parameter is a boolean that specifies whether the generated sparkline should contain width and height attributes on the root element.

A value of 1 causes them to be added, while 0 leaves them off. The default value of this parameter is 1. (Although that may change in future versions. Add the parameter if you want to be future-proof.)

bgcolor

The value of this parameter is an SVG-supported color string which specifies a color for the background of the sparkline. In general, this parameter should not be supplied or should be very subtle to avoid taking attention away from the actual data displayed.

padx

The value of this parameter is the number of pixels of padding inside the sparkline, but to the left of the first data point and right of the last data point.

pady

The value of this parameter is the number of pixels of padding inside the sparkline, but above the highest data point and below the lowest data point.

Attribute Parameters

The attribute parameters passed in $args_hr depend somewhat on the $type. However, some are common.

height

This optional parameter specifies the height of the Sparkline in pixels. The data for the sparkline is scaled to fit this height. If not specified, the default height is 10 pixels.

width

This parameter specifies the width of the Sparkline in pixels. All data is scaled to fit this width. The default value of the width parameter depends on the sparkline type.

values

This parameter specifies the data to be displayed by the sparkline. The actual form of this data is determined by the sparkline type.

color

This optional parameter specifies the color for the displayed data as an SVG supported color string. Each sparkline type uses this color slightly differently.

mark

There are times when certain points on the sparkline need to be highlighted in some way. For instance, you might want to highlight the lowest and highest value of a data set. The mark attribute supports this functionality.

The appearance of the mark is mostly determined by the sparkline type. However, you may select different colors for each mark.

The value of the mark attribute is a reference to an array of pairs, where each pair consists of an index and a color. The index is either an integer specifying which point in the values is to be marked or a string that describes a particular point. The supported index strings are

first: This index string represents the first data point. It is synonymous with a numeric index of 0.
last: This index string represents the last data point. It is equal to one less than the number of values.
high: This index string repesents the highest value in the data set. If there is more than one point with the highest value, the first index with this value is selected.
low: This index string repesents the lowest value in the data set. If there is more than one point with the lowest value, the first index with this value is selected.

The following would be examples of marks:

Single Indexed Mark

mark => [ 3 => 'blue' ]

High and Low Marks

mark => [ low => 'red', high => 'green' ]

SPARKLINE TYPES

The supported graph types are: Area, Bar, Line, RangeArea, RangeBar, and Whisker. Each type is described below with any parameters specific to that type.

Area

An Area sparkline is a basic line graph shaded between the line and the x axis. The supplied color attribute determines the shading. Area graphs do particularly well for continuous data. If you would prefer to just have the line without filling the area, see the Line type.

values: The value of this parameter is a reference to an array. This array is either an array of numeric values representing the y-values of the data to be plotted, or an array of anonymous arrays, each containing an x-value and a y-value.
width: This parameter is optional for the Area sparkline type. The value is the width of the sparkline in pixels. The default value for this parameter is the number of items in the values parameter.
color: This optional parameter specifies the color of the filled area between the data line and the x-axis as a SVG supported color string. The default value for this parameter is #000 (black).
mark: The mark for an Area is a vertical line of the specified color. The line moves from a value of zero up to the value.
xscale: This parameter determines the distance between data points. The width parameter overrides the xscale parameter. If no width or xscale are supplied, the default value is 2.

Bar

The Bar sparkline type is a simple bar graph. This sparkline type does not require any x values. Bar graphs see to be particularly useful for non-continuous data.

values: The values parameter is required for the Bar sparkline type. The value must be a reference to an array of numeric values, specifying the height of the corresponding bar.
thick: This optional parameter specifies the thickness of the individual bars on the bar graph. This parameter is ignored if the width parameter is specified. If neither width or thick are specified, the default value of thick is 3.
gap: This optional parameter specifies a gap to appear between individual bars on the bar graph. If the gap is not specified, the default value is 0.
width: This optional parameter specifies the width of the sparkline in pixels. If the width is not specified, the width of the sparkline is the value of thick + gap times the number of values.
color: This optional parameter specifies the color of the filled area between the data line and the x-axis as a SVG supported color string. The default value for this parameter is #000 (black).
mark: The mark for Bar replaces the bar in question with one of the specified color.

Line

The Line sparkline type is a simple line graph. Both x and y values are required for Line sparklines. Area graphs do particularly well for continuous data. If you would prefer to have the area under the line filled, see the Area type.

values: The value of this parameter is a reference to an array. This array is either an array of numeric values representing the y-values of the data to be plotted, or an array of anonymous arrays, each containing an x-value and a y-value.
width: This parameter is optional for the Area sparkline type. The value is the width of the sparkline in pixels. The default value for this parameter is the number of items in the values parameter.
thick: This optional parameter specifies the thickness of the data line in pixels. If not specified, the default value is 1 pixel.
color: This optional parameter specifies the color of the data line as a SVG supported color string. The default value for this parameter is #000 (black).
mark: The mark for Line is a dot of the specified color at the chosen location. The radius of the dot is the same as the width of the line, specified by the thick parameter.
xscale: This parameter determines the distance between data points. The width parameter overrides the xscale parameter. If no width or xscale are supplied, the default value is 2.

RangeArea

An RangeArea sparkline type shows high/low continuous values by displaying shading the area between two lines of continuous data. The supplied color attribute determines the shading. Area graphs do particularly well for continuous data.

If you would prefer to just have a single line shaded to the x-axis, see the Area type. If you would prefer a single continuous line with no shading see the Line type.

values

The value of this parameter is a reference to an array. This array is either an array of numeric values representing the y-values of the data to be plotted, or an array of anonymous arrays, each containing an x-value and a y-value.

width

This parameter is optional for the RangeArea sparkline type. The value is the width of the sparkline in pixels. The default value for this parameter is the number of items in the values parameter.

color

This optional parameter specifies the color of the filled area between the data line and the x-axis as a SVG supported color string. The default value for this parameter is #000 (black).

mark

The mark for a RangeArea is a vertical line of the specified color. The line moves from the low value to the high value at the specified position.

There is one difference between the mark index values for RangeArea and for other sparkline types. Since there are two values for each index, the high and low indexes need further explanation.

The index high chooses the highest of the high values. The index low chooses the lowest of the low values.

xscale

This parameter determines the distance between data points. The width parameter overrides the xscale parameter. If no width or xscale are supplied, the default value is 2.

RangeBar

The RangeBar sparkline type shows high/low pairs of related values that define a range at each of the supplied data points. Each data point is displayed as a bar (like the bar graph) that ranges from the low value to the high value.

The RangeBar type is very good for displaying two related values of a discrete data set. For example, high and low values of some data aggregated each month.

values

This parameter is slightly more complicated than the other sparkline types. Its value is a reference to an array of array references. Each of these internal array references contains two numbers: a low value followed by a high value. These numbers are used to calculate the height of the bar and its placement veritcally on the sparkline.

thick

This optional parameter specifies the thickness of the individual bars on the bar graph. This parameter is ignored if the width parameter is specified. If neither width or thick are specified, the default value of thick is 3.

gap

This optional parameter specifies a gap to appear between individual bars on the bar graph. If the gap is not specified, the default value is 0.

width

This optional parameter specifies the width of the sparkline in pixels. If the width is not specified, the width of the sparkline is the value of thick + gap times the number of values.

color

This optional parameter specifies the color of the filled area between the data line and the x-axis as a SVG supported color string. The default value for this parameter is #000 (black).

mark

The mark for RangeBar replaces the bar in question with one of the specified color.

There is one difference between the mark index values for RangeBar and for other sparkline types. Since there are two values for each index, the high and low indexes need further explanation.

The index high chooses the highest of the high values. The index low chooses the lowest of the low values.

Whisker

The Whisker sparkline type shows a sequence of events that can have one of two outcomes (e.g. win/loss). A short line upwards is one of the outcomes and a short line downward is the other outcome. There is also a third possible where no tick is displayed.

values

The values parameter is required for the Whisker sparkline type. The value can be one of three things:

string of '+', '-', or '0': Where '+' means an uptick, '-' is a down tick, and 0 is no tick.
string of '1' or '0'.: Where '1' means an uptick, and '0' means a downtick.
reference to an array of numbers: Where any positive number is an uptick, any negative number is a downtick, and zero is no tick.

width

This optional parameter specifies the width of the sparkline in pixels. If the width is not specified, the width of the sparkline is the value of thick times 3 times the number of values.

thick

This optional parameter specifies the thickness of the individual whiskers on the whisker chart. The gaps between the whiskers is twice the value of thick. This parameter is ignored if the width parameter is specified. If neither width or thick are specified, the default value of thick is 1.

gap

This optional parameter specifies a gap to appear between individual whiskers on the whisker chart. If the gap is not specified, the default value is twice the thick value for the whiskers.

color

This optional parameter specifies the color of the individual whiskers as a SVG supported color string. The default value for this parameter is #000 (black).

mark

The mark for Whisker replaces the whisker in question with one of the specified color.

PUBLIC METHODS

The following public methods are provided on the SVG::Sparkline object.

get_height

Returns in height in pixels of the completed sparkline.

get_width

Returns in width in pixels of the completed sparkline.

to_string

Convert the SVG::Sparkline object to an XML string. This is the method that is used by the stringification overload.

PROGRAMS

The library also supplies two programs that simplies the creation of sparklines without programming. The command-line tool sparkline.pl is documented in the program itself. The documentation is displayed when executing the program with the --help parameter.

The CGI script is documented in SVG::Sparkline::Manual::CGI.

ACKNOWLEDGEMENTS

This module has been greatly improved by suggestions and corrections supplied but Robert Boone, Debbie Campbell, and Joshua Keroes.

Thanks to Helder Magalhães for the suggestion to remove the height and width attributes from the root svg element. This lead to the definition of the -sized parameter.

Thanks to Jeff Schiller for the idea of the sparklines.cgi script. Honestly, I would not have thought to provide it (since it's not hard to build).

AUTHOR

G. Wade Johnson <gwadej@cpan.org>

LICENCE AND COPYRIGHT

This module is free software; you can redistribute it and/or modify it under the same terms as Perl 5.8.0. See perlartistic.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

To install SVG::Sparkline, copy and paste the appropriate command in to your terminal.

cpanm

cpanm SVG::Sparkline

CPAN shell

perl -MCPAN -e shell
install SVG::Sparkline

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

LIBRARY INTERFACE

SVG::Sparkline->new( $type, $args_hr )

Configuration Parameters

Attribute Parameters

SPARKLINE TYPES

Area

Bar

Line

RangeArea

RangeBar

Whisker

PUBLIC METHODS

get_height

get_width

to_string

PROGRAMS

ACKNOWLEDGEMENTS

AUTHOR

LICENCE AND COPYRIGHT

DISCLAIMER OF WARRANTY

Module Install Instructions