Linux Certif

Toute la documentation sur la certification Linux LPI

Chart::Gnuplot.3pm

NAME

Chart::Gnuplot - Plot graph using Gnuplot on the fly

SYNOPSIS

     use Chart::Gnuplot;
     
     # Data
     my @x = (-10 .. 10);
     my @y = (0 .. 20);
     
     # Create chart object and specify the properties of the chart
     my $chart = Chart::Gnuplot->new(
         output => "fig/simple.png",
         title  => "Simple testing",
         xlabel => "My x-axis label",
         ylabel => "My y-axis label",
         ....
     );
     
     # Create dataset object and specify the properties of the dataset
     my $dataSet = Chart::Gnuplot::DataSet->new(
         xdata => \@x,
         ydata => \@y,
         title => "Plotting a line from Perl arrays",
         style => "linespoints",
         ....
     );
     
     # Plot the data set on the chart
     $chart->plot2d($dataSet);
     
     ##################################################
     
     # Plot many data sets on a single chart
     $chart->plot2d($dataSet1, $dataSet2, ...);
 
 

DESCRIPTION

This module is to plot graphs uning GNUPLOT on the fly. In order to use this module, gnuplot need to be installed. If image format other than PS and EPS is required to generate, the convert program of ImageMagick is also needed.

To plot chart using Chart::Gnuplot, a chart object and at least one dataset object are required. Information about the chart such as output file, chart title, axes labels and so on is specified in the chart object. Dataset object contains information about the dataset to be plotted, including source of the data points, dataset label, color used to plot and more.

After chart object and dataset object(s) are created, the chart can be plotted using the plot2d, plot3d or multiplot method of the chart object, e.g.

     # $chart is the chart object
     $chart->plot2d($dataSet1, $dataSet2, ...);
 
 

To illustate the features of Chart::Gnuplot, the best way is to show by examples. A lot of examples are provided in the package.

CHART OBJECT

The chart object can be initiated by the c<new> method. Properties of the chart may be specified optionally when the object is initiated:

     my $chart = Chart::Gnuplot->new(%options);
 
 

Chart Options

output

Output file of the graph. By default, the image format is detected automatically by the extension of the filename. However, it can also be changed manually by using the format conversion methods such as "convert" and "png" (see sessions below).

The supported image formats are:

     bmp  : Microsoft Windows bitmap
     epdf : Encapsulated Portable Document Format
     epi  : Encapsulated PostScript Interchange format
     eps  : Encapsulated PostScript
     gif  : Graphics Interchange Format
     jpg  : Joint Photographic Experts Group JFIF format
     pdf  : Portable Document Format
     png  : Portable Network Graphics
     ppm  : Portable Pixmap Format
     ps   : PostScript file
     psd  : Adobe Photoshop bitmap file
     xpm  : X Windows system pixmap
 
 

If the filename has no extension, postscipt will be used.

title

Title of the chart. E.g.,

     title => "Chart title"
 
 

Properties of the chart title can be specified in hash. E.g.,

     title => {
         text => "Chart title",
         font => "arial, 20",
         ....
     }
 
 

Supported properties are:

     text     : title in plain text
     font     : font face (and optionally font size)
     color    : font color
     offset   : offset relative to the default position
     enhanced : title contains subscript/superscipt/greek? (on/off)
 
 

Default values would be used for properties not specified. These properties has no effect on the main title of the multi-chart (see multiplot).

xlabel, ylabel, zlabel

Label of the x-axis, y-axis and z-axis. E.g.

     xlabel => "Bottom axis label"
 
 

Properties of the axis label can be specified in hash, similar to the chart title. Supported properties are:

     text     : title in plain text
     font     : font face (and optionally font size)
     color    : font color
     offset   : offset relative to the default position
     rotate   : rotation in degrees
     enhanced : title contains subscript/superscipt/greek? (on/off)
 
 

x2label, y2label

Label of the secondary x-axis (displayed on the top of the graph) and the secondary y-axis (displayed on the right of the graph). See xlabel.

xrange, yrange, zrange

Range of the x-axis, y-axis and z-axis in the plot, e.g.

     xrange => [0, "pi"]
 
 

x2range, y2range

Range of the secondary axes in the plot. See xrange.

trange, urange, vrange

Range of the parametric parameter (t for 2D plots, while u and v for 3D plots). See xrange.

xtics, ytics, ztics

The tics and tic label on the x-axis, y-axis and z-axis. E.g.

    xtics => {
       labels   => [-10, 15, 20, 25],
       labelfmt => "%3f",
       ....
    }
 
 

