GD::Graph::boxplot - Produces PNG box and whisker graphs

 

NAME

Boxplot - Box and Whisker Graph Module for Perl 5.

SYNOPSIS

use GD::Graph::boxplot;

DESCRIPTION

boxplot is a perl5 module that uses GD::Graph, GD, and Statistics::Descriptive to create and display PNG output for box and whisker graphs.

EXAMPLES

See the samples directory in the distribution.

USAGE

Fill an array of arrays with the x values and array references to the data sets to be used. Make sure that every array has the same number of data sets as there are x values, otherwise GD:Graph will complain and refuse to compile the graph. For example:

        $one = [210..275];
        $two = [180, 190, 200, 220, 235, 245];
        $three = [40, 140..150, 160..180, 250];
        $four = [100..125, 136..140];
        $five = [10..50, 100, 180];
        @data = ( 
                ["1st", "2nd", "3rd", "4th", "5th"],
                [$one, $two, $three, $four, $five ],
                [ [-25, 1..15], [-45, 25..45, 100], [70, 42..125], [undef], [180..250] ],
                # as many sets of data sets as you like         
                );

If you don't have any data for a certain dataset, you can use undef as shown above, and GD::Graph will skip that box.

Create a new GG::Graph object by calling the new operator on the type boxplot:

        $my_graph = new GD::Graph::boxplot( );

Set the graph options:

        $my_graph->set( 
                x_label           => 'X Label',
                y_label           => 'Y label',
                title             => 'Some simple graph',
                upper_percent     => 70,
                lower_percent     => 35,
                step_const        => 1.8
                );

Output the graph:

    $gd = $my_graph->plot( \@data );
    open(IMG, '>box.png') or die $!;
    binmode IMG;
    print IMG $gd->png;

METHODS AND FUNCTIONS

See GD::Graph documentation for methods for all GD::Graph graphs.

OPTIONS

Options for all graphs

See GD::Graph documentation for options for all graphs.

Options for graphs with axes

Boxplot has axes, and has all of the options available to the other graphs with axes: bars, lines, points, linespoints and area. See the GD::Graph documentation for all of these options.

Options specific to Boxplot graphs

do_stats, upper_percent, lower_percent
If do_stats is a true value, the program assumes that raw data are used for input. It calculates the statistics for each box's data, and draws the box, mean, median, upper and lower whiskers, outliers, and far-out-values accordingly. The top and bottom of the box are determined by the numbers given for upper_percent and lower_percent. For example, if you wanted to have the box contain all the data from the 20% to 80% range, you would use: 
        $my_graph->set(
                lower_percent         => 20,
                upper_percent         => 80
                );

If do_stats is set to 0, the program assumes that the user has already calculated the required statistics for every box. The user must input these statistics in place of the raw data:

        # data must be in this form:
        # $data = [mean, lowest, lower-percentile, median, upper-precentile, highest];
        $one = [27, -35, 14, 29, 39, 52];
        $two = [41, -140, 29, 45, 62, 125];
        $three = [100, 30, 88, 95, 115, 155];
        $four = [80, -100, 60, 100, 110, 195];
        @data = ( 
                ["1st", "2nd", "3rd", "4th"],
                [ $one, $two, $three, $four],
                # as many sets as you like, all with the required statistical data
                );


        $my_graph = new GD::Graph::boxplot();
        $my_graph->set(
                box_spacing       => 35,
                do_stats          => 0
                );

Notice that if do_stats is set to 0, upper_percent and lower_percent are not used, because the user is able to input the actual value for the lower-percentile and upper-percetile. Also notice that outliers and far-out-values are not drawn, because the program does not have the data points to use. However, the lowest or highest values can be drawn as outliers or far-out-values if they fall outside of the whiskers.

Default: do_stats = 1, upper_percent = 75, lower_percent = 25.

box_spacing
Number of pixels to leave open between boxes. This works well in most cases, but on some platforms, a value of 1 will be rounded off to 0.

Default: box_spacing = 10

warnings
If set to 1, warnings are printed to the standard out when the user sets parameters to questionable values. For example, if there are not enough pixels to draw the boxes properly because there are too many data sets for the given image size, or because the box_spacing is set too high, then a warning is printed so the user is aware of the problem. If set to 0, all warnings are turned off. This option is for users who do not want anything to be printed to the standard output.

Default: warnings = 1

step_const
Sets the step size equal to step_const box-heights, where the box-height is the distance from the top of the box to the bottom. The whiskers are then drawn one step from the top/bottom of the box, or to the largest/smallest data value, whichever is closer to the box. If there are values further than one step from the box, then the whiskers are drawn to one step from the box, and those values further than the whiskers are drawn as either outliers or far-out-values as explained below. step_cont can be any number greater than 0.

Default: step_const = 1.5

fov_const
Sets the distance that will mark the boundary between outliers and far-out-values. Outliers will be drawn between the whisker and fov_const steps from the whisker. Far-out-values will be drawn for values that fall farther than fov_const steps from the whisker. fov_const can be any number greater than 0.

Default: fov_const = 1

box_fill
When set to 1, the boxes are filled with the color for that data set. When set to 0, only the symbols and the outlines of the boxes will be drawn.

Default: box_fill = 1

symbolc
The color for drawing the symbols and box outlines.

Default: symbolc = 'dblue'

NOTES

This module was designed to function in the same way as other GIFgraph graph types. It has all of the same functionality (except for mixed graphs) as the other graphs. This functionality includes how to set the colors that fill the boxes (same as Bars), change the size of the margins between the plot and the edge of the GIF, etc. Please read the GIFgraph documentation for the full set of options avaiable.

AUTHOR

Written by: Nigel Wright. Converted by: George Fitch.

Design and Funding: Mark Landry, Client/Server Architects, Inc.

Contact info

email: nwright@hmc.edu - Nigel gaf3@gaf3.com - George

Copyright

Copyright (C) 1999 Nigel Wright. All rights reserved. This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

 

   GD::Graph::boxplot - Produces PNG box and whisker graphs