API

@gp args...

The @gp macro, and its companion @gsp for 3D plots, allows to send data and commands to the gnuplot using an extremely concise syntax. The macros accepts any number of arguments, with the following meaning:

• one, or a group of consecutive, array(s) build up a dataset. The different arrays are accessible as columns 1, 2, etc. from the gnuplot process. The number of required input arrays depends on the chosen plot style (see gnuplot documentation);

• a string occurring before a dataset is interpreted as a gnuplot command (e.g. set grid);

• a string occurring immediately after a dataset is interpreted as a plot element for the dataset, by which you can specify using clause, with clause, line styles, etc.. All keywords may be abbreviated following gnuplot conventions. Moreover, "plot" and "splot" can be abbreviated to "p" and "s" respectively;

• the special symbol :-, whose meaning is to avoid starting a new plot (if given as first argument), or to avoid immediately running all commands to create the final plot (if given as last argument). Its purpose is to allow splitting one long statement into multiple (shorter) ones;

• any other symbol is interpreted as a session ID;

• an Int (>= 1) is interpreted as the plot destination in a multi-plot session (this specification applies to subsequent arguments, not previous ones);

• an input in the form "\$name"=>(array1, array2, etc...) is interpreted as a named dataset. Note that the dataset name must always start with a "$";

• an input in the form keyword=value is interpreted as a keyword/value pair. The accepted keywords and their corresponding gnuplot commands are as follows:

  • xrange=[low, high] => "set xrange [low:high];
  • yrange=[low, high] => "set yrange [low:high];
  • zrange=[low, high] => "set zrange [low:high];
  • cbrange=[low, high]=> "set cbrange[low:high];
  • key="..." => "set key ...";
  • title="..." => "set title "..."";
  • xlabel="..." => "set xlabel "..."";
  • ylabel="..." => "set ylabel "..."";
  • zlabel="..." => "set zlabel "..."";
  • cblabel="..." => "set cblabel "..."";
  • xlog=true => set logscale x;
  • ylog=true => set logscale y;
  • zlog=true => set logscale z.

All Keyword names can be abbreviated as long as the resulting name is unambiguous. E.g. you can use xr=[1,10] in place of xrange=[1,10].

@gsp args...

This macro accepts the same syntax as @gp, but produces a 3D plot instead of a 2D one.

boxxyerror(x, y; xmin=NaN, ymin=NaN, xmax=NaN, ymax=NaN, cartesian=false)

contourlines(x::Vector{Float64}, y::Vector{Float64}, h::Matrix{Float64}; cntrparam="level auto 10")

Compute paths of contour lines for 2D data, and return a vector of IsoContourLines object.

Arguments:

• x, y: Coordinates;
• h: the levels on which iso contour lines are to be calculated
• cntrparam: settings to compute contour line paths (see gnuplot documentation for cntrparam).

Example

x = randn(5000);
y = randn(5000);
h = hist(x, y, nbins1=20, nbins2=20);
clines = contourlines(h.bins1, h.bins2, h.counts, cntrparam="levels discrete 15, 30, 45");
@gp "set size ratio -1"
for i in 1:length(clines)
    @gp :- clines[i].data "w l t '$(clines[i].z)' dt $i"
end

dataset_names(sid::Symbol)
dataset_names()

Return a vector with all dataset names for the sid session. If sid is not provided the default session is considered.

gpexec(sid::Symbol, command::String)
gpexec(command::String)

Execute the gnuplot command command on the underlying gnuplot process of the sid session, and return the results as a Vector{String}. If a gnuplot error arises it is propagated as an ErrorException.

The the sid argument is not provided, the default session is considered.

Examples:

gpexec("print GPVAL_TERM")
gpexec("plot sin(x)")

hist(v::Vector{T}; range=extrema(v), bs=NaN, nbins=0, pad=true) where T <: Number

Calculates the histogram of the values in v and returns a Histogram1D structure.

Arguments

• v: a vector of values to compute the histogra;
• range: values of the left edge of the first bin and of the right edge of the last bin;
• bs: size of histogram bins;
• nbins: number of bins in the histogram;
• pad: if true add one dummy bins with zero counts before the first bin and after the last.

If bs is given nbins is ignored.

Example

v = randn(1000)
h = hist(v, bs=0.5)
@gp h  # preview
@gp h.bins h.counts "w histep notit"

hist(v1::Vector{T1 <: Number}, v2::Vector{T2 <: Number}; range1=[NaN,NaN], bs1=NaN, nbins1=0, range2=[NaN,NaN], bs2=NaN, nbins2=0)

Calculates the 2D histogram of the values in v1 and v2 and returns a Histogram2D structure.

Arguments

