The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
chart-0.94
River stage zero No dependents
++
/ Chart.pod

NAME

Chart::* - a series of charting modules

SYNOPSIS

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

DESCRIPTION

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.

use-ing Chart

Okay, so you caught me. There's really no Chart::type module. All of the different chart types (Points, Lines, Bars, LinesPoints, StackedBars, Pie, 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.

Getting an object

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.

Setting different options

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

or

  $obj->set ('title' => 'Foo Bar');

The following are all of the currently supported options:

'transparent'

Makes the background of the image transparent if set to 'true'. Useful for making web page images. Default is 'false'.

'gif_border'

Sets the number of pixels used as a border between the graph and the edges of the gif. Defaults to 10.

'graph_border'

Sets the number of pixels used as a border between the title/labels and the actual graph within the gif. Defaults to 10.

'text_space'

Sets the amount of space left on the sides of text, to make it more readable. Defaults to 2.

'title'

Tells GD graph what to use for the title of the graph. If empty, no title is drawn. Default is empty.

'sub_title'

The second line for the title, if needed. Default is empty.

'x_label'

Tells Chart::* what to use for the x-axis label. If empty, no label is drawn. Default is empty.

'y_label'

Tells Chart::* what to use for the y-axis label. If empty, no label is drawn. Default is empty.

'legend'

Draws a legend in the upper-right corner of the gif when set to 'true'. Default is 'true'.

'legend_labels'

Sets the values for the labels for the different datasets. Should be assigned a reference to an array of labels. For example,

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

'tick_len'

Sets the length of the x- and y-ticks in pixels. Default is 4.

'grid_lines'

Adds light grey grid lines in the back of the chart if set to 'true'. Default is undef.

'stagger_x_labels'

Staggers the x-tick labels vertically to make them readable if set to 'true'. Default is 'true'.

'y_ticks'

Sets the number of y_ticks to draw. Default is 5.

'max_val'

Sets the maximum y-value on the graph, cancelling the auto-scaling. Default is undef.

'pt_size'

Sets the size of the points for points, linespoints, and pareto graphs. Points are drawn as squares with sides of length 'pt_size'. Default is 4.

'dashed_lines'

Uses dashed lines, instead of solid lines, for the graph. If this is set to any other value than '' or undef, it will draw dashed lines. (I use this when the chart is going to be printed with a B&W printer. Unfortunately, it's hard to differentiate the lines after 4 datasets. There just weren't enough different ways to make dotted lines.) Default is undef.

'skip_x_ticks'

Sets the number of x-ticks and x-tick labels to skip. (ie. if 'skip_x_ticks' was set to 4, Chart::* would draw every 4th x-tick and x-tick label). Default is undef.

'custom_x_ticks'

Used in points, lines, linespoints, and bars charts, this option allows you to specify exatly which x-ticks and x-tick labels should be drawn. It should be assigned a reference to an array of desired ticks. Just remember that I'm counting from the 0th element of the array. (ie., if 'custom_x_ticks' is assigned [0,3,4], then the 0th, 3rd, and 4th x-ticks will be displayed)

'colors'

This option allows you to specify colors for the different datasets. It should be assigned a reference to an array of array references. Setting an entry to undef lets Chart::* pick the color for you. So,

    $obj->set ('colors' => [undef, [0,0,0], [255,0,0]]);

would let Chart::* pick the color for the first dataset, set the second to black, and the third to red. Default is undef.

'sort'

Tells Chart::* to sort the data before plotting it. Can be assigned an order ('asc' or 'desc' for ascending and descending, respectively), in which case it sorts numerically. Or it can also be assigned an array reference. The array reference should contain 3 elements: the order in which to search (as above), which dataset to use (remember that 0 is the x-tick labels), and the type of sort to do ('alpha' or 'num' for alphabetical or numerical sorts, respectively). For example,

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

'nosort'

Turns off the default sort for pareto graphs. Default is undef.

'cutoff'

Only used for pareto graphs, this option determines where the cut-off point is. It then lumps everything after the highest 'cutoff' data points into an 'Other' entry on the graph. Default is 5.

'nocutoff'

Turns off the default 'cutoff' feature of pareto graphs. Defaut is undef.

GIFgraph.pm-style API

Sending the image to a file

Invoking the gif method causes the graph to be plotted and saved to a file. It takes the name of the output file and a reference to the data as arguments. For example,

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

CGI and Chart::*

Okay, so you're probably thinking, "Do I always have to save these images to disk? What if I want to use Chart::* to create dynamic images for my web site?" Well, here's the answer to that.

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

Graph.pm-style API

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.pm, 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 (from Carp.pm) an error message and return undef. 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 and return undef.

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.

Clearing the data

A simple call to the clear_data method empties any values that may have been entered.

    $obj->clear_data ();
Getting a copy of the data

If you want a copy of the data that has been added so far, make a call to the get_data method like so:

    $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]};
Sending the image to a file

Invoking the gif method causes the graph to be plotted and saved to a file. It takes the name of the output file as an argument. For example,

  $obj->gif ("foo.gif");

would plot the data , and the save the image to foo.gif.

CGI and Chart::*

Okay, so you're probably thinking (again), "Do I always have to save these images to disk? What if I want to use Chart::* to create dynamic images for my web site?" Well, here's the answer to that.

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

TO DO

A bunch of things. The most pressing being

  • Add in support for negative values. (I consider this a bug)

  • Add more customization, such as fonts, colors, etc. for each element of the chart.

  • Add some 3-D graphs.

BUGS

This module can't graph negative values yet. There are probably lots more, since I consider this an alpha release. Mail me with any bugs, comments, suggestions, flames, death threats, etc.

AUTHOR

David Bonner (dbonner@cs.bu.edu)

COPYRIGHT

Copyright(c) 1997 by David Bonner. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.