Chart Options¶

output

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

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

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    : sides on which border is displayed
    linetype : line type
    width    : line width
    color    : line coler

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 => {
        linetype => 'dash',
        width    => 2,
        ....
    }

Supported properties are:

    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)

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'

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

Supported properties are:

    fmt    : date-time format
    offset : offset relative to the default position
    font   : font face (and optionally font size)

bg

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

Supported properties are:

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

plotbg

Background color of the plot area. This option has no effect in 3D plots. See bg for supported properties.

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

Chart Options Not Mentioned Above¶

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

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

E.g.

    $chart->set(view => '30,60');

will be translated to the Gnuplot statement

    set view 30,60

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.

multiplot

    $chart->multiplot(@charts);

Plot multiple charts in the same image.

animate

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

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",
    );

Supported properties are:

    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

arrow

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

Supported properties are:

    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')

line

Draw arbitrary straight line. e.g.,

    $chart->line(
        from     => "0,2",
        to       => "0.3,0.1",
        linetype => 'dash',
        width    => 2,
        color    => "dark-blue",
    );

Supported properties are:

    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

rectangle

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.

ellipse

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

circle

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

polygon

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.

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

Convert the image format by ImageMagick, e.g.

    $chart->convert('png');

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.

    $chart->command(\@gnuplotCommands);

Add a list of gnuplot commands.

execute

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.

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)
    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".

color

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"

width

Line width used in the plot. The default width is 1.

linetype

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

is equivalent to

    linetype => 'dash'

Note: the line type may not be displayed as the name if "terminal" is set and is not postscript.

pointtype

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

is equivalent to

    pointtype => 'square'

Note: the point type may not be displayed as the name if "terminal" is set and is not postscript.

pointsize

Point size of the plot. E.g.

    pointsize => 3

The default point size is 1.

fill

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

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

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.

using

The "using" keyword of Gnuplot.

every

The "every" keyword of Gnuplot. Has effect only if the data is input from "datafile".

index

The "index" keyword of Gnuplot. Has effect only if the data is input from "datafile".

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