NAME

GIFgraph - Graph Plotting Module for Perl 5

SYNOPSIS

use GIFgraph::moduleName;

DESCRIPTION

GIFgraph is a perl5 module to create and display GIF output for a graph. The following classes for graphs with axes are defined:

GIFgraph::lines: Create a line chart.
GIFgraph::bars: Create a bar chart.
GIFgraph::points: Create an chart, displaying the data as points.
GIFgraph::linespoints: Combination of lines and points.
GIFgraph::area: Create a graph, representing the data as areas under a line.
GIFgraph::mixed: Create a mixed type graph, any combination of the above. At the moment this is fairly limited. Some of the options that can be used with some of the individual graph types won't work very well. Multiple bar graphs in a mixed graph won't display very nicely.

Additional types:

GIFgraph::pie: Create a pie chart.

EXAMPLES

See the samples directory in the distribution.

USAGE

Fill an array of arrays with the x values and the values of the data sets. Make sure that every array is the same size, otherwise GIFgraph will complain and refuse to compile the graph.

@data = ( 
    ["1st","2nd","3rd","4th","5th","6th","7th", "8th", "9th"],
    [    1,    2,    5,    6,    3,  1.5,    1,     3,     4]
    [ sort { $a <=> $b } (1, 2, 5, 6, 3, 1.5, 1, 3, 4) ]
);

If you don't have a value for a point in a certain dataset, you can use undef, and GIFgraph will skip that point.

Create a new GIFgraph object by calling the new operator on the graph type you want to create (chart is bars, lines, points, linespoints or pie).

$my_graph = new GIFgraph::chart( );

Set the graph options.

$my_graph->set( 
    x_label           => 'X Label',
    y_label           => 'Y label',
    title             => 'Some simple graph',
    y_max_value       => 8,
    y_tick_number     => 8,
    y_label_skip      => 2 
);

Output the graph

$my_graph->plot_to_gif( "sample01.gif", \@data );

METHODS AND FUNCTIONS

Methods for all graphs

new GIFgraph::chart([width,height]): Create a new object $graph with optional width and heigth. Default width = 400, default height = 300. chart is either bars, lines, points, linespoints, area or pie.
set_text_clr( colour name ): Set the colour of the text. This will set the colour of the titles, labels, and axis labels to colour name. Also see the options textclr, labelclr and axislabelclr.
set_title_font( fontname ): Set the font that will be used for the title of the chart. Possible choices are defined in GD. NB. If you want to use this function, you'll need to use GD. At some point I'll rewrite this, so you can give this a number from 1 to 4, or a string like 'large' or 'small'. On the other hand, I might not, if Thomas Boutell decides to support more fonts.
plot( \@data ): Plot the chart, and return the GIF data.
plot_to_gif( filename, \@data ): Plot the chart, and write the GIF data to filename.
set( key1 => value1, key2 => value2 .... ): Set chart options. See OPTIONS section.

Methods for Pie charts

set_label_font( fontname )
set_value_font( fontname ): Set the font that will be used for the label of the pie or the values on the pie. Possible choices are defined in GD. See also set_title_font.

Methods for charts with axes.

set_x_label_font ( font name )
set_y_label_font ( font name )
set_x_axis_font ( font name )
set_y_axis_font ( font name ): Set the font for the x and y axis label, and for the x and y axis value labels. See also set_title_font.

OPTIONS

Options for all graphs

gifx, gify

The width and height of the gif file in pixels Default: 400 x 300. NB At the moment, these are read-only options. If you want to set the size of a graph, you will have to do that with the new method.

t_margin, b_margin, l_margin, r_margin

Top, bottom, left and right margin of the GIF. These margins will be left blank. Default: 0 for all.

logo

Name of a logo file. This should be a GIF file. Default: no logo.

logo_resize, logo_position

Factor to resize the logo by, and the position on the canvas of the logo. Possible values for logo_position are 'LL', 'LR', 'UL', and 'UR'. (lower and upper left and right). Default: 'LR'.

transparent

If set to a true value, the produced GIF will have the background colour marked as transparent (see also option bgclr). Default: 1.

