API Reference

Types and constructors

Figure

Figure

Type that stores a figure. It has the following fields:

• handle: the figure’s unique identifier (it may be of any type).
• gp_proc: the gnuplot process associated with the figure (type Base.Process).
• axes: a vector of Gaston.Axis.
• multiplot: a string with arguments to set multiplot.
• autolayout: true if Gaston should handle the figure’s layout (Bool).

Figure(h = nothing, autolayout = true, multiplot = "")::Figure

Return an empty a figure with given handle. If h === nothing, automatically assign the next available numerical handle. A new gnuplot process is started and associated with the new figure, which becomes the active figure.

If the handle provided already exists, an error is thrown.

Examples

fig = Figure()   # new figure with next available numerical handle
fig = Figure(5)  # new figure with handle 5 (if it was available)
fig = Figure(multiplot = "'title 'test'") # new figure with multiplot settings

(f::Figure)(index)::Gaston.Axis

Return the axis stored at the specified index. If the axis does not exist, an empty axis is created.

Plot commands

plot

plot([f::Figure,] [indexed figure,], [settings...,] data..., [plotline...,] [kwargs...])::Figure

Plot the provided data, returning a figure.

Arguments (in order from left to right):

• f::Figure (optional). If a figure f is given as argument, the figure is reset (all previous axes are removed), and the new plot is created in the first axis of f.
• An indexed figure (e.g. f[3]) (optional). The axis at the given index is cleared (or created if it does not exist), and the plot is added to it.
• Axis settings (optional, default ""). See documentation for details on how to specify these settings.
• The data to be plotted. Data may be provided as vectors, ranges, matrices, functions, etcetera (see documentation).
• A plotline (optional, default "") specifiying the plot formatting. See documentation for details on how to specify these settings.

The figure to use for plotting may also be specified using the keyword argument handle. Other keyword arguments are passed to convert_args, documented under Recipes.

Examples