Supported properties are:

     labels    : the locations of the tic labels
     labelfmt  : format of the labels
     font      : font of the labels
     fontsize  : font size of the lebals
     fontcolor : font color of the label
     offset    : position of the tic labels shifted from its default
     rotate    : rotation of the tic labels
     length    : length of the tics
     along     : where the tics are put (axis/border)
     minor     : number of minor tics between adjacant major tics
     mirror    : turn on and off the tic label of the secondary axis. No effect
               : for C<ztics> (on/off)
 
 

x2tics, y2tics

The tics and tic label of the secondary axes. See ``xtics, ytics, ztics''.

legend

Legend describing the plots. Supported properties are:

     position : position of the legend
     width    : number of character widths to be added or subtracted to the
              : region of the legend
     height   : number of character heights to be added or subtracted to the
              : region of the legend
     align    : alignment of the text label. Left or right (default)
     order    : order of the keys
     title    : title of the legend
     sample   : format of the sample lines
     border   : border of the legend
 
 

See border for the available options of border

E.g.

     legend => {
        position => "outside bottom",
        width    => 3,
        height   => 4,
        align    => "right",
        order    => "horizontal reverse",
        title    => "Title of the legend",
        sample   => {
            length   => 3,
            position => "left",
            spacing  => 2,
        },
        border   => {
            linetype => 2,
            width    => 1,
            color    => "blue",
        },
     }
 
 

timeaxis

Specify the axes of which the tic labels are date/time string. Possible values are combinations of ``x'', ``y'', ``x2'', and ``y2'' joined by ``,''. E.g.

     timeaxis => "x, y2"
 
 

means that the x-axis and y2-axis are data/time axes.

border

Border of the graph. Properties supported are ``linetype'', ``width'', and ``color''. E.g.

     border => {
         linetype => 3,
         width    => 2,
         color    => '#ff00ff',
     }
 
 

grid

Major grid lines. E.g.

     grid => {
         type  => 'dash',
         width => 2,
         ....
     }
 
 

Supported properties are:

     type   : line type of the grid lines (default: dot)
     width  : line width (defaulr: 0)
     color  : line color (default: black)
     xlines : whether the vertical grid lines are drawn (on/off)
     ylines : whether the horizontal grid lines are drawn (on/off)
 
 

tmargin, bmargin

Top and bottom margin (in character height). This option has no effect in 3D plots. E.g.

     tmargin => 10
 
 

lmargin, rmargin

Left amd right margin (in character width). This option has no effect in 3D plots. See ``tmargin, bmargin''.

orient

Orientation of the image. Possible values are ``lanscape'' (default) and ``portrait''. E.g.

     orient => "portrait"
 
 

imagesize

Size (length and height) of the image relative to the default. E.g.

     imagesize => "0.8, 0.5"
 
 

size

Size of the plot relative to the chart size. This is useful in some multi-plot such as inset chart. E.g.

     size => "0.5, 0.4"
 
 

origin

Origin of the chart. This is useful in some multi-plot such as inset chart. E.g.

     origin => "0.1, 0.5"
 
 

timestamp

Time stamp of the plot. To place the time stamp with default setting,

     timestamp => 'on'
 
 

To set the format of the time stamp as well, e.g.,

     timestamp => {
        fmt    => '%d/%m/%y %H:%M',
        offset => "10,-3",
        font   => "Helvetica",
     }
 
 

bg (experimental)

Background color of the chart. This option has no effect in the sub-chart of multiplot and is experimental. E.g.

     bg => "yellow"
 
 

Properties can be specified in hash. E.g.,

     bg => {
         color   => "yellow",
         density => 0.2,
     }
 
 

Supported properties are:

     color   : color (name ot RRGGBB value)
     density : density of the coloring
 
 

plotbg (experimental)

Background color of the plot area. This option has no effect in 3D plots and is experimental. See bg.

gnuplot

The path of Gnuplot executable. This option is useful if you are using Windows or have multiple versions of Gnuplot installed. E.g.,

     gnuplot => "C:\Program Files\...\gnuplot\bin\wgnuplot.exe";   # for Windows
 
 

convert

The path of convert executable of ImageMagick. This option is useful if you have multiple convert executables.

terminal

The terminal driver that Gnuplot uses. The default terminal is ``postscript''. This attribute is not recommended to be changed unless you are familiar with the Gnuplot syntax. Please check the output image carefully if you use this in production code.

