From d854443fc287d1bd9e1977c836f4c6b946cfcbe2 Mon Sep 17 00:00:00 2001 From: Giorgio Calderone Date: Mon, 13 Apr 2020 19:25:07 +0200 Subject: [PATCH] Docs updated --- docs/src/advanced.md | 48 ++++++++++++++++++++------------------------ docs/src/basic.md | 43 ++++++++++++++++++++++++++------------- 2 files changed, 51 insertions(+), 40 deletions(-) diff --git a/docs/src/advanced.md b/docs/src/advanced.md index b9c3f14..b3aa3a1 100644 --- a/docs/src/advanced.md +++ b/docs/src/advanced.md @@ -1,17 +1,16 @@ -# Advanced usage - -Here we will show a few advanced techniques for data visualization using **Gnuplot.jl**. - - ```@setup abc using Gnuplot Gnuplot.quitall() mkpath("assets") -saveas(file) = save(term="pngcairo size 480,360 fontscale 0.8", output="assets/$(file).png") empty!(Gnuplot.options.init) -gpexec("set term unknown") +push!( Gnuplot.options.init, "set term unknown") +empty!(Gnuplot.options.reset) +push!( Gnuplot.options.reset, linetypes(:Set1_5, lw=2)) +saveas(file) = save(term="pngcairo size 550,350 fontscale 0.8", output="assets/$(file).png") ``` +# Advanced usage +Here we will show a few advanced techniques for data visualization using **Gnuplot.jl**. ## Named datasets @@ -128,7 +127,6 @@ The output value is the exit status of the underlying gnuplot process. You may also quit all active sessions at once with [`Gnuplot.quitall()`](@ref): ```@repl abc Gnuplot.quitall() -gpexec("set term unknown") # hide ``` ## Histograms @@ -218,14 +216,9 @@ 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](@ref). If you simply wish to execute a command, without storing it in the session, use [`gpexec`](@ref). E.g. if you wish to temporarily change the current terminal: -```@repl abc -gpexec("set term wxt"); -``` -The gnuplot process replies are returned as a string, e.g.: +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](@ref). If you simply wish to execute a command without storing it in the session, and possibly retrieve a value, use [`gpexec`](@ref). E.g. if you wish to retrieve the value of a gnuplot variable: ```@repl abc gpexec("print GPVAL_TERM") -gpexec("set term unknown") #hide ``` You may also provide a session ID as first argument (see [Multiple sessions](@ref)) to redirect the command to a specific session. @@ -233,9 +226,8 @@ You may also provide a session ID as first argument (see [Multiple sessions](@re ## Dry sessions A "*dry session*" is a session with no underlying gnuplot process. To enable dry sessions type: -```@repl abc +```julia Gnuplot.options.dry = true; -Gnuplot.options.dry = false #hide ``` before starting a session (see also [Options](@ref)). Note that the `dry` option is a global one, i.e. it affects all sessions started after setting the option. @@ -245,15 +237,21 @@ If a gnuplot process can not be started the package will print a warning, and au ## Options -Thepackage options are stored in a global structure available in Julia as `Gnuplot.option` (the type of the structure is [`Gnuplot.Options`](@ref)). The most important settings are as follows: +The package options are stored in a global structure available in Julia as `Gnuplot.option` (the type of the structure is [`Gnuplot.Options`](@ref)). The most important settings are as follows: -- `dry::Bool`: if true all new sessions will be started [Dry sessions](@ref). Default is `false`, but if the package is not able to start a gnuplot it will automatically switch to `false`; +- `dry::Bool`: if true all new sessions will be started as [Dry sessions](@ref). 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: +- `init::Vector{String}`: initialization commands to be executed when a new session is created. Default is an empty vector. It can be used to, e.g., set a custom terminal: ```@repl abc -push!(Gnuplot.options.init, "set term sixelgd"); +push!(Gnuplot.options.start, "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](@ref); +Note that this is option affect all the newly created sessions, not the older ones. Also note that the commands in `Gnuplot.options.init` **are not** saved in [Gnuplot scripts](@ref); + +- `reset::Vector{String}`: initialization commands to be executed when a session is reset. Default is an empty vector. It can be used to, e.g., set custom linetypes or palette: +```@repl abc +push!(Gnuplot.options.init, linetypes(:Set1_5, lw=2)); +``` +Note that this is option affect all the sessions. Also note that the commands in `Gnuplot.options.reset` **are** saved in [Gnuplot scripts](@ref); - `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.: ```@repl abc @@ -262,14 +260,11 @@ Gnuplot.options.verbose = true; x = 1.:10; @gp x x.^2 "w l t 'Parabola'" save(term="pngcairo size 480,360 fontscale 0.8", output="output.png") +Gnuplot.options.verbose = false # hide +gpexec("set term unknown") # hide ``` 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`; -```@setup abc -Gnuplot.options.verbose = false -gpexec("set term unknown") -``` - - `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; @@ -278,3 +273,4 @@ gpexec("set term unknown") - `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. + diff --git a/docs/src/basic.md b/docs/src/basic.md index 0bc8c66..9f61f06 100644 --- a/docs/src/basic.md +++ b/docs/src/basic.md @@ -3,9 +3,11 @@ using Gnuplot Gnuplot.quitall() mkpath("assets") Gnuplot.splash("assets/logo.png") -saveas(file) = save(term="pngcairo size 480,360 fontscale 0.8", output="assets/$(file).png") empty!(Gnuplot.options.init) -gpexec("set term unknown") +push!( Gnuplot.options.init, "set term unknown") +empty!(Gnuplot.options.reset) +push!( Gnuplot.options.reset, linetypes(:Set1_5, lw=2)) +saveas(file) = save(term="pngcairo size 550,350 fontscale 0.8", output="assets/$(file).png") ``` # Basic usage @@ -209,22 +211,34 @@ saveas("ex008a") # hide ``` ![](assets/ex008a.png) +The list of all available palette can be retrieved with [`palette_names()`](@ref): +```@repl abc +palette_names() +``` -The [ColorSchemes](https://juliagraphics.github.io/ColorSchemes.jl/stable/basics/#Pre-defined-schemes-1) palettes can also be used to generate line types (actually just line colors), by means of the [`linetypes()`](@ref) function, e.g. + +The [ColorSchemes](https://juliagraphics.github.io/ColorSchemes.jl/stable/basics/#Pre-defined-schemes-1) palettes can also be used to generate line type colors, and optionally the line width, point size and dashed pattern, by means of the [`linetypes()`](@ref) function, e.g. ```@example abc -@gp linetypes(:deepsea) -x = 1:0.1:4pi -for i in 1:5 - @gp :- x i.* sin.(x) "w l notit lw 5" +@gp "set key left" "set multiplot layout 1,2" +@gp :- 1 linetypes(:Set1_5, lw=2) +for i in 1:10 + @gp :- i .* (0:10) "w lp t '$i'" +end +@gp :- 2 linetypes(:Set1_5, dashed=true, ps=2) +for i in 1:10 + @gp :- i .* (0:10) "w lp t '$i'" end saveas("ex009") # hide ``` ![](assets/ex009.png) -The list of all available palette can be retrieved with [`palette_names()`](@ref): -```@repl abc -palette_names() +The plot on the left features the `:Set1_5` palette and where each line is solid and has a width of 2 by default. The plot on the right shows the same palette but default line widths are 1, default point size is 2 (for the first N line types, where N is the number of discrete colors in the palette), and the dashed pattern is automatically changed. + +You may set a default line types for all plots with: +```julia +push!( Gnuplot.options.init, linetypes(:Set1_5, lw=2)) ``` +(see [Options](@ref) for further informations). All plot in this documentation were generated with the latter settings. ## Exporting plots to files @@ -237,13 +251,13 @@ terminals() Once you choose the proper terminal (i.e. format of the exported file), use the [`save()`](@ref) function to export. As an example, all the plots in this page have been saved with: ```julia -save(term="pngcairo size 480,360 fontscale 0.8", output="assets/output.png") +save(term="pngcairo size 550,350 fontscale 0.8", output="assets/output.png") ``` Note that you can pass both the terminal name and its options via the `term=` keyword. See [Gnuplot terminals](@ref) for further info on the terminals. ## Gnuplot scripts -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 re-create a figure using just gnuplot. +Besides exporting plots in image files, **Gnuplot.jl** can also save a *script*, i.e. a file containing the minimum set of data and commands required to re-create a figure using just gnuplot. The script allows a complete decoupling of plot data and aethetics, from the Julia code used to generate them. With scripts you can: - modify all aesthetic details of a plot without re-running the (possibly complex and time-consuming) code used to generate it; @@ -257,7 +271,7 @@ after the plot has been displayed. Note that when images or large datasets are E.g., the following code: -```julia +```@example abc x = 1:10 @gp x x.^2 "w l" save("script1.gp") @@ -283,7 +297,7 @@ set output ``` While the following: -```julia +```@example abc img = testimage("lighthouse"); @gp "set size square" "set autoscale fix" img "rotate=-90deg with rgbimage notit" save("script2.gp") @@ -301,6 +315,7 @@ set output The above scripts can be loaded into a pure gnuplot session (Julia is no longer needed) as follows: ``` gunplot> load 'script1.gp' +gunplot> load 'script2.gp' ``` to generate a plot identical to the original one.