Chart::Gnuplot - Plot graph using Gnuplot in Perl on the fly
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, ...);
This Perl 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, it is recommended to install the convert program of ImageMagick as well. Please refer to "MECHANISM OF THIS MODULE" for details.
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 can be found in SourceForge http://chartgnuplot.sourceforge.net.
Casual users may skip this session.
When the plotting method (e.g. plot2d) is called, Chart::Gnuplot would generate a Gnuplot script based on the information in the chart object and dataset object. Then it would call the Gnuplot program. Unless specified explicitly in terminal of the Chart object, Chart::Gnuplot would by default generate the image in PS format first and then convert the image (by ImageMagick) based on the extension of the filename. The rationale of this approach is that the postscript terminal is so far the best developed teriminal and so this would let users to enjoy the power of Gnuplot as much as possible.
Because the default terminal is postscript, if ImageMagick is not installed, you would always need to specify the terminal if the output format is not PS (or EPS).
On the other hand, for some image formats, e.g. mousing supported SVG, which ImageMagick cannot be converted to, the terminal must be set explicitly (e.g., svg mousing in this case).
svg mousing
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);
Output file of the graph. E.g.
output => "fig/chart.png",
By default, the image format is detected automatically by the extension of the filename. (Please refer to "MECHANISM OF THIS MODULE" for details). However, it can also be changed manually by the terminal option or the format conversion methods such as convert and png.
Some of image formats that can be detected automatically 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 format will be output.
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).
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)
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.
Range of the x-axis, y-axis and z-axis in the plot, e.g.
xrange => [0, "pi"]
would make the plot from x = 0 to x = 3.14159...
Range of the secondary (top horizontal and right vertical) axes of the plot. See "xrange, yrange, zrange".
Range of the parametric parameter (t for 2D plots, while u and v for 3D plots). See "xrange, yrange, zrange".
The tics and tic label on the x-axis, y-axis and z-axis. E.g.
xtics => { labels => [-10, 15, 20, 25], labelfmt => "%3f", .... }
If you set this to undef. E.g.,
undef
xtics => undef
Then this option will be explicitly unset and the chart will have not have tic marks on the specified axis.
labels : the locations of the tic labels start : the starting value for manually-specified range incr : the increment for manually-specified range end : the ending value for manually-specified range 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)
The tics and tic label of the secondary axes. See "xtics, ytics, ztics".
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", }, }
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 of the graph. Properties supported are:
sides : sides on which border is displayed linetype : line type width : line width color : line coler
border => { sides => "bottom, left", linetype => 3, width => 2, color => '#ff00ff', }
sides tells which side(s) will be displayed. Default is all four borders for 2D plots, and four bottom and left vertial borders for 3D plots. Acceptable valurs are the 12-bit code (see the Gnuplot manual) or the following names:
sides
bottom left top right bottom left front bottom left back bottom right front bottom right back left vertical right vertical front vertical back vertical top left front top left back top right front top right back
border => undef
Then this option will be explicitly unset and the chart will have not have any border.
Major grid lines. E.g.
grid => { linetype => 'dash', width => 2, .... }
linetype : 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)
Top and bottom margin (in character height). This option has no effect in 3D plots. E.g.
tmargin => 10
Left amd right margin (in character width). This option has no effect in 3D plots. See "tmargin, bmargin".
Orientation of the image. Possible values are "lanscape" (default) and "portrait". E.g.
orient => "portrait"
Size (length and height) of the image relative to the default. E.g.
imagesize => "0.8, 0.5"
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 of the chart. This is useful in some multi-plot such as inset chart. E.g.
origin => "0.1, 0.5"
Time stamp of the plot. To place the time stamp with default setting,
timestamp => 'on'
Properties of the time stamp (such as date-time format) can also be set, e.g.
timestamp => { fmt => '%d/%m/%y %H:%M', offset => "10,-3", font => "Helvetica", }
fmt : date-time format offset : offset relative to the default position font : font face (and optionally font size)
Background color of the chart. This option has no effect in the sub-chart of multiplot. E.g. to give the chart a yellow background,
bg => "yellow"
Properties can be specified in hash. E.g.,
bg => { color => "yellow", density => 0.2, }
color : color (name ot RRGGBB value) density : density of the coloring
Background color of the plot area. This option has no effect in 3D plots. See bg for supported properties.
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
The path of convert executable of ImageMagick. This option is useful if you have multiple convert executables.
The terminal driver that Gnuplot uses. E.g.,
terminal => 'svg mousing'
The default value is postscript enhanced color. Terminal is not necessarily related to the output image format. E.g., you may use gif terminal and then convert the image format to jpg by the convert() method.
postscript enhanced color
If Chart::Gnuplot encounters options not mentions above, it would convert them to Gnuplot set statements. E.g. if the chart object is
$chart = Chart::Gnuplot->new( ... foo => "FOO", );
the generated Gnuplot statements would be:
... set foo FOO
This mechanism lets Chart::Gnuplot support many features not mentioned above (such as "cbrange", "samples", "view" and so on).
Constructor of the chart object. If no option is specified, default values would be used. See "Chart Options" for available options.
General set methods for arbitrary number of options.
$chart->set(%options);
$chart->set(view => '30,60');
will be translated to the Gnuplot statement
set view 30,60
$chart->plot2d(@dataSets);
Plot the data sets in a 2D chart. Each dataset is represented by a dataset object.
$chert->plot3d(@dataSets);
Plot the data sets in a 3D chart. Each dataset is represented by a dataset object.
$chart->multiplot(@charts);
Plot multiple charts in the same image.
Create animated gif. E.g.
# Create (main) chart object my $chart = Chart::Gnuplot->new( output => "animate.gif", ); # Add frames to the (main) chart object my $T = 30; # number of frames my @c; for (my $i = 0; $i < $T; $i++) { $c[$i] = Chart::Gnuplot->new(xlabel => 'x'); my $ds = Chart::Gnuplot::DataSet->new( func => "sin($i*2*pi/$T + x)", ); $c[$i]->add2d($ds); } # Create animation $chart->animate( charts => \@c, delay => 10, # delay 0.1 sec between successive images );
charts : chart sequence used to create the animation delay : delay (in units of 0.01 second) between successive images, default : value is 5
See add2d and add3d.
Add a 2D dataset to a chart without plotting it out immediately. Used with multiplot or animate.
multiplot
animate
Add a 3D dataset to a chart without plotting it out immediately. Used with multiplot or animate.
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", );
text : label text position : position of the label offset : offset relative to the default position rotate : rotation in degrees font : font face (and optionally font size) fontcolor : color of the text pointtype : point type pointsize : point size pointcolor : point color
Draw arbitrary arrow. e.g.,
$chart->arrow( from => "0,2", to => "0.3,0.1", linetype => 'dash', width => 2, color => "dark-blue", head => { size => 2, angle => 30, }, );
from : starting position to : ending position (position of the arrow head) rto : ending position relative to the starting position linetype : line type width : line width color : color head : arrow head
Supported properties of the arrow head are:
size : size of the head angle : angle (in degree) between the arrow and the head branch direction : head direction ('back', 'both' or 'off')
Draw arbitrary straight line. e.g.,
$chart->line( from => "0,2", to => "0.3,0.1", linetype => 'dash', width => 2, color => "dark-blue", );
from : starting position to : ending position (position of the arrow head) rto : ending position relative to the starting position linetype : line type width : line width color : color
Draw arbitrary rectangle. e.g.,
$chart->rectangle( from => "screen 0.2, screen 0.2", to => "screen 0.4, screen 0.4", fill => { density => 0.2, color => "#11ff11", }, border => {color => "blue"}, linewidth => 3, layer => 'front', index => 1, );
Most properties of a rectangle can be classified into location, dimension, filling and border. Location and dimension of the rectangle can be specified by from and to, or from and rto, or at, width and height. Filling can be specified by color and density, or pattern. Border has only one property color so far. Besides, linewidth controls the line width of the border as well as the filling pattern. The layer that the rectangle is drawn is set by layer. The index is a tag of the rectangle, which usually can be omitted.
from
to
rto
at
width
height
color
density
pattern
linewidth
layer
index
Draw arbitrary ellipse. e.g.,
$chart->ellipse( at => "screen 0.2, screen 0.2", width => 0.2, height => 0.5 fill => {pattern => 2}, border => {color => "blue"}, );
The properties of ellipse is the same as those of rectangle, except that its location and dimension must be set by at, width and height.
ellipse
Draw arbitrary circle. e.g.,
$chart->circle( at => "screen 0.2, screen 0.2", size => 0.5 fill => {pattern => 2}, layer => 'behind', );
The properties of circle is the same as those of rectangle, except that its location and dimension must be set by at, width and height.
circle
Draw arbitrary polygon. e.g.,
$chart->polygon( vertices => [ " 0, 0.2", "-2, -0.2", {to => "2, -0.3"}, {rto => "0, 0.3"}, ], fill => {pattern => 2}, border => {color => "blue"}, );
The location and dimension of the polygon are specified by an array of vertices. Except border, pattern of fill, index and layer, other properties of rectangle is not supported.
vertices
border
fill
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 is a copy of $chart my $copy = $chart->copy;
You may also make multiple copies . E.g.
my @copies = $chart->copy(10); # make 10 copies
Convert the image format by ImageMagick, e.g.
$chart->convert('png');
$chart->png;
Change the image format to PNG.
$chart->gif;
Change the image format to GIF.
$chart->jpg;
Change the image format to JPEG.
$chart->ps;
Change the image format to postscript.
$chart->pdf
Change the image format to PDF.
$chart->command($gnuplotCommand);
Add a gnuplot command. This method is useful for the Gnuplot features that have not yet implemented.
$chart->command(\@gnuplotCommands);
Add a list of gnuplot commands.
Execute Gnuplot. Normally users do not need to call this method directly because this method would be called automatically by other methods such as plot2d, multiplot and animate.
The dataset object can be initiated by the new method. Properties of the dataset may be specified optionally when the object is initiated:
new
my $dataset = Chart::Gnuplot::DataSet->new(%options);
The data source of the dataset can be specified by either one of the following ways:
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.
xdata
ydata
Data point matrix of the format [[x1,y1], [x2,y2], [x3,y3], ...]
points => \@points
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.
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 of the dataset (shown in the legend).
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) vectors : arrows circles : circles, for say, bubble charts histograms : for plotting histograms
hbars and hlines are available only if the data is input from points or (x,y)data.
hbars
hlines
points
(x,y)data
Color of the dataset in the plot. Can be a named color or RBG (#RRGGBB) value. The supported color names can be found in the file doc/colors.txt in the distribution. E.g.
color => "#99ccff"
is equivalent to
color => "dark-red"
Line width used in the plot. The default width is 1.
Line type. Can be an integer or line type name. The supported line type names can be found in the file doc/linetypes.txt in the distribution. E.g.
linetype => 3
linetype => 'dash'
Note: the line type may not be displayed as the name if terminal is set and is not postscript.
terminal
Point type. Can be an integer or point type name. The supported point type names can be found in the file doc/pointtypes.txt in the distribution. E.g.
pointtype => 64
pointtype => 'square'
Note: the point type may not be displayed as the name if terminal is set and is not postscript.
Point size of the plot. E.g.
pointsize => 3
The default point size is 1.
Filling the boxes. Has effect only on plotting styles with boxes, such as "boxes", "boxxyerrorbars" and "financebars". To fill with pattern,
fill => { pattern => 1, }
pattern may be an interger from 0 (no filling) to 7.
To fill with solid,
fill => { color => '#33bb33', density => 0.2, }
color may be named color or RGB (#RRGGBB). density may be a real number from 0 (empty) to 1.
Border of the boxes. Has effect only on plotting styles with boxes and if fill is set. color (either named color or RGB) is the only supported property. E.g.
border => { color => 'blue', }
Axes used in the plot. Possible values are "x1y1", "x1y2", "x2y1" and "x2y2".
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
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.
The using keyword of Gnuplot.
using
The every keyword of Gnuplot. Has effect only if the data is input from datafile.
every
datafile
The index keyword of Gnuplot. Has effect only if the data is input from datafile.
Constructor of the dataset object. If no option is specified, default values would be used. See "Dataset Options" for available options.
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;
my @copies = $dataset->copy(10); # make 10 copies
Some simple examples are shown below. Many more come with the distribution.
my $chart = Chart::Gnuplot->new( output => "expression.png" ); my $dataSet = Chart::Gnuplot::DataSet->new( func => "sin(x)" ); $chart->plot2d($dataSet);
my $chart = Chart::Gnuplot->new( output => "arrays.png" ); my $dataSet = Chart::Gnuplot::DataSet->new( xdata => \@x, ydata => \@y, ); $chart->plot2d($dataSet);
# 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);
my $chart = Chart::Gnuplot->new( output => "file.png" ); my $dataSet = Chart::Gnuplot::DataSet->new( datafile => "in.dat" ); $chart->plot2d($dataSet);
# 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);
use Encode; my $title = ... # Title with German umlauts $title = decode("utf8", $title); Chart::Gnuplot->new( encoding => 'iso-8859-1', title => $title, );
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);
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] ]);
Carp, File::Copy, File::Temp, Storable
Gnuplot http://www.gnuplot.info
ImageMagick http://www.imagemagick.org (for full feature)
Gnuplot official website http://www.gnuplot.info
Ka-Wai Mak <kwmak@cpan.org>
Copyright (c) 2008-2011, 2013-2015 Ka-Wai Mak. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Chart::Gnuplot, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Chart::Gnuplot
CPAN shell
perl -MCPAN -e shell install Chart::Gnuplot
For more information on module installation, please visit the detailed CPAN module installation guide.