Terminal is not necessarily related to the output image format. You may convert the image format by the "convert()" method.

Chart Methods

new

     my $chart = Chart::Gnuplot->new(%options);
 
 

Constructor of the chart object. If no option is specified, default values would be used. See ``Chart Options'' for available options.

set

General set methods for arbitrary number of options.

     $chart->set(%options);
 
 

plot2d

     $chart->plot2d(@dataSets);
 
 

Plot the data sets in a 2D chart. Each dataset is represented by a dataset object.

plot3d

     $chert->plot3d(@dataSets);
 
 

Plot the data sets in a 3D chart. Each dataset is represented by a dataset object. It is not yet completed. Only basic features are supported.

multiplot

     $chert->multiplot(@charts);
 
 

Plot multiple charts in the same image.

add2d

Add a 2D dataset to a chart without plotting it out immediately. Used with "multiplot".

add3d

Add a 3D dataset to a chart without plotting it out immediately. Used with "multiplot".

label

Add an arbitrary text label. e.g.,

     $chart->label(
         text       => "This is a label",
         position   => "0.2, 3 left",
         offset     => "2,2",
         rotate     => 45,
         font       => "arial, 15",
         fontcolor  => "dark-blue",
         pointtype  => 3,
         pointsize  => 5,
         pointcolor => "blue",
     );
 
 

arrow

Draw arbitrary arrow. e.g.,

     $chart->arrow(
         from      => "0,2",
         to        => "0.3,0.1",
         linetype  => 'dash',
         width     => 2,
         color     => "dark-blue",
         headsize  => 3,
         head      => 'both',
     );
 
 

copy

Copy the chart object. This method is especially useful when you want to copy a chart with highly customized format. E.g.

     my $chart = Chart::Gnuplot->new(
         ...
     );
 
     # $copy and $chart will have the same format
     my $copy = $chart->copy;
 
 

You may also make multiple copies . E.g.

     my @copies = $chart->copy(10);  # make 10 copies
 
 

convert

     $chart->convert($imageFmt);
 
 

Convert the image format to $imageFmt. See ``Chart Options'' for supported image formats.

png

     $chart->png;
 
 

Change the image format to PNG.

gif

     $chart->gif;
 
 

Change the image format to GIF.

jpg

     $chart->jpg;
 
 

Change the image format to JPEG.

ps

     $chart->ps;
 
 

Change the image format to postscript.

pdf

     $chart->pdf
 
 

Change the image format to PDF.

command

     $chart->command($gnuplotCommand);
 
 

Add a gnuplot command. This method is useful for the Gnuplot features that have not yet implemented.

DATASET OBJECT

The dataset object can be initiated by the "new" method. Properties of the dataset may be specified optionally when the object is initiated:

     my $dataset = Chart::Gnuplot::DataSet->new(%options);
 
 

The data source of the dataset can be specified by either one of the following ways:

1. Arrays of x values, y values and z values (in 3D plots) of the data points.

2. Array of data points. Each point is specified as an array of x, y, z coordinates

3. Data file.

4. Mathematical expression (for a function).

Dataset Options

xdata, ydata, zdata

The x, y, z values of the data points. E.g.

     xdata => \@x
 
 

If "xdata" is omitted but "ydata" is defined, the integer index starting from 0 would be used for "xdata".

points

Data point matrix of the format [[x1,y1], [x2,y2], [x3,y3], ...]

     points => \@points
 
 

datafile

Input data file

     datafile => $file
 
 

The data files are assumed to be space-separated, with each row corresponding to one data point. Lines beginning with ``#'' are considered as comments and would be ignored. Other formats are not supported at this moment.

func

Mathematical function to be plotted. E.g.

     func => "sin(x)*x**3"
 
 

Supported functions:

     abs(x)       : absolute value
     acos(x)      : inverse cosine
     acosh(x)     : inverse hyperbolic cosine
     arg(x)       : complex argument
     asin(x)      : inverse sine
     asinh(x)     : inverse hyperbolic sine
     atan(x)      : inverse tangent
     atanh(x)     : inverse hyperbolic tangent
     besj0(x)     : zeroth order Bessel function of the first kind
     besj1(x)     : first order Bessel function of the first kind
     besy0(x)     : zeroth order Bessel function of the second kind
     besy1(x)     : first order Bessel function of the second kind
     ceil(x)      : ceiling function
     cos(x)       : cosine
     cosh(x)      : hyperbolic cosine
     erf(x)       : error function
     erfc(x)      : complementary error function
     exp(x)       : expontial function
     floor(x)     : floor function
     gamma(x)     : gamma function
     ibeta(a,b,x) : incomplete beta function
     inverf(x)    : inverse error function
     igamma(a,x)  : incomplete gamma function
     imag(x)      : imaginary part
     invnorm(x)   : inverse normal distribution function
     int(x)       : integer part
     lambertw(x)  : Lambert W function
     lgamma(x)    : log gamma function
     log(x)       : natural logarithm
     log10(x)     : common logarithm
     norm(x)      : normal distribution function
     rand(x)      : pseudo random number
     real(x)      : real part
     sgn(x)       : sign function
     sin(x)       : sine
     sinh(x)      : hyperbolic sine
     sqrt(x)      : square root
     tan(x)       : tangent
     tanh(x)      : hyperbolic tangent
 
 

