/ 
SVG-Sparkline-0.2.5
River stage zero No dependents
/ SVG::Sparkline

NAME

SVG::Sparkline - Create Sparklines in SVG

VERSION

This document describes SVG::Sparkline version 0.2.5

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

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.

INTERFACE

CVG::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.

-nodecl

The value of this parameter is a boolean that specifies whether the XML declaration statement is to be removed from the generated SVG.

If you are embedding the SVG content directly in another document (maybe HTML), you should pass this parameter with a 1. If you are generating a standalone sparkline document, you should pass a 0.

The -nodecl parameter defaults to 0.

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

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

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

Area

An Area sparkline is a basic line graph with shaded between the line and the x axis. The supplied color attribute determines the shading.

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.

Bar

The Bar sparkline type is a simple bar graph. This sparkline type does not require any x values.

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.

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

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.

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.

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.

to_string

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

DIAGNOSTICS

Diagnostic message for the various types are documented in the appropriate SVG::Sparkline::* module.

CONFIGURATION AND ENVIRONMENT

SVG::Sparkline requires no configuration files or environment variables.

DEPENDENCIES

Carp, SVG.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

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

ACKNOWLEDGEMENTS

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

AUTHOR

G. Wade Johnson <wade@anomaly.org>

LICENCE AND COPYRIGHT

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