plot(1:10) # A simple plot
plot("set title 'test'}, 1:10)  # Configure the axes
plot("set title 'test'}, 1:10, "w p")  # Configure the axes and plotline
plot(sin)  # plot the sine function from -10 to 10
plot(0:0.01:1, sin) # plot the sine function at the given time instants

See also plot! and splot.

plot(f1::Figure, f2::Figure,... ; multiplot = "", autolayout = false, kwargs...)::Figure

Return a new figure whose axes come from the figures provided in the arguments.

plot!

plot!(...)::Figure

Similar to plot, but adds a new curve to an axis. If the axis does not exist, it is created. However, plot! does not support specification of the axis settings.

Examples

plot(1:10)        # plot a curve
plot!((1:10.^2))  # add a second curve
f = plot(sin)     # store new plot in f
plot!(f, cos)     # add second curve to plot

See documentation to plot for more details.

splot

splot(...)::Figure

Similar to plot, but creates a 3D plot.

Example

splot(-1:0.1:1, -1:0.1:1, (x,y)->sin(x)*cos(y)) # Plot an equation in the specified range

See documentation to plot for more details.

splot!

splot!(...) -> Figure

Similar to splot, but adds a new surface to an existing plot.

See documentation to plot! for more details.

@plot

@plot args...

@plot provides an alternative syntax for plotting. The arguments are interpreted similarly to plot: first, a figure or axis may be specified; then, data is provided, and finally a plotline may be given. This macro allows specifying gnuplot settings as setting = value, which is converted to set setting value before passing it to gnuplot. These key, value pairs must be surrounded by curly brackets.

Examples

# Plot a sine wave with title `example` and with a grid, with a red line
@plot {title = "'example'", grid = true} sin {lc = 'red'}

In this example, grid = true is converted to set grid. To disable a setting, use (for example) grid = false (converted to unset grid).

@plot!

@plot! args...

Alternative Convenient syntax for plot!. See the documentation for @plot.

@splot

@splot args...

Alternative Convenient syntax for splot. See the documentation for @plot.

@splot!

@splot! args...

Alternative Convenient syntax for splot!. See the documentation for @plot.

Plotting with built-in themes

These functions call plot behind the scenes, with settings and plotline taken from a built-in theme.

scatter

scatter(args...; kwargs...)::Figure

Generate a scatter plot with built-in plotline theme scatter.

See the plot documentation for more information on the arguments.

scatter!

scatter!(args...; kwargs...)::Figure

Insert a scatter plot. See the scatter documentation for more details.

stem

stem(args...; onlyimpulses::Bool = false, color = "'blue'", kwargs...)::Figure

Generate a stem plot with built-in plotline themes impulses and stem.

This function takes the following keyword arguments:

• onlyimpulses: if true, plot using only impulses and omit the dots.
• color: specify line color to use. If not specified, the impulses and the dots may be plotted with different colors.

See the plot documentation for more information on the arguments.

stem!

stem!(args... ; onlyimpulses = false, color = "'blue'", kwargs...)::Figure

Insert a stem plot. See the stem documentation for more details.

bar

bar(args...; kwargs...)::Figure

Generate a bar plot with built-in settings theme boxplot and plotline theme box. See the plot documentation for more information on the arguments.

bar!

bar!(args...; kwargs...)::Figure

Insert a bar plot. See the bar documentation for more details.

barerror

barerror(args...; kwargs...)::Figure

Generate a barerror plot with built-in settings theme boxplot and plotline theme boxerror. See the plot documentation for more information on the arguments.

barerror!

barerror!(args...; kwargs...)::Figure

Insert a barerror plot. See the barerror documentation for more details.

histogram

histogram(args...,[bins = 10,] [mode = :pdf,] [edges = nothing,] [horizontal = false]; kwargs...)::Figure

Plot a histogram of the provided data, using StatsBase.fit. This function takes the following keyword arguments:

• bins specifies the number of bins (default 10)
• mode specifies how the histogram area is normalized (see StatsBase.fit)

imagesc

imagesc(args...; kwargs...)::Figure

Plot an array as an image. If the array is a matrix, a grayscale image is assumed. If the given array z is three-dimensional, an rgbimage is assumed, with z[1,:,:] the red channel, z[2,:,:] the blue channel, and z[3,:,:] the blue channel.

See the documentation to plot for more details.

surf

surf(args...; kwargs...)::Figure

Plot the provided data as a surface, using the settings theme hidden3d and the plotline theme pm3d.

See the plot documentation for more information on the arguments.

surf!

surf!(args...; kwargs...)::Figure

Insert a surface plot. See the surf documentation for more details.

scatter3

scatter3(args...; kwargs...)::Figure

Generate a scatter plot of the provided data, using the settings theme scatter3 and the plotline theme scatter.

See the plot documentation for more information on the arguments.

scatter3

scatter3!(args...; kwargs...)::Figure

Insert a scatter plot. See the scatter3 documentation for more details.

wireframe

wireframe(args...; kwargs...)::Figure

Plot the provided data using a wireframe, using the settings theme hidden3d.

See the plot documentation for more information on the arguments.

wireframe!

wireframe!(args...; kwargs...)::Figure

Insert a wireframe plot. See the wireframe documentation for more details.

wiresurf

wiresurf(args...; kwargs...)::Figure

Plot the provided data as a surface with a superimposed wireframe, using the settings theme wiresurf.

See the plot documentation for more information on the arguments.

wiresurf!

wiresurf!(args...; kwargs...)::Figure

Insert a wiresurf plot. See the wiresurf documentation for more details.

surfcontour

surfcontour(args...; [labels::Bool = true,] kwargs...)::Figure

Plot the provided data as a surface with contour lines at the base, using the settings theme contourproj and the plotline theme labels.

If the keyword argument labels is true, then numerical labels are added to the contour lines.

See the plot documentation for more information on the arguments.

contour

contour(args...; [labels::Bool = true,] kwargs...)::Figure

Plot the provided data using contour lines, with settings themes countour and labels.

If the keyword argument labels is true, then the contour lines are labeled. See the documentation to plot for more details.

heatmap

heatmap(args...; kwargs...)

Plot the data provided as a heatmap, using the settings theme heatmap and the plotline theme pm3d.

See the documentation to plot for more details.

Recipes

Gaston.convert_args

convert_args(args...)

Convert values of specific types to data that gnuplot can plot.

Users should add methods to this function for their own types. The returned value must be one of the following types:

• A Gaston.PlotRecipe, which describes a curve (i.e. it contains coordinates and a plotline).
• A Gaston.AxisRecipe, which contains multiple PlotRecipes and axis settings.
• A Gaston.FigureRecipe, which contains multiple AxisRecipes and multiplot settings.

See the Gaston documentation for full details and examples.

To add a recipe for 3-D plotting, use convert_args3.

Gaston.convert_args3

convert_args3(args...)

Convert values of specific types to data that gnuplot can plot using splot.

See documentation for convert_args for more details.

Figure management

figure

figure(handle = <active figure handle> ; index = nothing)::Figure

Return specified figure (by handle or index) and make it the active figure. If no figures exist, then a new figure is returned.

If no arguments are given, the current active figure is returned.

closefigure

closefigure(h = nothing)::Nothing

Close figure with handle h. If no arguments are given, the active figure is closed. The most recent remaining figure (if any) is made active.

The associated gnuplot process is also terminated.

Examples

plot(sin, handle = :first);
plot(cos, handle = :second);
plot(tan, handle = :third);
closefigure()        # close figure with handle `:third`
closefigure(:first)  # close figure with handle `:first`
closefigure()        # close figure with handle `:second`

closefigure(fig::Figure)::Nothing

Closes the specified figure. The associated gnuplot process is also terminated.

Example

p = plot(1:10);
closefigure(p)

closeall

closeall()::Nothing

Close all existing figures.

Utility functions and macros

@Q_str

@Q_str

Inserts single quotation marks around a string.

When passing options to gnuplot, some arguments should be quoted and some should not. For example:

• set title Example # gnuplot errors
• set title 'Example' # the title must be quoted
• set pointtype 7 # the point type is not quoted

Gaston allows setting options using keyword arguments:

@plot {title = "Example"} x y  # converted to "set title Example"

Here, the keyword argument should be {title = "'Example'"}, which is correctly converted to set title 'Example'. To avoid having to type the single quotes, this macro allows us to write:

@plot {title = Q"Example"} x y  # converted to "set title 'Example'"

@gpkw

@gpkw

Convert a variable number of keyword arguments to a vector of pairs of strings.

Example

julia> @gpkw {title = Q"Example", grid = true}
2-element Vector{Pair}:
 "title" => "'Example'"
  "grid" => true

push!

push!(f1::Figure, an::FigureAxis)::Figure

Insert the axis in an into f.

Example

``` julia f1 = plot(sin) f2 = Figure() plot(f2, cos) plot(f2[2], tan) push!(f1, f2[2]) # insert the plot of tan into f1

Saving plots

save

save(f::Figure = figure(); filename = nothing, term = "pngcairo font ',7'")::Nothing

Save figure f using the specified terminal term and filename.

If filename is not provided, the filename used is "figure-handle.ext, where handle = f.handle and ext is given by the first three characters of the current terminal.

save(handle; filename = nothing, term = "pngcairo font ',7'")::Nothing

Save the figure with the given handle.

Animations

animate

animate(f::Figure, term = config.altterm)

Render an animated plot in notebooks such as Pluto and Jupyter.

This function is meant to be used to render an animation within a notebook environment. Normally, all plots are rendered in a terminal such as png. However, rendering an animation requires switching to gif, webp or other terminal that supports animations. Changing the global terminal configuration wil cause all other plots in the notebook to be re-rendered with the wrong terminal. This function allows changing the terminal on a plot-by-plot basis, without changing the global terminal configuration.

Non-exported functions and types

The following may be useful when extending or developing Gaston. These functions are not part of the official API and may be modified or removed in future versions.

Gaston.terminals

Gaston.terminals()

Return a list of available gnuplot terminals

Gaston.listfigures

Gaston.listfigures()

Display a list of all existing figures.

Gaston.gp_start

Gaston.gp_start()::Base.Process

Returns a new gnuplot process.

Gaston.gp_quit

Gaston.gp_quit(process::Base.Process)

End gnuplot process process. Returns the exit code.”

Gaston.gp_quit(f::Figure)

End the gnuplot process associated with f. Returns the process exit code.

Gaston.gp_send

gp_send(process::Base.Process, message::String)

Send string message to process and handle its response.

gp_send(f::Figure, message)

Send string message to the gnuplot process associated with f and handle its response.

Gaston.gp_exec

gp_exec(message::AbstractString)

Run an arbitrary gnuplot command and return gnuplot’s stdout.

Gaston.Plot

Gaston.Plot(datafile::String, plotline::String)

Type that stores the data needed to plot a curve.

Gaston.Plot(args..., plotline = "")

Construct a new Plot. The curve data (for instance, x and y coordinates) are provided first. The curve plotline is the last argument.

Gaston.Axis

Axis(settings::String           = "",
     plots::Vector{Gaston.Plot} = Gaston.Plot[],
     is3d::Bool                 = false)

Type that stores the data required to create a 2-D or 3-D axis.

The constructor takes the following arguments:

• settings: stores the axis settings.
• plots: a vector of Plot, one per curve.
• is3d: determines if axis is generated with plot or splot.

Gaston.cs2dec

cs2dec(cs::ColorScheme)

Convert a colorsheme to a vector of integers, where each number corresponds to each color in cs, expressed in base 10. Meant to be used with lc rgb variable.

This function accepts color schemes made up of RGB or RGBA values.

Gaston.set!

set!(a::Gaston.Axis, s)
set!(f::Gaston.FigureAxis, s)

Set the settings of the axis or indexed figure. s can be a string or a vector of pairs.

Gaston.meshgrid

meshgrid(x, y, z)

Return a z-coordinate matrix from x, y coordinates and a function f, such that z[row,col] = f(x[row], y[col])