• v1: a vector of values along the first dimension;
• v2: a vector of values along the second dimension;
• range1: values of the left edge of the first bin and of the right edge of the last bin, along the first dimension;
• range1: values of the left edge of the first bin and of the right edge of the last bin, along the second dimension;
• bs1: size of histogram bins along the first dimension;
• bs2: size of histogram bins along the second dimension;
• nbins1: number of bins along the first dimension;
• nbins2: number of bins along the second dimension;

If bs1 (bs2) is given nbins1 (nbins2) is ignored.

Example

v1 = randn(1000)
v2 = randn(1000)
h = hist(v1, v2, bs1=0.5, bs2=0.5)
@gp h  # preview
@gp "set size ratio -1" "set auto fix" h.bins1 h.bins2 h.counts "w image notit"

linetypes(cmap::ColorScheme; rev=false)
linetypes(s::Symbol; rev=false)

Convert a ColorScheme object into a string containing the gnuplot commands to set up linetype colors.

If the argument is a Symbol it is interpreted as the name of one of the predefined schemes in ColorSchemes. If rev=true the line colors are reversed.

palette(cmap::ColorScheme; rev=false)
palette(s::Symbol; rev=false)

Convert a ColorScheme object into a string containing the gnuplot commands to set up the corresponding palette.

If the argument is a Symbol it is interpreted as the name of one of the predefined schemes in ColorSchemes. If rev=true the palette is reversed.

palette_names()

Return a vector with all available color schemes for the palette and linetypes function.

save(sid::Symbol; term="", output="")
save(sid::Symbol, script_filename::String, ;term="", output="")
save(; term="", output="")
save(script_filename::String ;term="", output="")

Export a (multi-)plot into the external file name provided in the output= keyword. The gnuplot terminal to use is provided through the term= keyword.

If the script_filename argument is provided a gnuplot script will be written in place of the output image. The latter can then be used in a pure gnuplot session (Julia is no longer needed) to generate exactly the same original plot.

If the sid argument is provided the operation applies to the corresponding session.

session_names()

Return a vector with all currently active sessions.

stats(sid::Symbol,name::String)
stats(name::String)
stats(sid::Symbol)
stats()

Print a statistical summary for the name dataset, belonging to sid session. If name is not provdied a summary is printed for each dataset in the session. If sid is not provided the default session is considered.

This function is actually a wrapper for the gnuplot command stats.

terminals()

Return a Vector{String} with the names of all the available gnuplot terminals.

terminal(sid::Symbol)
terminal()

Return a String with the current gnuplot terminal (and its options) of the process associated to session sid, or to the default session (if sid is not provided).

test_terminal(term=nothing; linetypes=nothing, palette=nothing)

Run the test and test palette commands on a gnuplot terminal.

If no term is given it will use the default terminal. If lt and pal are given they are used as input to the linetypes and palette function repsetcively to load the associated color scheme.

Examples

test_terminal()
test_terminal("wxt", lt=:rust, pal=:viridis)

Histogram1D

A 1D histogram data.

Fields

• bins::Vector{Float64}: bin center values;
• counts::Vector{Float64}: counts in the bins;
• binsize::Float64: size of each bin;

Histogram2D

A 2D histogram data.

Fields

• bins1::Vector{Float64}: bin center values along first dimension;
• bins2::Vector{Float64}: bin center values along second dimension;
• counts::Vector{Float64}: counts in the bins;
• binsize1::Float64: size of each bin along first dimension;
• binsize2::Float64: size of each bin along second dimension;

IsoContourLines

Coordinates of all contour lines of a given level.

Fields

• paths::Vector{Path2d}: vector of Path2d objects, one for each continuous path;
• data::Vector{String}: vector with string representation of all paths (ready to be sent to gnuplot);
• z::Float64: level of the contour lines.

Options

Structure containing the package global options, accessible through Gnuplot.options.

Fields

• dry::Bool: whether to use dry sessions, i.e. without an underlying Gnuplot process (default: false)
• cmd::String: command to start the Gnuplot process (default: "gnuplot")
• default::Symbol: default session name (default: :default)
• init::Vector{String}: commands to initialize the gnuplot session (e.g., to set default terminal)
• verbose::Bool: verbosity flag (default: false)
• preferred_format::Symbol: preferred format to send data to gnuplot. Value must be one of:
  • bin: fastest solution for large datasets, but uses temporary files;
  • text: may be slow for large datasets, but no temporary file is involved;
  • auto (default) automatically choose the best strategy.

Path2d

A path in 2D.

Fields

• x::Vector{Float64}
• y::Vector{Float64}

Gnuplot.gpversion()

Return the gnuplot application version.

Raise an error if version is < 5.0 (required to use data blocks).

Gnuplot.quit(sid::Symbol)

Quit the session identified by sid and the associated gnuplot process (if any).

Gnuplot.quitall()

Quit all the sessions and the associated gnuplot processes.

Gnuplot.version()

Return the Gnuplot.jl package version.