Chart::Gnuplot(3pm)

📦
version 0.23 · 2 versions
  • 0.23 · debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
  • 0.23 · ubuntu jammy
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Chart::Gnuplot 💖

okay bestie, welcome to the Chart::Gnuplot(3pm) man page — straight out of User Contributed Perl Documentation, and no cap, it's a banger. Buckle up, we're plotting graphs in Perl with Gnuplot on the fly. ✨

🌸 NAME 🌸

Chart::Gnuplot — plot a graph using Gnuplot in Perl, on the fly, live, in real time, no waiting. 💅

✨ SYNOPSIS ✨

Here's the whole vibe in one go, bestie:

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 🦋

So this Perl module plots graphs using GNUPLOT, on the fly. 🫶 But fr fr, to use it you need gnuplot installed. And if you wanna generate an image format that isn't PS or EPS, you should highkey go install the convert program from ImageMagick too. If you're curious why, go peek at "MECHANISM OF THIS MODULE" below — it's giving lore. 👑

To plot a chart with Chart::Gnuplot, you need two things: a chart object and at least one dataset object. Chart object holds all the chart-level tea — output file, chart title, axes labels, all of it. Dataset object holds the tea about the actual dataset being plotted: where the data points come from, the dataset label, what color to plot it in, and more.

Once your chart object and dataset object(s) exist, you plot with the plot2d, plot3d or multiplot method of the chart object, like:

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

ngl, the best way to actually get what Chart::Gnuplot can do is to just look at examples. And there are SO many examples over at SourceForge <http://chartgnuplot.sourceforge.net>. go look, it's iconic. 🌈

🧚 MECHANISM OF THIS MODULE 🧚