interlaced

If set to a true value, the produced GIF will be interlaced. Default: 1.

bgclr, fgclr, textclr, labelclr, axislabelclr, accentclr

Background, foreground, text, label, axis label and accent colours.

dclrs (short for datacolours)

This controls the colours for the bars, lines, markers, or pie slices. This should be a reference to an array of colour names as defined in GIFgraph::colour (perldoc GIFgraph::colour for the names available).

$graph->set( dclrs => [ qw(green pink blue cyan) ] );

The first (fifth, ninth) data set will be green, the next pink, etc. Default: [ qw(lred lgreen lblue lyellow lpurple cyan lorange) ]

Options for graphs with axes.

options for bars, lines, points, linespoints and area charts.

long_ticks, tick_length

If long_ticks is a true value, ticks will be drawn the same length as the axes. Otherwise ticks will be drawn with length tick_length. if tick_length is negative, the ticks will be drawn outside the axes. Default: long_ticks = 0, tick_length = 4.

x_ticks

If x_ticks is a true value, ticks will be drawm for the x axis. These ticks are subject to the values of long_ticks and tick_length. Default: 1.

y_tick_number

Number of ticks to print for the Y axis. Use this, together with y_label_skip to control the look of ticks on the y axis. Default: 5.

y_number_format

This can be either a string, or a reference to a subroutine. If it is a string, it will be taken to be the first argument to an sprintf, with the value as the second argument:

