Advanced usage
Here we will show a few advanced techniques for data visualization using Gnuplot.jl.
Named datasets
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);
+Advanced usage · Gnuplot.jl Advanced usage
Here we will show a few advanced techniques for data visualization using Gnuplot.jl.
Named datasets
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) 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
@@ -17,9 +17,9 @@ name = "\$MyDataSet1"
a = vars.a,
b = vars.b,
c = vars.c)
┌ Info: Best fit values:
-│ a = 1.51670007143536
-│ b = 0.276931181635526
-└ c = 0.684624514856412
Multiplot
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.
Recycling data from the previous example we can plot both data and best fit model (in plot 1) and residuals (in plot 2):
@gp "f(x) = a * sin(b + c*x)"
+│ a = 1.47346212156232
+│ b = 0.298898550323684
+└ c = 0.693722474958205
Multiplot
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.
Recycling data from the previous example we can plot both data and best fit model (in plot 1) and residuals (in plot 2):
@gp "f(x) = a * sin(b + c*x)"
@gp :- "a=$(vars.a)" "b=$(vars.b)" "c=$(vars.c)"
@gp :- name=>(x, y, err)
@gp :- "set multiplot layout 2,1"
@@ -82,7 +82,7 @@ fxy = [sinc2d(x,y) for x in x, y in y]
0
The output value is the exit status of the underlying gnuplot process.
You may also quit all active sessions at once with Gnuplot.quitall():
julia> Gnuplot.quitall()
Histograms
Gnuplot.jl provides facilities to compute and display histograms, e.g.:
x = randn(1000);
@gp hist(x)
The hist() function also accept keywords to set the range to consider (range= keyword) and either the bin size (bs=) or the total number of bins (nbins=) in the histogram. A finer control on the output is achieved by exploiting the fields of the returned (Gnuplot.Histogram1D) structure, e.g.:
x = randn(1000);
h = hist(x, range=3 .* [-1,1], bs=0.5)
-@gp h.bins h.counts "w histep t 'Data' lc rgb 'red'"
The hist() function compute also 2D histograms by passing two vectors (with the same lengths), e.g.:
x = randn(10_000)
+@gp h.bins h.counts "w histep t 'Data' lc rgb 'red'"
The hist() function compute also 2D histograms by passing two vectors (with the same lengths), e.g.:
x = randn(10_000)
y = randn(10_000)
h = hist(x, y)
@gp h
Again, a finer control can be achieved by specifying ranges, bin size or number of bins (along both dimensions) and by explicitly using the content of the returned Gnuplot.Histogram2D structure:
x = randn(10_000)
@@ -107,7 +107,31 @@ p(σ) = round(1 - exp(-(σ^2) / 2), sigdigits=3)
# Draw contour lines at 1, 2 and 3 σ
clines = contourlines(h, p.(1:3));
-@gp palette(:beach, smooth=true, rev=true) "set grid front" "set size ratio -1" h clines
Animations
The Multiplot capabilities can also be used to stack plots one above the other in order to create an animation, as in the following example:
x = y = -10:0.33:10
+@gp palette(:beach, smooth=true, rev=true) "set grid front" "set size ratio -1" h clines
Interpolation of 2D scattered data
The dgrid3d() function allows to interpolate 2D scattered data onto a 2D regular grid, e.g.:
x = (rand(200) .- 0.5) .* 3;
+y = (rand(200) .- 0.5) .* 3;
+z = exp.(-(x.^2 .+ y.^2));
+
+# Interpolate on a 20x30 regular grid with splines
+gx, gy, gz = dgrid3d(x, y, z, "20,30 splines")
+
+@gsp "set size ratio -1" "set xyplane at 0" xlab="X" ylab="Y" :-
+@gsp :- x y z "w p t 'Scattered data' lc pal"
+@gsp :- gx gy gz "w l t 'Interpolation on a grid' lc pal"
Warn The splines algorithm may be very slow on large datasets. An alternative option is to use a smoothing kernel, such as gauss.
The interpolated data in scarcely sampled regions are poorly constrained, i.e. they are actually extrapolated values. By using the extra=false keyword all extrapolated values are set to NaN:
x = randn(2000) .* 0.5;
+y = randn(2000) .* 0.5;
+rsq = x.^2 + y.^2;
+z = exp.(-rsq) .* sin.(y) .* cos.(2 * rsq);
+
+@gsp "set size ratio -1" palette(:balance, smooth=true) "set view map" "set pm3d" :-
+@gsp :- "set multiplot layout 1,3" xr=[-2,2] yr=[-2,2] :-
+@gsp :- 1 tit="Scattered data" x y z "w p notit lc pal"
+
+# Show extrapolated values
+gx, gy, gz = dgrid3d(x, y, z, "40,40 gauss 0.1,0.1")
+@gsp :- 2 tit="Interpolation on a grid\\n(extrapolated values are shown)" gx gy gz "w l notit lc pal"
+
+# Hide exrapolated values
+gx, gy, gz = dgrid3d(x, y, z, "40,40 gauss 0.1,0.1", extra=false)
+@gsp :- 3 tit="Interpolation on a grid\\n(extrapolated values are hidden)" gx gy gz "w l notit lc pal"
Animations
The Multiplot capabilities can also be used to stack plots one above the other in order to create an animation, as in the following example:
x = y = -10:0.33:10
fz(x,y) = sin.(sqrt.(x.^2 + y.^2))./sqrt.(x.^2+y.^2)
fxy = [fz(x,y) for x in x, y in y]
@gsp "set xyplane at 0" "unset colorbox" cbr=[-1,1] zr=[-1,1]
@@ -119,4 +143,4 @@ for direction in [-1,1]
end
end
@gsp
Here the frame variable is used as multiplot index. The animation can be saved in a GIF file with:
save(term="gif animate size 480,360 delay 5", output="assets/animation.gif")
Direct command execution
When gnuplot commands are passed to @gp or @gsp they are stored in a session for future use, or to be saved in Gnuplot scripts. If you simply wish to execute a command without storing it in the session, and possibly retrieve a value, use gpexec. E.g., to retrieve the value of a gnuplot variable:
julia> gpexec("print GPVAL_TERM")
-"unknown"
You may also provide a session ID as first argument (see Multiple sessions) to redirect the command to a specific session.
Alternatively you may start the The gnuplot REPL to type commands directly from the Julia prompt.
The gnuplot REPL
The Gnuplot.jl package comes with a built-in REPL mode to directly send commands to the underlying gnuplot process. Since the REPL is a global resource, the gnuplot mode is not enabled by default. You can start it with:
Gnuplot.repl_init(start_key='>')
The customizable start_key character is the key which triggers activation of the REPL mode. To quit the gnuplot REPL mode hit the backspace key.
Dry sessions
A "dry session" is a session with no underlying gnuplot process. To enable dry sessions type:
Gnuplot.options.dry = true;
before starting a session (see also Options). Note that the dry option is a global one, i.e. it affects all sessions started after setting the option.
Clearly, no plot can be generated in dry sessions. Still, they are useful to run Gnuplot.jl code without raising errors (no attempt will be made to communicate with the underlying process). Moreover, Gnuplot scripts can also be generated in a dry session, without the additional overhead of sending data to the gnuplot process.
If a gnuplot process can not be started the package will print a warning, and automatically enable dry sessions.
Settings
This document was generated with Documenter.jl on Tuesday 28 April 2020. Using Julia version 1.4.0.
You may also provide a session ID as first argument (see Multiple sessions) to redirect the command to a specific session.
Alternatively you may start the The gnuplot REPL to type commands directly from the Julia prompt.
The gnuplot REPL
The Gnuplot.jl package comes with a built-in REPL mode to directly send commands to the underlying gnuplot process. Since the REPL is a global resource, the gnuplot mode is not enabled by default. You can start it with:
Gnuplot.repl_init(start_key='>')The customizable start_key character is the key which triggers activation of the REPL mode. To quit the gnuplot REPL mode hit the backspace key.
Dry sessions
A "dry session" is a session with no underlying gnuplot process. To enable dry sessions type:
Gnuplot.options.dry = true;before starting a session (see also Options). Note that the dry option is a global one, i.e. it affects all sessions started after setting the option.
Clearly, no plot can be generated in dry sessions. Still, they are useful to run Gnuplot.jl code without raising errors (no attempt will be made to communicate with the underlying process). Moreover, Gnuplot scripts can also be generated in a dry session, without the additional overhead of sending data to the gnuplot process.
If a gnuplot process can not be started the package will print a warning, and automatically enable dry sessions.