Chart::Gnuplot(3pm)					User Contributed Perl Documentation				       Chart::Gnuplot(3pm)

NAME

       Chart::Gnuplot - Plot graph using Gnuplot in Perl 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 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, 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 can be found in SourceForge
       <http://chartgnuplot.sourceforge.net>.

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"]

       would make the plot from x = 0 to x = 3.14159...

       x2range, y2range

       Range of the secondary (top horizontal and right vertical) axes of the plot.  See "xrange, yrange, zrange".

       trange, urange, vrange

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

       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",
	     ....
	  }

       If you set this to "undef". E.g.,

	   xtics => undef

       Then this option will be explicitly unset and the chart will have not have tic marks on the specified axis.

       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 "sides", "linetype", "width", and "color". E.g.

	   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:

	   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

       If you set this to "undef". E.g.,

	   border => undef

       Then this option will be explicitly unset and the chart will have not have any border.

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

       animate

       Create animated gif. E.g.

	   my $chart = Chart::Gnuplot->new(
	       output => "animate.gif",
	   );

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

	   $chart->animate(
	       charts => @c,
	       delay  => 10,   # delay 0.1 sec between successive images
	   );

       Supported properties are:

	   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.

       add2d

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

       add3d

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

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

WISH LIST

       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

       Carp, 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-2011 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.

perl v5.12.4							    2011-09-17						       Chart::Gnuplot(3pm)