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
@@ -16,9 +16,9 @@ name = "\$MyDataSet1"
a = gpexec("print a"),
b = gpexec("print b"),
c = gpexec("print c"))
┌ Info: Best fit values:
-│ a = "1.40227450305279"
-│ b = "0.296215599996585"
-└ c = "0.700772054919827"
A named dataset is available until the session is reset, i.e. as long as :- is used as first argument to @gp.
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.
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.49027843564636"
+│ b = "0.291241150034077"
+└ c = "0.712856583575748"
A named dataset is available until the session is reset, i.e. as long as :- is used as first argument to @gp.
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.
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}]'"
@@ -63,7 +63,7 @@ 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, use gpexec. E.g. if you wish to temporarily change the current terminal:
julia> gpexec("set term wxt");
The gnuplot process replies are returned as a string, e.g.:
julia> gpexec("print GPVAL_TERM")
-"wxt"
You may also provide a session ID as first argument (see Multiple sessions, to redirect the command to a specific session.
Dry sessions
A "dry session" is a session with no underlying gnuplot process. To enable dry sessions type:
julia> 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.
Options
Thepackage options are stored in a global structure available in Julia as Gnuplot.option (the type of the structure is Gnuplot.Options). The most important settings are as follows:
dry::Bool: if true all new sessions will be started Dry sessions. Default is false, but if the package is not able to start a gnuplot it will automatically switch to false;
init::Vector{String}: This vector can be used to push! initialization commands to be executed when a new session is started. Default is an empty vector. It can be used to, e.g., set a custom terminal for all new sessions:
julia> push!(Gnuplot.options.init, "set term sixelgd");
Note that this is a global option, i.e. it will affect all new sessions. Also note that the commands in Gnuplot.options.init are not saved in Gnuplot scripts;
verbose::Bool: a flag to set verbosity of the package. In particular if it is true all communication with the underlying process will be printed on stdout. E.g.:
+"wxt"
You may also provide a session ID as first argument (see Multiple sessions) to redirect the command to a specific session.
Dry sessions
A "dry session" is a session with no underlying gnuplot process. To enable dry sessions type:
julia> 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.
Options
Thepackage options are stored in a global structure available in Julia as Gnuplot.option (the type of the structure is Gnuplot.Options). The most important settings are as follows:
dry::Bool: if true all new sessions will be started Dry sessions. Default is false, but if the package is not able to start a gnuplot it will automatically switch to false;
init::Vector{String}: This vector can be used to push! initialization commands to be executed when a new session is started. Default is an empty vector. It can be used to, e.g., set a custom terminal for all new sessions:
julia> push!(Gnuplot.options.init, "set term sixelgd");
Note that this is a global option, i.e. it will affect all new sessions. Also note that the commands in Gnuplot.options.init are not saved in Gnuplot scripts;
verbose::Bool: a flag to set verbosity of the package. In particular if it is true all communication with the underlying process will be printed on stdout. E.g.:
julia> Gnuplot.options.verbose = true;
julia> x = 1.:10;
@@ -92,4 +92,4 @@ GNUPLOT (default) set output 'output.png'
GNUPLOT (default) plot \
$data1 w l t 'Parabola'
GNUPLOT (default) set output
-GNUPLOT (default) set term wxt 0 enhanced
Each line reports the package name (GNUPLOT), the session name (default), the command or string being sent to gnuplot process, and the returned response (line starting with ->). Default value is false;
cmd::String: command to start the gnuplot process, default value is "gnuplot". If you need to specify a custom path to the gnuplot executable you may change this value;
default::Symbol: default session name, i.e. the session that will be used when no session name is provided;
preferred_format::Symbol: preferred format to send data to gnuplot. Value must be one of:
bin: provides best performances 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.
Settings
This document was generated with Documenter.jl on Wednesday 1 April 2020. Using Julia version 1.3.1.
Each line reports the package name (GNUPLOT), the session name (default), the command or string being sent to gnuplot process, and the returned response (line starting with ->). Default value is false;
cmd::String: command to start the gnuplot process, default value is"gnuplot". If you need to specify a custom path to the gnuplot executable you may change this value;default::Symbol: default session name, i.e. the session that will be used when no session name is provided;preferred_format::Symbol: preferred format to send data to gnuplot. Value must be one of:bin: provides best performances 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.
