The @gp macro (and its companion @gsp, for splot operations) allows to exploit all of the Gnuplot package functionalities using an extremely efficient and concise syntax. Both macros accept the same syntax, as described below.
The macros accepts any number of arguments, with the following meaning:
a symbol: the name of the session to use;
a string: a command (e.g. "set key left") or plot specification (e.g. "with lines");
a string starting with a $ sign: a data set name;
an Int > 0: the plot destination in a multiplot session;
a keyword/value pair: a keyword value (see below);
any other type: a dataset to be passed to Gnuplot. Each dataset must be terminated by either:
a string starting with a $ sign (i.e. the data set name);
or a string with the plot specifications (e.g. "with lines");
the :- symbol, used as first argument, avoids resetting the Gnuplot session. Used as last argument avoids immediate execution of the plot/splot command. This symbol can be used to split a single call into multiple ones.
All entries are optional, and there is no mandatory order. The plot specification can either be:
a complete plot/splot command (e.g., "plot sin(x)", both "plot" and "splot" can be abbreviated to "p" and "s" respectively);
or a partial specification starting with the "with" clause (if it follows a data set).
The list of accepted keyword is as follows:
title::String: plot title;
xlabel::String: X axis label;
ylabel::String: Y axis label;
zlabel::String: Z axis label;
xlog::Bool: logarithmic scale for X axis;
ylog::Bool: logarithmic scale for Y axis;
zlog::Bool: logarithmic scale for Z axis;
xrange::NTuple{2, Number}: X axis range;
yrange::NTuple{2, Number}: Y axis range;
zrange::NTuple{2, Number}: Z axis range;
cbrange::NTuple{2, Number}: Color box axis range;
The symbol for the above-mentioned keywords may also be used in a shortened form, as long as there is no ambiguity with other keywords. E.g. you can use: xr=(1,10) in place of xrange=(1,10).
Examples:
Simple examples with no data:
@gp "plot sin(x)"
-@gp "plot sin(x)" "pl cos(x)"
-@gp "plo sin(x)" "s cos(x)"
-
-# Split a `@gp` call in two
-@gp "plot sin(x)" :-
-@gp :- "plot cos(x)"
-
-# Insert a 3 second pause between one plot and the next
-@gp "plot sin(x)" 2 xr=(-2pi,2pi) "pause 3" "plot cos(4*x)"
Simple examples with data:
@gp "set key left" tit="My title" xr=(1,12) 1:10 "with lines tit 'Data'"
-
-x = collect(1.:10)
-@gp x
-@gp x x
-@gp x -x
-@gp x x.^2
-@gp x x.^2 "w l"
-
-lw = 3
-@gp x x.^2 "w l lw $lw"
x = range(-2pi, stop=2pi, length=100);
-y = 1.5 * sin.(0.3 .+ 0.7x) ;
-noise = randn(length(x))./2;
-e = 0.5 * fill(1, size(x));
-
-name = "\$MyDataSet1"
-@gp x y name "plot $name w l" "pl $name u 1:(2*\$2) w l"
-
-@gsp randn(Float64, 30, 50)
-@gp randn(Float64, 30, 50) "w image"
-@gsp x y y
-
-@gp("set key horizontal", "set grid",
- xrange=(-7,7), ylabel="Y label",
- x, y, "w l t 'Real model' dt 2 lw 2 lc rgb 'red'",
- x, y+noise, e, "w errorbars t 'Data'")
-
-@gp "f(x) = a * sin(b + c*x); a = 1; b = 1; c = 1;" :-
-@gp :- x y+noise e name :-
-@gp :- "fit f(x) $name u 1:2:3 via a, b, c;" :-
-@gp :- "set multiplot layout 2,1" :-
-@gp :- "plot $name w points" ylab="Data and model" :-
-@gp :- "plot $name u 1:(f(\$1)) w lines" :-
-@gp :- 2 xlab="X label" ylab="Residuals" :-
-@gp :- "plot $name u 1:((f(\$1)-\$2) / \$3):(1) w errorbars notit"
-
-# Retrieve values for a, b and c
-a = Meta.parse(Gnuplot.exec("print a"))
-b = Meta.parse(Gnuplot.exec("print b"))
-c = Meta.parse(Gnuplot.exec("print c"))
-
-# Save to a PDF file
-save(term="pdf", output="gnuplot.pdf")
Display an image
using TestImages
-img = testimage("lena");
-@gp img "w image"
-@gp "set size square" img "w rgbimage" # Color image with correct proportions
-@gp "set size square" img "u 2:(-\$1):3:4:5 with rgbimage" # Correct orientation
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 (> 0) 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 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 "..."";
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];
an input in the form "name"=>(array1, array2, etc...) is interpreted as a named dataset.
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.
The following functions are not exported by the Gnuplot.jl package since they are typically not used in every day work, or aimed to debugging purposes. Still, they can be useful in some case, hence they are documented here.
In order to call these functions you should add the Gnuplot. prefix to the function name.
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 sid argument is (optional): if not given, :default is used.
The main purpose of the Gnuplot.jl package is to send data and commands to the underlying gnuplot process, in order to generate plots. Unlike other packages, however, the actual commands to plot, or the plot attributes, are not specified through function calls. This is what makes Gnuplot.jleasy to learn and use: there are no functions or keywords names to memorize[1].
The most important symbols exported by the package are the @gp (for 2D plots) and @gsp (for 3D plots) macros, both accepting any number of arguments, and whose meaning is interpreted as follows:
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.;
the special symbol :-, whose meaning is to avoid creating 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.
The above lists all the required concepts to follow the examples presented below. The @gp and @gsp macros also accepts further arguments, but their use will be discussed in Advanced techniques.
Here we will show a few examples to generate 2D plots. The examples are intentionally very simple to highlight the behavior of Gnuplot.jl. See Examples for more complex ones.
The main purpose of the Gnuplot.jl package is to send data and commands to the underlying gnuplot process, in order to generate plots. Unlike other packages, however, the actual commands to plot, or the plot attributes, are not specified through function calls. This is what makes Gnuplot.jleasy to learn and use: there are no functions or keywords names to memorize[1].
The most important symbols exported by the package are the @gp (for 2D plots) and @gsp (for 3D plots) macros, both accepting any number of arguments, and whose meaning is interpreted as follows:
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.;
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.
The above lists all the required concepts to follow the examples presented below. The @gp and @gsp macros also accepts further arguments, but their use will be discussed in Advanced techniques.
Here we will show a few examples to generate 2D plots. The examples are intentionally very simple to highlight the behavior of Gnuplot.jl. See Examples for more complex ones.
The save() function allows to export all plots (as well as multiplots, see Multiplot) to a file using one of the many available gnuplot terminals. To check which terminals are available in your platform type set term in your gnuplot terminal.
Besides exporting plots in a file Gnuplot.jl can also save a script, i.e. a file containing the minimum set of data and commands required to generate a plot within gnuplot.
To generate a script for one of the example above use:
save("script.gp")
after the plot has been displayed. The script can then be used within a gnuplot session as follows:
gunplot> load 'script.gp'
to generate a plot identical to the original one, without using the Julia language.
The purpose of gnuplot scripts is to allow sharing all data, alongside a plot, in order to foster collaboration among scientists and replicability of results. Moreover, a script can be used at any time to change the details of a plot, without the need to re-run the Julia code used to generate it the first time.
Finally, the scripts are the only possible output when Dry sessions are used (i.e. when gnuplot is not available in the user platform.
1a previous knowledge of gnuplot usage is, nevertheless, required.
Settings
This document was generated with Documenter.jl on Thursday 26 March 2020. Using Julia version 1.3.1.
The save() function allows to export all plots (as well as multiplots, see Multiplot) to a file using one of the many available gnuplot terminals. To check which terminals are available in your platform type set term in your gnuplot terminal.
Besides exporting plots in a file Gnuplot.jl can also save a script, i.e. a file containing the minimum set of data and commands required to generate a plot within gnuplot.
To generate a script for one of the example above use:
save("script.gp")
after the plot has been displayed. The script can then be used within a gnuplot session as follows:
gunplot> load 'script.gp'
to generate a plot identical to the original one, without using the Julia language.
The purpose of gnuplot scripts is to allow sharing all data, alongside a plot, in order to foster collaboration among scientists and replicability of results. Moreover, a script can be used at any time to change the details of a plot, without the need to re-run the Julia code used to generate it the first time.
Finally, the scripts are the only possible output when Dry sessions are used (i.e. when gnuplot is not available in the user platform.
1a previous knowledge of gnuplot usage is, nevertheless, required.
Settings
This document was generated with Documenter.jl on Thursday 26 March 2020. Using Julia version 1.3.1.
The Gnuplot.jl package allows easy and fast use of gnuplot as a data visualization tool in Julia. Have a look at Basic usage and Examples for a quick overview. The package main features are:
fast time-to-first-plot (~1 sec);
extremely concise yet meaningful syntax, makes it ideal for interactive data exploration;
no need to learn new API functions or keywords: only two macros (@gp for 2D plots, @gsp for 3D plots) and a basic knowledge of gnuplot are enough to generate the most complex plots;
transparent interface between Julia and gnuplot to exploit all functionalities of the latter, both present and future ones;
fast data transmission through system pipes (no temporary files involved);
availability of all the palettes from ColorSchemes;
support for multiple plots in one window, multiple plotting windows, as well as ASCII and Sixel plots (to plot directly in a terminal);
support for histograms (both 1D and 2D);
enhanced support for contour plots;
export to a huge number of formats such as pdf, png, $\LaTeX$, svg, etc. (actually all those supported by gnuplot);
save sessions into gnuplot scripts enables easy plot reproducibility and modifications.
A powerful plotting framework is among the most important tool in the toolbox of any modern scientist and engineer. As such, it is hard to find a single package to fit all needs, and many solutions are indeed available in the Julia ecosystem.
Gnuplot.jl package fills the niche of users who needs:
publication-quality plots, by exploiting the capabilities of a widely used tool such as gnuplot, and its many output formats available;
a well-documented framework, by taking advantage of all the gnuplot documentation, tutorials and examples available on the web;
a fast response, by relying on an external program (rather than on a large Julia code base);
an interactive data exploration framework, by exposing a carefully designed, extremely concise and easy to remember syntax (at least for users with minimal gnuplot knowledge);
a procedure to foster plot reproducibility by sharing just the data and commands in the form of gnuplot scripts, rather than the original Julia code.
Unlike other packages Gnuplot.jl is not a pure Julia solution as it depends on an external package to actually generate plots. However, if gnuplot is not available on a given platform, the package could still be used in "dry" mode, and no error for a missing dependency will be raised (see Dry sessions).
The Gnuplot.jl package development follows a minimalistic approach: it is essentially a thin layer to send data and string commands to gnuplot. This way all underlying capabilities, both present and future ones, are automatically exposed to Julia user, with no need to implement dedicated wrappers.
The functionalities 1, 2 and 3 listed above are similar to those provided by the Gaston package. Gnuplot.jl also provides features 4 and 5, as well as the minimalistic approach.
Any modern plotting package is able to produce a simple scatter plot, with custom symbols, line styles, colors and axis labels. Indeed, this is exactly the example that is reported in every package documentation (also here: see 2D plots). Still, producing complex and publication-quality plots is not an easy task. As a consequence is also not easy to determine whether a package can cope with the most difficult cases (unless you actually try it out) and a reasonable choice is typically to rely on the size of the user base, the availability of documentation / tutorials, and the possibility to preview complex examples.
Gnuplot.jl aims to be ready for even the most challenging plots by relying on the widely and long lasting used gnuplot application, and by allowing each native feature (both present and future ones) to be immediately available in the Julia language. Moreover, Gnuplot.jl provides a unique syntax specifically aimed to increase productivity while performing interactive data exploration.
Last but not least, have a look at the Gnuplot.jlExamples page.
The Gnuplot.jl package allows easy and fast use of gnuplot as a data visualization tool in Julia. Have a look at Basic usage and Examples for a quick overview. The package main features are:
fast time-to-first-plot (~1 sec);
extremely concise yet meaningful syntax, makes it ideal for interactive data exploration;
no need to learn new API functions or keywords: only two macros (@gp for 2D plots, @gsp for 3D plots) and a basic knowledge of gnuplot are enough to generate the most complex plots;
transparent interface between Julia and gnuplot to exploit all functionalities of the latter, both present and future ones;
fast data transmission through system pipes (no temporary files involved);
availability of all the palettes from ColorSchemes;
support for multiple plots in one window, multiple plotting windows, as well as ASCII and Sixel plots (to plot directly in a terminal);
support for histograms (both 1D and 2D);
enhanced support for contour plots;
export to a huge number of formats such as pdf, png, $\LaTeX$, svg, etc. (actually all those supported by gnuplot);
save sessions into gnuplot scripts enables easy plot reproducibility and modifications.
A powerful plotting framework is among the most important tool in the toolbox of any modern scientist and engineer. As such, it is hard to find a single package to fit all needs, and many solutions are indeed available in the Julia ecosystem.
Gnuplot.jl package fills the niche of users who needs:
publication-quality plots, by exploiting the capabilities of a widely used tool such as gnuplot, and its many output formats available;
a well-documented framework, by taking advantage of all the gnuplot documentation, tutorials and examples available on the web;
a fast response, by relying on an external program (rather than on a large Julia code base);
an interactive data exploration framework, by exposing a carefully designed, extremely concise and easy to remember syntax (at least for users with minimal gnuplot knowledge);
a procedure to foster plot reproducibility by sharing just the data and commands in the form of gnuplot scripts, rather than the original Julia code.
Unlike other packages Gnuplot.jl is not a pure Julia solution as it depends on an external package to actually generate plots. However, if gnuplot is not available on a given platform, the package could still be used in "dry" mode, and no error for a missing dependency will be raised (see Dry sessions).
The Gnuplot.jl package development follows a minimalistic approach: it is essentially a thin layer to send data and string commands to gnuplot. This way all underlying capabilities, both present and future ones, are automatically exposed to Julia user, with no need to implement dedicated wrappers.
The functionalities 1, 2 and 3 listed above are similar to those provided by the Gaston package. Gnuplot.jl also provides features 4 and 5, as well as the minimalistic approach.
Any modern plotting package is able to produce a simple scatter plot, with custom symbols, line styles, colors and axis labels. Indeed, this is exactly the example that is reported in every package documentation (also here: see 2D plots). Still, producing complex and publication-quality plots is not an easy task. As a consequence is also not easy to determine whether a package can cope with the most difficult cases (unless you actually try it out) and a reasonable choice is typically to rely on the size of the user base, the availability of documentation / tutorials, and the possibility to preview complex examples.
Gnuplot.jl aims to be ready for even the most challenging plots by relying on the widely and long lasting used gnuplot application, and by allowing each native feature (both present and future ones) to be immediately available in the Julia language. Moreover, Gnuplot.jl provides a unique syntax specifically aimed to increase productivity while performing interactive data exploration.
Last but not least, have a look at the Gnuplot.jlExamples page.
In order to use the Gnuplot.jl package you'll need gnuplot (ver. >= 4.7) installed on your system, and its executable available in your path.
If gnuplot is not available in your platform you can still use Gnuplot.jl in "dry" mode (see Dry sessions). In this case a plot can not be generated, but you may still generate Gnuplot scripts.