Please see the Gnuplot manual for updated information.

Supported mathematical constants:

     pi : the circular constant 3.14159...
 
 

Supported arithmetic operators:

     addition           : +
     division           : /
     exponentiation     : **
     factorial          : !
     modulo             : %
     multiplication     : *
     subtraction        : -, e.g., 1-2
     unary minus        : -, e.g., -1
 
 

Supported logical operations:

     and                      : &&
     complement               : ~
     equality                 : ==
     greater than             : >
     greater than or equal to : >=
     inequality               : !=
     less than                : <
     less than or equal to    : <= 
     negation                 : !
     or                       : ||
     if ... than else ...     : ?:, e.g., a ? b : c
 
 

Parametric functions may be represented as hash. E.g.

     func => {x => 'sin(t)', y => 'cos(t)'}
 
 

will draw a circle.

title

Title of the dataset (shown in the legend).

style

The plotting style for the dataset, including

     lines          : join adjacent points by straight lines
     points         : mark each points by a symbol
     linespoints    : both "lines" and "points"
     dots           : dot each points. Useful for large datasets
     impluses       : draw a vertical line from the x-axis to each point
     steps          : join adjacent points by steps
     boxes          : draw a centered box from the x-axis to each point
     xerrorbars     : "dots" with horizontal error bars
     yerrorbars     : "dots" with vertical error bars
     xyerrorbars    : both "xerrorbars" and "yerrorbars"
     xerrorlines    : "linespoints" with horizontal error bars
     yerrorlines    : "linespoints" with vertical error bars
     xyerrorlines   : both "xerrorlines" and "yerrorlines"
     boxerrorbars   : "boxes" with "yerrorbars"
     boxxyerrorbars : use rectangles to represent the data with errors
     financebars    : finance bars for open, high, low and close price
     candlesticks   : candle sticks for open, high, low and close price
     hbars          : horizontal bars (experimental)
     hlines         : horizontal lines (experimental)
 
 

color

