|
Chart - a series of charting modules |
Chart - a series of charting modules
use Chart::type;
$obj = Chart::type->new;
$obj = Chart::type->new ( $gif_width, $gif_height );
$obj->set ( $key_1, $val_1, ... ,$key_n, $val_n );
$obj->set ( $key_1 => $val_1,
...
$key_n => $val_n );
$obj->set ( %hash );
# GIFgraph.pm-style API
@data = ( \@x_tick_labels, \@dataset1, ... , \@dataset_n );
$obj->gif ( "filename", \@data );
$obj->gif ( $filehandle, \@data );
$obj->gif ( FILEHANDLE, \@data );
$obj->cgi_gif ( \@data );
# Graph.pm-style API
$obj->add_pt ($label, $val_1, ... , $val_n);
$obj->add_dataset ($val_1, ... , $val_n);
$obj->gif ( "filename" );
$obj->gif ( $filehandle );
$obj->gif ( FILEHANDLE );
$obj->cgi_gif ();
# Retrieve imagemap information
$obj->set ( 'imagemap' => 'true' );
$imagemap_ref = $obj->imagemap_dump ();
This module is an attempt to build a general purpose graphing module that is easily modified and expanded. I borrowed most of the API from Martien Verbruggen's GIFgraph module. I liked most of GIFgraph, but I thought it was to difficult to modify, and it was missing a few things that I needed, most notably legends. So I decided to write a new module from scratch, and I've designed it from the bottom up to be easy to modify. Like GIFgraph, Chart uses Lincoln Stein's GD module for all of its graphics primitives calls.
Okay, so you caught me. There's really no Chart::type module. All of the different chart types (Points, Lines, Bars, LinesPoints, Pie, Composite, StackedBars, and Pareto so far) are classes by themselves, each inheriting a bunch of methods from the Chart::Base class. Simply replace the word type with the type of chart you want and you're on your way. For example,
use Chart::Lines;
would invoke the lines module.
The new method can either be called without arguments, in which case it returns an object with the default image size (400x300 pixels), or you can specify the width and height of the image. Just remember to replace type with the type of graph you want. For example,
$obj = Chart::Bars (600,400);
would return a Chart::Bars object containing a 600x400 pixel image. New also initializes most of the default variables, which you can subsequently change with the set method.
This is where the fun begins. Set looks for a hash of keys and values. You can pass it a hash that you've already constructed, like
%hash = ('title' => 'Foo Bar');
$obj->set (%hash);
or you can try just constructing the hash inside the set call, like
$obj->set ('title' => 'Foo Bar');
The following are all of the currently supported options:
@labels = ('foo', 'bar');
$obj->set ('legend_labels' => \@labels);
Default is empty, in which case 'Dataset 1', 'Dataset 2', etc. are used as the labels.
For a pareto graph, the first value should be the name of the set, and the second should be the name of the running sum of the values.
For a pie graph, this option is ignored, as the values for the legend are taken from the array of data point labels.
$obj->set('colors' => {'background' => [255,255,255]});
sets the background color to white (which is the default). Valid keys for this hash are
'background' (background color for the gif)
'text' (all the text in the chart)
'y_label' (color of the first y axis label)
'y_label2' (color of the second y axis label)
'grid_lines' (color of the grid lines)
'x_grid_lines' (color of the x grid lines - for x axis ticks)
'y_grid_lines' (color of the y grid lines - for to left y axis ticks)
'y2_grid_lines' (color of the y2 grid lines - for right y axis ticks)
'dataset0'..'dataset15' (the different datasets)
'misc' (everything else, ie. ticks, box around the legend)
NB. For composite charts, there is a limit of 8 datasets per component. The colors for 'dataset8' through 'dataset15' become the colors for 'dataset0' through 'dataset7' for the second component chart.
imagemap_dump() method. NB. that the
imagemap_dump() method cannot be called until after the Chart has been
generated (ie. using the gif() or cgi_gif() methods).
$obj->set ('sort' => ['asc', 2, 'num']);
would sort the data numerically in ascending order, sorting by the third dataset (second if you don't count the x-tick labels). Note that
$obj->set ('sort' => ['asc', 0, 'alpha']);
will sort the data in ascending alphabetical order by the x-tick labels. Defualts to undef, normally, and 'desc' for pareto.
$obj->set ('composite_info' => [ ['Bars', [1,2]],
['Lines', [3,4] ]);
This example would set the two component charts to be a bar chart and a line chart. It would use the first two data sets for the bar chart (note that the numbering starts at 1, not zero like most of the other numbered things in Chart), and the second two data sets for the line chart. The default is undef.
NB. Chart::Composite can only do two component charts.
$obj->gif ("foo.gif", \@data);
would plot the data in @data, and the save the image to foo.gif. Of course, this then beggars the question ``What should @data look like?''. Well, just like GIFgraph, @data should contain references to arrays of data, with the first array reference pointing to an array of x-tick labels. For example,
@data = ( [ 'foo', 'bar', 'junk' ],
[ 30.2, 23.5, 92.1 ] );
would set up a graph with one dataset, and three data points in that set. In general, the @data array should look something like
@data = ( \@x_tick_labels, \@dataset1, ... , \@dataset_n );
And no worries, I make my own internal copy of the data, so that it doesn't mess with yours.
$obj->cgi_gif ( \@data );
The cgi_gif method will print the chart, along with the appropriate http header, to stdout, allowing you to call chart-generating scripts directly from your html pages (ie. with a <img src=image.pl> HTML tag). The @data array should be set up the same way as for the normal gif method.
You might ask, ``But what if I just want to add a few points to the graph, and then display it, without all those references to references?''. Well, friend, the solution is simple. Borrowing the add_pt idea from Matt Kruse's Graph module, you simply make a few calls to the add_pt method, like so:
$obj->add_pt ('foo', 30, 25);
$obj->add_pt ('bar', 16, 32);
Or, if you want to be able to add entire datasets, simply use the add_dataset method:
$obj->add_dataset ('foo', 'bar');
$obj->add_dataset (30, 16);
$obj->add_dataset (25, 32);
These methods check to make sure that the points and datasets you are adding are the same size as the ones already there. So, if you have two datasets currently stored, and try to add a data point with three different values, it will carp (per the Carp module) an error message. Similarly, if you try to add a dataset with 4 data points, and all the other datasets have 3 data points, it will carp an error message.
Don't forget, when using this API, that I treat the first dataset as a series of x-tick labels. So, in the above examples, the graph would have two x-ticks, labeled 'foo' and 'bar', each with two data points.
$obj->clear_data ();
$dataref = $obj->get_data;
It returns (you guessed it!) a reference to an array of references to datasets. So the x-tick labels would be stored as
@x_labels = @{$dataref->[0]};
gif() method.
$obj->gif ("foo.gif");
$obj->gif ($filehandle);
$obj->gif (FILEHANDLE);
$obj->cgi_gif ();
The cgi_gif method will print the chart, along with the appropriate http header, to stdout, allowing you to call chart-generating scripts directly from your html pages (ie. with a <img src=image.pl> HTML tag).
Chart can also return the pixel positioning information so that you can
create image maps from the gifs Chart generates. Simply set the 'imagemap'
option to 'true' before you generate the gif, then call the imagemap_dump()
method afterwards to retrieve the information. You will be returned a
data structure almost identical to the @data array described above to pass
the data into Chart.
$imagemap_data = $obj->imagemap_dump ();
Instead of single data values, you will be passed references to arrays of pixel information. For Bars and StackedBars charts, the arrays will contain two x-y pairs (specifying the upper left and lower right corner of the bar), like so
( $x1, $y1, $x2, $y2 ) = @{ $imagemap_data->[$dataset][$datapoint] };
For Lines, Points, and LinesPoints, the arrays will contain a single x-y pair (specifying the center of the point), like so
( $x, $y ) = @{ $imagemap_data->[$dataset][$datapoint] };
A few caveats apply here. First of all, GD treats the upper-left corner of the gif as the (0,0) point, so positive y values are measured from the top of the gif, not the bottom. Second, these values will most likely contain long decimal values. GD, of course, has to truncate these to single pixel values. Since I don't know how GD does it, I can't truncate it the same way he does. In a worst-case scenario, this will result in an error of one pixel on your imagemap. If this is really an issue, your only option is to either experiment with it, or to contact Lincoln Stein and ask him. Third, please remember that the 0th dataset will be empty, since that's the place in the @data array for the data point labels.
Probably quite a few, since it's been completely rewritten. As usual, please mail me with any bugs, patches, suggestions, comments, flames, death threats, etc.
David Bonner (dbonner@cs.bu.edu)
Peter Clark (ninjaz@webexpress.com)
Copyright(c) 1997-1998 by David Bonner, 1999 by Peter Clark
All rights reserved. This program is free software; you can
redistribute it and/or modify it under the same terms as Perl
itself.
|
Chart - a series of charting modules |