Casual users may skip this session. (but like... it's interesting, just saying 🙈)

When the plotting method (e.g. plot2d) gets called, Chart::Gnuplot generates a Gnuplot script based on everything in the chart object and dataset object. Then it calls the Gnuplot program. Unless you explicitly set terminal in the Chart object, Chart::Gnuplot will by default generate the image in PS format first, and then convert the image (using ImageMagick) based on the extension of the filename. The reason for this whole approach? The postscript terminal is, so far, the best developed terminal — so this lets users enjoy the power of Gnuplot as much as possible. periodt. 💅

Because the default terminal is postscript, if ImageMagick is not installed, you'll always need to specify the terminal whenever the output format isn't PS (or EPS). 😭

And on the other hand — for some image formats, e.g. mousing-supported SVG, which ImageMagick cannot convert to, you must set the terminal explicitly (e.g., "svg mousing" in this case).

👑 CHART OBJECT 👑

You initiate the chart object with the new method. Chart properties can optionally be specified when the object is initiated:

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

🎀 Chart Options 🎀

output

Output file of the graph. E.g.

output => "fig/chart.png",

By default, the image format is auto-detected from the filename extension. (Peep "MECHANISM OF THIS MODULE" for the details.) But you can also change it manually with the terminal option or with the format conversion methods like convert and png.

Some of the image formats that can be detected automatically:

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, postscript format will be output. 🖨️

title

Title of the chart. E.g.,

title => "Chart title"

Properties of the chart title can be specified in a 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 — does the title contain subscript/superscript/greek? (on/off)

Default values get used for any property you don't specify. And heads up: these properties have 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 a 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 — does the title contain subscript/superscript/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 go 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 labels 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 not have any tic marks on the specified axis. gone. deleted. 💅

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 labels
  • 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 adjacent major tics
  • mirror — turn on and off the tic label of the secondary axis. No effect for ztics (on/off)

x2tics, y2tics

The tics and tic labels of the secondary axes. See "xtics, ytics, ztics".

legend

The 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 which axes have tic labels that are date/time strings. 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 date/time axes. 🕰️

border

Border of the graph. Properties supported are:

  • sides — sides on which the border is displayed
  • linetype — line type
  • width — line width
  • color — line 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 vertical borders for 3D plots. Acceptable values 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 not have any border. bye 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 (default: 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 and 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 — sets the orientation. Like, portrait vs landscape, the whole vibe of how your plot sits. Example:
orient => "portrait"
  • imagesize — how big the image is (length AND height) compared to the default size. Bestie, it's a scale factor situation:
imagesize => "0.8, 0.5"
  • size — how big the plot is relative to the chart size. Lowkey iconic for multi-plot setups like inset charts where you're nesting one plot inside another. Example:
size => "0.5, 0.4"
  • origin — where the chart starts from, aka its origin. Also a multi-plot / inset-chart girlie. Example:
origin => "0.1, 0.5"
  • timestamp — the time stamp of the plot 🕐. Want it with all the default settings? Just:
timestamp => 'on'

You can also set its properties (like the date-time format), no cap:

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

The properties it supports 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 🎨. Heads up though: this option does nothing in the sub-chart of multiplot. Periodt. Wanna give your chart a yellow background?
bg => "yellow"

You can also pass properties as a hash, like:

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

The properties it supports are:

color   : color (name or RRGGBB value)
density : density of the coloring
  • plotbg — background color of the plot area. ⚠️ This one has no effect in 3D plots. For the properties it supports, go look at bg above, they're the same.
  • gnuplot — the path to the Gnuplot executable. Super useful if you're on Windows or you've got multiple versions of Gnuplot installed and you need to be specific about which one:
gnuplot => "C:\Program Files\...\gnuplot\bin\wgnuplot.exe"   # for Windows
  • convert — the path to the convert executable from ImageMagick. Reach for this when you've got multiple convert executables lying around and you need to pick the right one.
  • terminal — the terminal driver that Gnuplot uses. Like:
terminal => 'svg mousing'

The default value is "postscript enhanced color". And bestie, important lore: the terminal is not necessarily related to the output image format. For example, you can use the gif terminal and then convert the image format to jpg using the convert() method. 💅

✨ Chart Options Not Mentioned Above ✨

So if Chart::Gnuplot bumps into options that nobody mentioned above, it just... converts them into Gnuplot set statements. Iconic behaviour honestly. So if your chart object looks like:

$chart = Chart::Gnuplot->new(
    ...
    foo => "FOO",
);

then the Gnuplot statements it generates will be:

...
set foo FOO

This little mechanism is what lets Chart::Gnuplot support a whole bunch of features that aren't written up above — things like "cbrange", "samples", "view" and so on. Slay.

🎀 Chart Methods 🎀

new ✨

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

The constructor of the chart object 🫶. If you don't pass any option, default values get used. For all the available options, go see "Chart Options".

set ✨

The general set method for an arbitrary number of options:

$chart->set(%options);

Example:

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

which gets translated into the Gnuplot statement:

set view 30,60

plot2d ✨

$chart->plot2d(@dataSets);

Plots your data sets in a 2D chart 🌸. Every single dataset is represented by a dataset object.

plot3d ✨

$chert->plot3d(@dataSets);

Plots your data sets in a 3D chart 🦋. Every single dataset is represented by a dataset object. (Yes, the original really does spell it $chert up there. We keep the lore intact. 💀)

multiplot ✨

$chart->multiplot(@charts);

Plots multiple charts inside the same image. The way it just... stacks them. 👑

animate ✨

Creates an animated gif, bestie. Example:

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

The properties it supports are:

charts : chart sequence used to create the animation
delay  : delay (in units of 0.01 second) between successive images, default
       : value is 5

Go check out add2d and add3d for the other half of this story. 🎬

add2d ✨

Adds a 2D dataset to a chart without plotting it out immediately. This is the one you pair up with "multiplot" or "animate".

add3d ✨

Adds a 3D dataset to a chart without plotting it out immediately. Also besties with "multiplot" and "animate".

label ✨

Adds an arbitrary text label. Like:

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

The properties it supports 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 ✨

Draws an arbitrary arrow, fr fr:

$chart->arrow(
    from     => "0,2",
    to       => "0.3,0.1",
    linetype => 'dash',
    width    => 2,
    color    => "dark-blue",
    head     => {
        size  => 2,
        angle => 30,
    },
);

The properties it supports 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

And the properties supported by the arrow head itself 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 ✨

Draws an arbitrary straight line:

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

The properties it supports 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 ✨

Draws an arbitrary rectangle 🎁:

$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 of a rectangle's properties fall into four little categories: location, dimension, filling and border. Location and dimension can be set by "from" and "to", or "from" and "rto", or "at", "width" and "height". Filling can be set by "color" and "density", or "pattern". The border has exactly one property so far: "color". Also, "linewidth" controls the line width of the border as well as the filling pattern. Where the rectangle gets drawn is set by "layer". And "index" is a tag of the rectangle — usually you can just skip it. 💅

ellipse ✨

Draws an arbitrary ellipse:

$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" are the exact same as those of rectangle, EXCEPT that its location and dimension must be set by "at", "width" and "height". No negotiating on that one.

circle ✨

Draws an arbitrary circle:

$chart->circle(
    at    => "screen 0.2, screen 0.2",
    size  => 0.5
    fill  => {pattern => 2},
    layer => 'behind',
);

The properties of "circle" are the same as those of rectangle, EXCEPT that its location and dimension must be set by "at", "width" and "height". (Yes, it says "width" and "height" here too — we report, we don't judge. 🙈)

polygon ✨

Draws an arbitrary polygon:

$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 get specified by an array of "vertices". And here's the tea: except for "border", "pattern" of "fill", "index" and "layer", none of the other rectangle properties are supported. 🚫

copy ✨

Copies the chart object. This method is ESPECIALLY useful when you want to copy a chart with a highly customized format. Like:

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

# $copy is a copy of $chart
my $copy = $chart->copy;

You can also make multiple copies, bestie. Get that clone army:

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

convert ✨

Converts the image format using ImageMagick. Like:

$chart->convert('png');

png ✨

$chart->png;

Changes the image format to PNG. 🖼️

gif ✨

$chart->gif;

Changes the image format to GIF.

jpg ✨

$chart->jpg;

Changes the image format to JPEG.

ps ✨

$chart->ps;

Changes the image format to postscript.

pdf ✨

$chart->pdf

Changes the image format to PDF. 📄

command ✨

$chart->command($gnuplotCommand);

Adds a gnuplot command. This one's your bestie for Gnuplot features that haven't been implemented yet.

$chart->command(\@gnuplotCommands);

Adds a whole LIST of gnuplot commands. Queue them up. 🌈

execute ✨

Executes Gnuplot. Normally you do not need to call this method directly, because it gets called automatically by other methods like plot2d, multiplot and animate. It's the backstage crew, not the main character. 🎭

💾 DATASET OBJECT 💾

Okay bestie, so the dataset object is your actual data — the points, the lines, the whole moment. You spin one up with the new method, and you can pass in properties right when you create it:

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

Now, where does the data come from? You've got four options, pick your fighter:

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

xdata => \@x

And the plot twist: if you leave out xdata but ydata is defined, then the integer index starting from 0 gets used for xdata. Free x-axis, you're welcome 💅

points

Data point matrix, formatted like [[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. (ngl, that's just how it is.)

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. A whole circle bestie, iconic behavior 🌈

title

Title of the dataset (shown in the legend). Your little name tag in the group chat ✨

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
Heads up: 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. So smooth, so slay 🦋

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. Easy peasy 🍓

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

Ten copies?? Not me making an entire girl group of datasets 💅✨

✨ EXAMPLES ✨

Okay bestie, 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);
  1. 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);
  1. 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);
  1. 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);
  1. 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);
  1. 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,
);
  1. 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);
  1. 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 curve fitting method. 📈
  3. Improve the testsuite. 🧪
  4. Reduce number of temporary files generated. 🗑️

💖 REQUIREMENTS 💖

You're gonna need: Carp, File::Copy, File::Temp, Storable. ✨

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

And for the full feature: 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 (c) 2008-2011, 2013-2015 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.

This page came from Chart::Gnuplot(3pm), source/version perl v5.34.0, dated 2022-06-10. Stay iconic, bestie! 💅✨🦋

📦 where this page comes from