SVG::Sparkline::Manual - Documentation for the SVG::Sparkline module
This document describes SVG::Sparkline version 0.34
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();
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.
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.
$args_hr
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.
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.
The value of this parameter is a boolean that specifies whether the generated sparkline should contain width and height attributes on the root element.
width
height
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.)
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.
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.
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.
The attribute parameters passed in $args_hr depend somewhat on the $type. However, some are common.
$type
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.
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.
This parameter specifies the data to be displayed by the sparkline. The actual form of this data is determined by the sparkline type.
This optional parameter specifies the color for the displayed data as an SVG supported color string. Each sparkline type uses this color slightly differently.
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.
mark
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
values
This index string represents the first data point. It is synonymous with a numeric index of 0.
This index string represents the last data point. It is equal to one less than the number of values.
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.
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:
mark => [ 3 => 'blue' ]
mark => [ low => 'red', high => 'green' ]
The supported graph types are: Area, Bar, Line, RangeArea, RangeBar, and Whisker. Each type is described below with any parameters specific to that type.
An Area sparkline is a basic line graph with 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.
Area
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.
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.
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).
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.
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.
xscale
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.
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.
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.
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.
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.
+
The mark for Bar replaces the bar in question with one of the specified color.
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.
This optional parameter specifies the thickness of the data line in pixels. If not specified, the default value is 1 pixel.
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).
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.
thick
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.
RangeArea
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.
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.
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.
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.
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.
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 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.
The values parameter is required for the Whisker sparkline type. The value can be one of three things:
Where '+' means an uptick, '-' is a down tick, and 0 is no tick.
Where '1' means an uptick, and '0' means a downtick.
Where any positive number is an uptick, any negative number is a downtick, and zero is no tick.
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.
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.
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.
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).
The mark for Whisker replaces the whisker in question with one of the specified color.
The following public methods are provided on the SVG::Sparkline object.
SVG::Sparkline
Returns in height in pixels of the completed sparkline.
Returns in width in pixels of the completed sparkline.
Convert the SVG::Sparkline object to an XML string. This is the method that is used by the stringification overload.
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.
sparkline.pl
--help
The CGI script is documented in SVG::Sparkline::Manual::CGI.
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).
G. Wade Johnson <wade@anomaly.org>
<wade@anomaly.org>
Copyright (c) 2009, G. Wade Johnson <wade@anomaly.org>. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl 5.8.0. See perlartistic.
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.
1 POD Error
The following errors were encountered while parsing the POD:
Non-ASCII character seen before =encoding in 'Magalhães'. Assuming UTF-8
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.