$label = sprintf( $s->{y_number_format, $value );

If it is a code reference, it will be executed with the value as the argument:

$label = &{$s->{y_number_format}}($value);

This can be useful, for example, if you want to reformat your values in currency, with the - sign in the right spot. Something like:

sub y_format
{
    my $value = shift;
    my $ret;

    if ($value >= 0)
    {
        $ret = sprintf("\$%d", $value * $refit);
    }
    else
    {
        $ret = sprintf("-\$%d", abs($value) * $refit);
    }

    return $ret;
}

$my_graph->set( 'y_number_format' => \&y_format );

(Yes, I know this can be much shorter and more concise)

Default: undef.

x_label_skip, y_label_skip

Print every x_label_skipth number under the tick on the x axis, and every y_label_skipth number next to the tick on the y axis. Default: 1 for both.

x_all_ticks

Force a print of all the x ticks, even if x_label_skip is set to a value Default: 0.

x_label_position

Controls the position of the X axis label (title). The value for this should be between 0 and 1, where 0 means aligned to the left, 1 means aligned to the right, and 1/2 means centered. Default: 3/4

y_label_position

Controls the position of both Y axis labels (titles). The value for this should be between 0 and 1, where 0 means aligned to the bottom, 1 means aligned to the top, and 1/2 means centered. Default: 1/2

x_labels_vertical

If set to a true value, the X axis labels will be printed vertically. This can be handy in case these labels get very long. Default: 0.

x_plot_values, y_plot_values

If set to a true value, the values of the ticks on the x or y axes will be plotted next to the tick. Also see x_label_skip, y_label_skip. Default: 1 for both.

box_axis

Draw the axes as a box, if true. Default: 1.

two_axes

Use two separate axes for the first and second data set. The first data set will be set against the left axis, the second against the right axis. If this is set to a true value, trying to use anything else than 2 datasets will generate an error. Default: 0.

zero_axis

If set to a true value, the axis for y values of 0 will always be drawn. This might be useful in case your graph contains negative values, but you want it to be clear where the zero value is. (see also zero_axis_only and box_axes). Default: 0.

zero_axis_only

If set to a true value, the zero axis will be drawn (see zero_axis), and no axis at the bottom of the graph will be drawn. The labels for X values will be placed on the zero exis. Default: 0.

y_max_value, y_min_value

Maximum and minimum value displayed on the y axis. If two_axes is a true value, then y1_min_value, y1_max_value (for the left axis), and y2_min_value, y2_max_value (for the right axis) take precedence over these.

The range (y_min_value..y_max_value) has to include all the values of the data points, or GIFgraph will die with a message.

For bar and area graphs, the range (y_min_value..y_max_value) has to include 0. If it doesn't, the values will be adapted before attempting to draw the graph.

Default: Computed from data sets.

axis_space

This space will be left blank between the axes and the text. Default: 4.

overwrite

If set to 0, bars of different data sets will be drawn next to each other. If set to 1, they will be drawn in front of each other. If set to 2 they will be drawn on top of each other. Default: 0.

If you have negative values in your data sets, setting overwrite to 2 might produce odd results. Of course, the graph itself would be quite meaningless, because overwrite = 2 is meant to show some cumulative effect.

graphs with lines

line_types

Which line types to use for lines and linespoints graphs. This should be a reference to an array of numbers:

$graph->set( line_types => [3, 2, 4] );

Available line types are 1: solid, 2: dashed, 3: dotted, 4: dot-dashed.

Default: [1] (always use solid)

line_type_scale

Controls the length of the dashes in the line types. default: 6.

line_width

The width of the line used in lines and linespoints graphs, in pixels. Default: 1.

graphs with points

markers

This controls the order of markers in points and linespoints graphs. This should be a reference to an array of numbers:

$graph->set( markers => [3, 5, 6] );

Available markers are: 1: filled square, 2: open square, 3: horizontal cross, 4: diagonal cross, 5: filled diamond, 6: open diamond, 7: filled circle, 8: open circle.

Default: [1,2,3,4,5,6,7,8]

marker_size

The size of the markers used in points and linespoints graphs, in pixels. Default: 4.

mixed graphs

types

A reference to an array with graph types, in the same order as the data sets. Possible values are:

$graph->set( types => [qw(lines bars points area linespoints)] );
$graph->set( types => ['lines', undef, undef, 'bars'] );

values that are undefined or unknown will be set to default_type.

Default: all set to default_type

default_type

The type of graph to draw for data sets that either have no type set, or that have an unknown type set.

Default: lines

Options and methods for legends (axestype graphs only)

At the moment legend support is minimal.

Methods

set_legend( @legend_keys );

Sets the keys for the legend. The elements of @legend_keys correspond to the data sets as provided to plot() or plot_to_gif().

If a key is undef or an empty string, the legend entry will be skipped.

set_legend_font( font name );

Sets the font for the legend text (see also set_title_font). Default: GD::gdTinyFont.

Options

legend_placement

Where to put the legend. This should be a two letter key of the form: 'B[LCR]|R[TCB]'. The first letter sigifies the placement (Bottom or Right), and the second letter signifies the alignment (Left, Right, Center, Top, or Bottom). Default: 'BC'

If the legend is placed at the bottom, some calculations will be made to ensure that there is some 'intelligent' wrapping going on. if the legend is placed at the right, all entries will be placed below each other.

legend_spacing

The number of pixels to place around a legend item, and between a legend 'marker' and the text. Default: 4

legend_marker_width, legend_marker_height

The width and height of a legend 'marker' in pixels. Defaults: 12, 8

lg_cols

If you, for some reason, need to force the legend at the bottom to have a specific number of columns, you can use this. Default: computed

Options for pie graphs

3d: If set to a true value, the pie chart will be drawn with a 3d look. Default: 1.
pie_height: The thickness of the pie when 3d is true. Default: 0.1 x GIF y size.
start_angle: The angle at which the first data slice will be displayed, with 0 degrees being "6 o'clock". Default: 0.

NOTES

All references to colours in the options for this module have been shortened to clr. The main reason for this was that I didn't want to support two spellings for the same word ('colour' and 'color')

Wherever a colour is required, a colour name should be used from the package GIFgraph::colour. perldoc GIFgraph::colour should give you the documentation for that module, containing all valid colour names. I will probably change this to read the systems rgb.txt file if it is available.

Wherever a font name is required, a font from GD should be used.

AUTHOR

Martien Verbruggen

Contact info

email: mgjv@comdyn.com.au

Copyright

To install GIFgraph, copy and paste the appropriate command in to your terminal.

cpanm

cpanm GIFgraph

CPAN shell

perl -MCPAN -e shell
install GIFgraph

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)