Here we will show a few advanced techniques for data visualization using Gnuplot.jl. The new concepts introduced in the examples are as follows:
a name can be associated to a dataset, in order to use it multiple times in a plot while sending it only once to gnuplot. A dataset name must begin with a $;
gnuplot is able to generate multiplot, i.e. a single figure containing multiple plots. Each plot is identified by a numeric ID, starting from 1;
Gnuplot.jl is able to handle multiple sessions, i.e. multiple gnuplot processes running simultaneously. Each session is identified by a symbol. If the session ID is not specified the :default session is considered.
A named dataset can be used multiple times in a plot, avoiding sending to gnuplot the same data multiple times. A dataset name must always start with a $, and the dataset is defined as a Pair{String, Tuple}, e.g.:
"\$name" => (1:10,)
A named dataset can be used as an argument to both @gp and gsp, e.g.:
x = range(-2pi, stop=2pi, length=100);
+Advanced techniques · Gnuplot.jl
A dataset may have an associated name whose purpose is to use it multiple times for plotting, while sending it only once to gnuplot. A dataset name must begin with a $.
A named dataset is defined as a Pair{String, Tuple}, e.g.:
"\$name" => (1:10,)
and can be used as an argument to both @gp and gsp, e.g.:
x = range(-2pi, stop=2pi, length=100);
y = sin.(x)
name = "\$MyDataSet1"
@gp name=>(x, y) "plot $name w l lc rgb 'black'" "pl $name u 1:(-1.5*\$2) w l lc rgb 'red'"
Both curves use the same input data, but the red curve has the second column (\$2, corresponding to the y value) is multiplied by a factor -1.5.
A named dataset comes in hand also when using gnuplot to fit experimental data to a model, e.g.:
# Generate data and some noise to simulate measurements
@@ -16,9 +16,9 @@ name = "\$MyDataSet1"
a=Gnuplot.exec("print a"),
b=Gnuplot.exec("print b"),
c=Gnuplot.exec("print c"))
┌ Info: Best fit values:
-│ a = "1.49753503068311"
-│ b = "0.265280323129744"
-└ c = "0.695848802236574"
A named dataset is available until the session is reset, i.e. as long as :- is used as first argument to @gp.
Gnuplot.jl can draw multiple plots in the same figure by exploiting the multiplot command. Each plot is identified by a positive integer number, which can be used as argument to @gp to redirect commands to the appropriate plot.
Continuing previous example we can plot both data and best fit model (in plot 1) and residuals (in plot 2):
@gp :- "set multiplot layout 2,1"
+│ a = "1.53999342784748"
+│ b = "0.312000243313806"
+└ c = "0.71603533340826"
A named dataset is available until the session is reset, i.e. as long as :- is used as first argument to @gp.
Gnuplot.jl can draw multiple plots in the same figure by exploiting the multiplot command. Each plot is identified by a positive integer number, which can be used as argument to @gp to redirect commands to the appropriate plot.
Continuing previous example we can plot both data and best fit model (in plot 1) and residuals (in plot 2):
@gp :- "set multiplot layout 2,1"
@gp :- 1 "p $name w errorbars t 'Data'"
@gp :- "p $name u 1:(f(\$1)) w l t 'Best fit model'"
@gp :- 2 "p $name u 1:((f(\$1)-\$2) / \$3):(1) w errorbars t 'Resid. [{/Symbol s}]'"
@@ -35,4 +35,8 @@ c=Gnuplot.exec("print c"))
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 "..."";
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].
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 "..."";
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].
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
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.
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.
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.
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).
Run the test and test palette commands on a gnuplot terminal.
If no term is given it will use the default terminal. If linetypes and palette are given they are used as input to the linetypes and palette function repsetcively to load the associated color scheme.
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.
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.
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).
Run the test and test palette commands on a gnuplot terminal.
If no term is given it will use the default terminal. If linetypes and palette are given they are used as input to the linetypes and palette function repsetcively to load the associated color scheme.
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 the sid argument is not provided, the default session is considered.
This document was generated with Documenter.jl on Tuesday 31 March 2020. Using Julia version 1.3.1.
diff --git a/dev/assets/ex007a.png b/dev/assets/ex007a.png
index 12807b2..adde206 100644
Binary files a/dev/assets/ex007a.png and b/dev/assets/ex007a.png differ
diff --git a/dev/assets/ex007b.jpg b/dev/assets/ex007b.jpg
deleted file mode 100644
index d94afd4..0000000
Binary files a/dev/assets/ex007b.jpg and /dev/null differ
diff --git a/dev/assets/ex007b.png b/dev/assets/ex007b.png
new file mode 100644
index 0000000..b91fa0c
Binary files /dev/null and b/dev/assets/ex007b.png differ
diff --git a/dev/assets/ex007c.jpg b/dev/assets/ex007c.jpg
deleted file mode 100644
index 72641a6..0000000
Binary files a/dev/assets/ex007c.jpg and /dev/null differ
diff --git a/dev/assets/ex007c.png b/dev/assets/ex007c.png
new file mode 100644
index 0000000..fb3caba
Binary files /dev/null and b/dev/assets/ex007c.png differ
diff --git a/dev/assets/ex011.png b/dev/assets/ex011.png
index 639e132..badae7e 100644
Binary files a/dev/assets/ex011.png and b/dev/assets/ex011.png differ
diff --git a/dev/basic/index.html b/dev/basic/index.html
index 950e2c2..0e95f78 100644
--- a/dev/basic/index.html
+++ b/dev/basic/index.html
@@ -13,11 +13,33 @@
img[10,:] .= -5
@gp img "w image notit"
Note that the first index in the img matrix corresponds to the x coordinate when the image is displayed.
If the orientation is not the correct one you may adjust it with the gnuplot rotate= keyword (the following example requires the TestImages package to be installed):
using TestImages
img = testimage("lighthouse");
-@gp "set size square" "set autoscale fix" img "rotate=-90deg with rgbimage notit"
To display a gray image use with image in place of with rgbimage, e.g.:
3D plots follow the same rules as 2D ones, just replace the @gp macro with @gsp and add the required columns (according to the plotting style).
E.g., to plot a spiral increasing in size along the X direction:
x = 0:0.1:10pi
-@gsp cbr=[-1,1].*30 x sin.(x) .* x cos.(x) .* x x./20 "w p pt 7 ps var lc pal"
Note that the fourth array in the dataset, x./20, is used as by gnuplot as point size (ps var). Also note that all the keywords discussed above can also be used in 3D plots.
3D plots follow the same rules as 2D ones, just replace the @gp macro with @gsp and add the required columns (according to the plotting style).
E.g., to plot a spiral increasing in size along the X direction:
x = 0:0.1:10pi
+@gsp cbr=[-1,1].*30 x sin.(x) .* x cos.(x) .* x x./20 "w p pt 7 ps var lc pal"
Note that the fourth array in the dataset, x./20, is used as by gnuplot as point size (ps var). Also note that all the keywords discussed above can also be used in 3D plots.
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 Tuesday 31 March 2020. Using Julia version 1.3.1.