Color of the dataset in the plot. Can be a named color ot RBG (#RRGGBB) value. The supported color names can be found in the file doc/colors.txt in the distribution. E.g.

     color => "#99ccff"
     # or
     color => "dark-red"
 
 

width

Line width used in the plot.

linetype

Line type.

pointtype

Point type.

pointsize

Point size of the plot.

fill

Filling string. Has effect only on plotting styles ``boxes'', ``boxxyerrorbars'' and ``financebars''.

axes

Axes used in the plot. Possible values are ``x1y1'', ``x1y2'', ``x2y1'' and ``x2y2''.

timefmt

Time format of the input data. The valid format are:

     %d : day of the month, 1-31
     %m : month of the year, 1-12
     %y : year, 2-digit, 0-99
     %Y : year, 4-digit
     %j : day of the year, 1-365
     %H : hour, 0-24
     %M : minute, 0-60
     %s : seconds since the Unix epoch (1970-01-01 00:00 UTC)
     %S : second, 0-60
     %b : name of the month, 3-character abbreviation
     %B : name of the month
 
 

smooth

The smooth method used in plotting data points. Supported methods include cubic splines (csplines), Bezier curve (bezier) and other. Please see Gnuplot manual for details.

Dataset Methods

new

     my $dataset = Chart::Gnuplot::DataSet->new(%options);
 
 

Constructor of the dataset object. If no option is specified, default values would be used. See ``Dataset Options'' for available options.

copy

Copy the dataset object. This method is especially useful when you want to copy a dataset with highly customized format. E.g.

     my $dataset = Chart::Gnuplot::DataSet->new(
         ...
     );
 
     # $copy and $dataset will have the same format and contain the same data
     my $copy = $dataset->copy;
 
 

You may also make multiple copies . E.g.

     my @copies = $dataset->copy(10);  # make 10 copies
 
 

EXAMPLES

Some simple examples are shown below. Many more come with the distribution.

1. Plot a mathematical expression

     my $chart = Chart::Gnuplot->new(
         output => "expression.png"
     );
 
     my $dataSet = Chart::Gnuplot::DataSet->new(
         func => "sin(x)"
     );
 
     $chart->plot2d($dataSet);
 
 

2. Plot from two Perl arrays, one for the x-axis data and the other the y-axis.

     my $chart = Chart::Gnuplot->new(
         output => "arrays.png"
     );
 
     my $dataSet = Chart::Gnuplot::DataSet->new(
         xdata => \@x,
         ydata => \@y,
     );
 
     $chart->plot2d($dataSet);
 
 

3. Plot x-y pairs

     # Data
     my @xy = (
         [1.1, -3],
         [1.2, -2],
         [3.5,  0],
         ...
     );
 
     my $chart = Chart::Gnuplot->new(
         output => "points.png"
     );
 
     my $dataSet = Chart::Gnuplot::DataSet->new(
         points => \@xy
     );
 
     $chart->plot2d($dataSet);
 
 

4. Plot data from a data file

     my $chart = Chart::Gnuplot->new(
         output => "file.png"
     );
 
     my $dataSet = Chart::Gnuplot::DataSet->new(
         datafile => "in.dat"
     );
 
     $chart->plot2d($dataSet);
 
 

5. Chart title, axis label and legend

     # Chart object
     my $chart = Chart::Gnuplot->new(
         output => "trigonometric.gif",
         title  => "Three basic trigonometric functions",
         xlabel => "angle in radian",
         ylabel => "function value"
     );
 
     # Data set objects
     my $sine = Chart::Gnuplot::DataSet->new(
         func  => "sin(x)",
         title => "sine function"
     );
     my $cosine = Chart::Gnuplot::DataSet->new(
         func  => "cos(x)",
         title => "cosine function"
     );
     my $tangent = Chart::Gnuplot::DataSet->new(
         func  => "tan(x)",
         title => "tangent function"
     );
 
     $chart->plot2d($sine, $cosine, $tangent);
 
 

6. Title in non-English characters (Thanks to WOLfgang Schricker)

     use Encode;
 
     my $title = ...   # Title with German umlauts
     $title = decode("utf8", $title);
 
     Chart::Gnuplot->new(
         encoding => 'iso-8859-1',
         title    => $title,
     );
 
 

7. Plot a financial time series

     my $chart = Chart::Gnuplot->new(
         output   => "dj.ps",
         title    => "Dow-Jones Index time series",
         timeaxis => 'x',
         xtics    => {
             labelfmt => '%b%y',
         },
     );
 
     my $dow = Chart::Gnuplot::DataSet->new(
         file    => "dj.dat",
         timefmt => '%Y-%m-%d',      # time format of the input data
         style   => "candlesticks",
         grid    => 'on',
     );
 
     $chart->plot2d($dow);
 
 

8. Plot several graphs on the same image

     my $chart = Chart::Gnuplot->new(
         output => "multiplot.gif",
     );
 
     my $left = Chart::Gnuplot->new();
     my $sine = Chart::Gnuplot::DataSet->new(
         func  => "sin(x)",
     );
     $left->add2d($sine);
 
     my $center = Chart::Gnuplot->new();
     my $cosine = Chart::Gnuplot::DataSet->new(
         func  => "cos(x)",
     );
     $center->add2d($cosine);
 
     my $right = Chart::Gnuplot->new();
     my $tangent = Chart::Gnuplot::DataSet->new(
         func  => "tan(x)",
     );
     $right->add2d($tangent);
 
     # Place the Chart::Gnuplot objects in matrix to indicate their locations
     $chart->multiplot([
         [$left, $center, $right]
     ]);
 
 

FUTURE PLAN

1. Improve the manual.

2. Add more control to the 3D plots.

3. Add curve fitting method.

4. Improve the testsuite.

5. Reduce number of temporary files generated.

REQUIREMENTS

File::Copy, File::Temp, Storable

Gnuplot <http://www.gnuplot.info>

ImageMagick <http://www.imagemagick.org> (for full feature)

SEE ALSO

Gnuplot official website <http://www.gnuplot.info>

AUTHOR

Ka-Wai Mak <kwmak@cpan.org>

COPYRIGHT

Copyright (c) 2008-2010 Ka-Wai Mak. All rights reserved.

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.