Gaston tutorial

  • explain that plot returns a figure object
  • explain delays and how to configure them

Gaston is a plotting package for Julia that relies on gnuplot. It focuses on fast, simple plotting, and leaves publication-quality plots to tools such as pgfplots. This tutorial covers Gaston version 0.7.2. We recommend reading gnuplot's user manual. Gaston follows many of gnuplot's conventions and many options need to be specified in gnuplot's syntax.

Gaston's code repository is here.

Contents

Installation

Make sure that gnuplot is installed on your system and in the system path. Confirm by running in Julia:

In [1]:
run(`gnuplot --version`)
gnuplot 5.2 patchlevel 2

Any errors here mean that gnuplot is not properly installed.

On Windows, it is recommended to let gnuplot's installer add it to the PATH.

Once gnuplot is functional, install Gaston using Julia's package manager by running Pkg.add("Gaston"). Tests can be run with Pkg.test("Gaston") (all tests should pass).

Overview of main plotting commands

Gaston offers four types of plots: regular 2D plots, surface (3D) plots, histograms, and images. Start by loading it into your Julia session:

In [2]:
using Gaston

2D plots

To plot a vector y against a vector x, use the command plot.

In [3]:
t = 0:0.01:1
plot(t, sin.(2π*5*t))
Out[3]:
Gnuplot Produced by GNUPLOT 5.2 patchlevel 2 -1 -0.5 0 0.5 1 0 0.2 0.4 0.6 0.8 1 gnuplot_plot_1

You may control certain properties of the axes, as well as the curve. All axes properties are strings.

Property

Purpose

Allowed values

title

Plot title

Any string

xlabel

X axis label

Any string

ylabel

Y axis label

Any string

grid

Show/don't show grid

"", "on" or "off"

xrange

X axis limits

A valid gnuplot range, e.g. "[-3:2]"

yrange

Y valid limits

Same as xrange

box

Control key (legends) placement

Any valid gnuplot box specification, e.g. "top left"

A curve's properties are:

Property

Purpose

Allowed values

plotstyle

Plot with lines, points, errorbars...

One of lines, linespoints, points, impulses, boxes, errorlines, errorbars, dots, steps, fsteps, fillsteps, financebars

legend

Curve description

Any string

color

Line color

Any color supported by gnuplot

linewidth

Line width

A positive number

linestyle

More complex lines

A string containing a combination of -, ., _ and space; empty string plots solid line

pointsize

Marker size

A positive number

marker

Marker style

One of "", +, x, *, esquare, fsquare, ecircle, fcircle, etrianup, ftrianup, etriandn, ftriandn, edmd, fdmd

These follow GnuPlot's standard syntax, and can be set by setting each property in the plot command. For example:

In [4]:
plot(t,sin.(2π*5*t),
    # axes properties
    title="A sine wave", xlabel="Time (s)", ylabel="Amplitude", grid="on", yrange="[-1.1:1.1]",
    # curve properties
    linewidth=3, color="blue", marker="ecircle", plotstyle="linespoints", linestyle="-.-")
Out[4]:
Gnuplot Produced by GNUPLOT 5.2 patchlevel 2 -1 -0.5 0 0.5 1 0 0.2 0.4 0.6 0.8 1 Amplitude Time (s) A sine wave gnuplot_plot_1

Note that, if the x coordinate is ommited, the indices of y will be used instead.

Other curves can be added to the same plot by using the plot!() command. Only curve properties can be used with this command; the axes properties remain unchanged.

In [5]:
plot!(t,cos.(2π*5*t),color="red",linewidth=2)
Out[5]:
Gnuplot Produced by GNUPLOT 5.2 patchlevel 2 -1 -0.5 0 0.5 1 0 0.2 0.4 0.6 0.8 1 Amplitude Time (s) A sine wave gnuplot_plot_1 gnuplot_plot_2

3D plots

Gaston can plot 3D surfaces using the surf command, which works in two different ways. The first is by giving it explicit x, y and z coordinates.

In [6]:
x=[0,1,2,3]
y=[0,1,2]
Z=[10 10 10; 10 5 10;10 1 10; 10 0 10]
surf(x,y,Z,title = "3D: Valley of the Gnu from gnuplot manual")
Out[6]:
Gnuplot Produced by GNUPLOT 5.2 patchlevel 2 0 0.5 1 1.5 2 2.5 3 0 0.5 1 1.5 2 0 2 4 6 8 10 3D: Valley of the Gnu from gnuplot manual gnuplot_plot_1

The second alternative is to pass x, y coordinates to a function.

Note that the surf command takes the same options as plot, with the addition of the zrange axes property.

In [7]:
x = y = -15:0.33:15
surf(x,y,(x,y)->sin.(sqrt.(x.*x+y.*y))./sqrt.(x.*x+y.*y),title="Sombrero",plotstyle="pm3d")
Out[7]:
Gnuplot Produced by GNUPLOT 5.2 patchlevel 2 -15 -10 -5 0 5 10 15 -15 -10 -5 0 5 10 15 -0.4 -0.2 0 0.2 0.4 0.6 0.8 1 Sombrero gnuplot_plot_1 -0.4 -0.2 0 0.2 0.4 0.6 0.8 1

The palette can be set with the palette setting. See gnuplot's documentation for details and valid values.

In [8]:
set(palette="gray")
surf(x,y,(x,y)->sin.(sqrt(x.*x+y.*y))./sqrt.(x.*x+y.*y),title="Sombrero",plotstyle="pm3d")
Out[8]:
Gnuplot Produced by GNUPLOT 5.2 patchlevel 2 -15 -10 -5 0 5 10 15 -15 -10 -5 0 5 10 15 -0.4 -0.2 0 0.2 0.4 0.6 0.8 1 Sombrero gnuplot_plot_1