mantao/Gnuplot.jl
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Docs updated

Browse Source
This commit is contained in:
Giorgio Calderone 2020-04-16 14:01:54 +02:00
parent 2bb942c80a
commit 70e12809c4
6 changed files with 160 additions and 117 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
ChangeLog.md
View File

@ -1,25 +1,33 @@
# Version 1.2.0 (not yet released)
# Version 1.2.0 (not yet released)
- New features:
* REPL mode: a new `Gnuplot.repl_init()` function is available to
install a gnuplot REPL;
* `@gp` and `@gsp` now accepts a `Gnuplot.PlotRecipe` object,
collect commands, data and plot specifications in a single
* `@gp` and `@gsp` now accepts a `Gnuplot.PlotElements` object,
containing commands, data and plot specifications in a single
argument;
* The `plotrecipe` function can be extended to register new implicit
* The `recipe()` function can be extended to register new implicit
recipes to display input data;
* The `linetypes` function now accept the `lw` and `ps` keywords
(to set the line width and point size respectively), and the
`dashed` keyword (to use dashed patterns in place of solid
lines);
* The `linetypes` function now accept the `lw`, `ps` (to set the
line width and point size respectively), and the `dashed` (to
use dashed patterns in place of solid lines) keywords;
* The new `Gnuplot.options.reset::Vector{String}` field allows to
set initialization commands to be executed when a session is
reset. Unlike `Gnuplot.options.reset`, these commands are saved
in the session and can be dumped to a script;
reset. Unlike `Gnuplot.options.init`, these commands are saved
in the session and can be saved into a script;
* New functions: `gpvars()` to retrieve all gnuplot variables,
`gpmargins()` to retrieve current plot margins (in screen
coordinates, `gpranges()` to retrieve current plot axis ranges;
* New keywords for `@gp` and `@gsp`: `lmargin`, `rmargin`,
`bmargin`, `tmargin`, `margins`, to set plot margins;
- New recipes:
- Bugfix:
* When a `Vector{String}` is passed to `driver()` it used to be

23
docs/src/advanced.md
View File

@ -2,10 +2,11 @@
using Gnuplot
Gnuplot.quitall()
mkpath("assets")
empty!(Gnuplot.options.init)
push!( Gnuplot.options.init, "set term unknown")
empty!(Gnuplot.options.reset)
push!( Gnuplot.options.reset, linetypes(:Set1_5, lw=2))
push!( Gnuplot.options.reset, linetypes(:Set1_5, lw=1.5))
saveas(file) = save(term="pngcairo size 550,350 fontscale 0.8", output="assets/$(file).png")
```
@ -51,9 +52,9 @@ name = "\$MyDataSet1"
The parameter best fit values can be retrieved as follows:
```@example abc
@info("Best fit values:",
a = gpexec("print a"),
b = gpexec("print b"),
c = gpexec("print c"))
a = gpexec("print a"),
b = gpexec("print b"),
c = gpexec("print c"))
```
A named dataset is available until the session is reset, i.e. as long as `:-` is used as first argument to `@gp`.
@ -112,7 +113,7 @@ In order to redirect commands to a specific session simply insert a symbol into
@gp :GP2 "plot sin(x)" # opens secondo window
@gp :- :GP1 "plot cos(x)" # add a plot on first window
```
The session ID can appear in every position in the argument list, but only one ID can be present in each call. If the session ID is not specified the `:default` session is considered.
The session ID can appear in every position in the argument list, but only one ID can be present in each call. If the session ID is not specified the `:default` session is used.
The names of all current sessions can be retrieved with [`session_names()`](@ref):
```@repl abc
@ -131,7 +132,7 @@ Gnuplot.quitall()
```
## Histograms
**Gnuplot.jl** provides facilities to compute and display histograms, through the [`hist()`](@ref) function. E.g., to quickly preview an histogram:
**Gnuplot.jl** provides facilities to compute (see [`hist()`](@ref) function) and display (see [Histogram recipes](@ref)) histograms. E.g., to quickly preview an histogram:
```@example abc
x = randn(1000);
@gp hist(x)
@ -141,7 +142,7 @@ saveas("ex013a") # hide
A finer control on the output is achieved by setting the range to consider (`range=` keyword) and either the bin size (`bs=`) or the total number of bins (`nbins=`) in the histogram. See [`hist()`](@ref) documentation for further information.
Moreover, the [`hist()`](@ref) return a [`Gnuplot.Histogram1D`](@ref) structure, whose content can be exploited to customize histogram appearence, e.g.:
The [`hist()`](@ref) return a [`Gnuplot.Histogram1D`](@ref) structure, whose content can be exploited to customize histogram appearence, e.g.:
```@example abc
x = randn(1000);
h = hist(x, range=3 .* [-1,1], bs=0.5)
@ -227,6 +228,14 @@ You may also provide a session ID as first argument (see [Multiple sessions](@re
Alternatively you may start the [The gnuplot REPL](@ref) 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:
```julia
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:
```julia

116
docs/src/basic.md
View File

@ -6,7 +6,7 @@ Gnuplot.splash("assets/logo.png")
empty!(Gnuplot.options.init)
push!( Gnuplot.options.init, "set term unknown")
empty!(Gnuplot.options.reset)
push!( Gnuplot.options.reset, linetypes(:Set1_5, lw=2))
push!( Gnuplot.options.reset, linetypes(:Set1_5, lw=1.5))
saveas(file) = save(term="pngcairo size 550,350 fontscale 0.8", output="assets/$(file).png")
```
@ -18,9 +18,9 @@ The most important symbols exported by the package are the [`@gp`](@ref) (for 2D
```@example abc
using Gnuplot
@gp 1:20
saveas("ex000") # hide
saveas("basic000") # hide
```
![](assets/ex000.png)
![](assets/basic000.png)
Both macros accept any number of arguments, whose meaning is interpreted as follows:
@ -56,17 +56,17 @@ before running the examples.
#### Plot a sinusoid:
```@example abc
@gp "plot sin(x)"
saveas("ex001") # hide
saveas("basic001") # hide
```
![](assets/ex001.png)
![](assets/basic001.png)
---
#### Plot two curves:
```@example abc
@gp "set key left" "plot sin(x)" "pl cos(x)"
saveas("ex002") # hide
saveas("basic002") # hide
```
![](assets/ex002.png)
![](assets/basic002.png)
!!! note
Note that all gnuplot commands can be abbreviated as long as the resulting string is not ambiguous. In the example above we used `pl` in place of `plot`.
@ -77,9 +77,9 @@ saveas("ex002") # hide
@gp "set grid" :-
@gp :- "p sin(x)" :-
@gp :- "plo cos(x)"
saveas("ex003") # hide
saveas("basic003") # hide
```
![](assets/ex003.png)
![](assets/basic003.png)
!!! note
The trailing `:-` symbol means the plot will not be updated until the last statement.
@ -89,9 +89,9 @@ saveas("ex003") # hide
#### Plot a parabola
```@example abc
@gp (1:20).^2
saveas("ex004") # hide
saveas("basic004") # hide
```
![](assets/ex004.png)
![](assets/basic004.png)
---
@ -99,9 +99,9 @@ saveas("ex004") # hide
```@example abc
x = 1:20
@gp "set key left" x ./ 20 x.^2 "with lines tit 'Parabola'"
saveas("ex005") # hide
saveas("basic005") # hide
```
![](assets/ex005.png)
![](assets/basic005.png)
---
#### Multiple datasets, logarithmic axis, labels and colors, etc.
@ -112,9 +112,9 @@ x = 1:0.1:10
@gp :- x x.^0.5 "w l tit 'Pow 0.5' dt 2 lw 2 lc rgb 'red'"
@gp :- x x "w l tit 'Pow 1' dt 1 lw 3 lc rgb 'blue'"
@gp :- x x.^2 "w l tit 'Pow 2' dt 3 lw 2 lc rgb 'purple'"
saveas("ex006") # hide
saveas("basic006") # hide
```
![](assets/ex006.png)
![](assets/basic006.png)
!!! note
The above example lacks the trailing `:-` symbol. This means the plot will be updated at each command, adding one curve at a time.
@ -135,6 +135,11 @@ In order to avoid typing long, and very frequently used gnuplot commands, **Gnup
- `xlog=true` => `set logscale x`;
- `ylog=true` => `set logscale y`;
- `zlog=true` => `set logscale z`;
- `margins=...` => `set margins ...`;
- `lmargin=...` => `set lmargin ...`;
- `rmargin=...` => `set rmargin ...`;
- `bmargin=...` => `set bmargin ...`;
- `tmargin=...` => `set tmargin ...`;
All such keywords can be abbreviated to unambiguous names.
@ -151,39 +156,31 @@ can be replaced with a shorter version:
where `NaN` in the `xrange` keyword means using axis autoscaling.
## Plot images
## Plot matrix as images
**Gnuplot.jl** can also display images, i.e. 2D arrays:
**Gnuplot.jl** can display a 2D matrix as an image:
```@example abc
img = randn(Float64, 30, 50)
img = randn(Float64, 15, 5)
img[10,:] .= -5
@gp img "w image notit"
saveas("ex007a") # hide
saveas("basic007a") # hide
```
![](assets/ex007a.png)
![](assets/basic007a.png)
Note that the first index in the `img` matrix corresponds to the `x` coordinate when the image is displayed.
Note that the first index in the `img` matrix corresponds to the rows in the displayed image 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):
A simple way to remember the convention is to compare how matrix are displayed on the REPL:
```@example abc
using TestImages
img = testimage("lighthouse");
@gp "set size square" "set autoscale fix" img "rotate=-90deg with rgbimage notit"
saveas("ex007b") # hide
img = reshape(1:15, 5, 3)
```
![](assets/ex007b.png)
To display a gray image use `with image` in place of `with rgbimage`, e.g.:
and their image representation, which is essentially upside down:
```@example abc
img = testimage("walkbridge");
@gp palette(:viridis) "set size square" "set autoscale fix" img "rotate=-0.5pi with image notit"
saveas("ex007c") # hide
@gp img "w image notit"
saveas("basic007b") # hide
```
![](assets/ex007c.png)
Note that we used a custom palette (`:lapaz`, see [Palettes and line types](@ref)) and the rotation angle has been expressed in radians (`-0.5pi`).
![](assets/basic007b.png)
Also note that the `img[1,1]` pixel is shown at coordinates x=0, y=0. See [Image recipes](@ref) for further info.
## [3D plots](@id plots3d)
@ -193,9 +190,9 @@ E.g., to plot a spiral increasing in size along the `X` direction:
```@example abc
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"
saveas("ex008") # hide
saveas("basic008") # hide
```
![](assets/ex008.png)
![](assets/basic008.png)
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.
@ -208,9 +205,9 @@ A gnuplot-compliant palette can be retrieved with [`palette()`](@ref), and used
x = 0:0.1:10pi
@gsp palette(:viridis) cbr=[-1,1].*30 :-
@gsp :- x sin.(x) .* x cos.(x) .* x x./20 "w p pt 7 ps var lc pal"
saveas("ex008a") # hide
saveas("basic008a") # hide
```
![](assets/ex008a.png)
![](assets/basic008a.png)
The list of all available palette can be retrieved with [`palette_names()`](@ref):
```@repl abc
@ -220,31 +217,36 @@ palette_names()
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 "set key left" "set multiplot layout 1,2"
@gp :- 1 linetypes(:Set1_5, lw=2)
@gp key="left" 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
saveas("basic009a") # hide
```
![](assets/ex009.png)
![](assets/basic009a.png)
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:
```@example abc
@gp key="left" linetypes(:Set1_5, dashed=true, ps=2)
for i in 1:10
@gp :- i .* (0:10) "w lp t '$i'"
end
saveas("basic009b") # hide
```
![](assets/basic009b.png)
The first plot features the `:Set1_5` palette, with solid lines whose width is 2 times the default. The second plot 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.
As discussed in [Options](@ref), you may set a default line types for all plots with:
```julia
push!( Gnuplot.options.init, linetypes(:Set1_5, lw=2))
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.
All plot in this documentation were generated with these settings.
## Exporting plots to files
**Gnuplot.jl** to export all plots (as well as multiplots, see [Multiplot](@ref)) to an external file using one of the many available gnuplot terminals. To check which terminals are available in your platform type:
**Gnuplot.jl** can export all plots (as well as multiplots, see [Multiplot](@ref)) to an external file using one of the many available gnuplot terminals. To check which terminals are available in your platform type:
```@repl abc
terminals()
```
@ -299,17 +301,17 @@ set output
While the following:
```@example abc
img = testimage("lighthouse");
@gp "set size square" "set autoscale fix" img "rotate=-90deg with rgbimage notit"
img = randn(100, 300);
@gp "set size ratio -1" "set autoscale fix" img "flipy with image notit"
save("script2.gp")
```
will produce:
```
reset session
set size square
set size ratio -1
set autoscale fix
plot \
'./script2_data/jl_vH8X4k' binary array=(512, 768) rotate=-90deg with rgbimage notit
'./script2_data/jl_OQrt9A' binary array=(300, 100) flipy with image notit
set output
```

14
docs/src/install.md
View File

@ -8,23 +8,11 @@ If `gnuplot` is not available in your platform you can still use **Gnuplot.jl**
## Package installation
In the Julia REPL type:
```julia-repl
julia> ]add Gnuplot
julia> ]add Gnuplot@1.2.0
```
The `]` character starts the Julia [package manager](https://julialang.github.io/Pkg.jl/v1/getting-started.html#Basic-Usage-1). Then hit backspace key to return to Julia REPL.
## Check installation
Check **Gnuplot.jl** version with:
```julia-repl
julia> ]st Gnuplot
Status `~/.julia/environments/v1.4/Project.toml`
[dc211083] Gnuplot v1.1.0
```
If the displayed version is not `v1.1.0` you are probably having a dependency conflict. In this case try forcing installation of the correct version with:
```julia-repl
julia> ]add Gnuplot@1.1.0
```
and check which package is causing the conflict.
Check execution and version of the underlying `gnuplot` process:
```@repl

27
docs/src/options.md
View File

@ -2,10 +2,11 @@
using Gnuplot
Gnuplot.quitall()
mkpath("assets")
empty!(Gnuplot.options.init)
push!( Gnuplot.options.init, "set term unknown")
empty!(Gnuplot.options.reset)
push!( Gnuplot.options.reset, linetypes(:Set1_5, lw=2))
push!( Gnuplot.options.reset, linetypes(:Set1_5, lw=1.5))
saveas(file) = save(term="pngcairo size 550,350 fontscale 0.8", output="assets/$(file).png")
```
@ -24,7 +25,7 @@ Note that this is option affect all the newly created sessions, not the older on
- `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.reset, linetypes(:Set1_5, lw=2));
push!(Gnuplot.options.reset, linetypes(:Set1_5, lw=1.5));
```
Note that this is option affect all the sessions. Also note that the commands in `Gnuplot.options.reset` **are** saved in [Gnuplot scripts](@ref);
@ -37,8 +38,8 @@ 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
push!( Gnuplot.options.reset, linetypes(:Set1_5, lw=2)); # hide
gpexec("set term unknown"); # hide
push!( Gnuplot.options.reset, linetypes(:Set1_5, lw=1.5)); # 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`;
@ -88,21 +89,3 @@ At the Julia prompt you may load the package and the associated settings by typi
julia> @gnuplotrc
```
and you're ready to go.
## The gnuplot REPL
The **Gnuplot.jl** package comes with a built-in REPL mode to directly send commands to the underlying gnuplot process. In order to avoid conflcts with other REPL modes, you need to explicitly activate such mode with:
```julia
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.
If you wish to activate the REPL at Julia startup insert th following code in `.julia/config/startup.jl`:
```julia
using Gnuplot
atreplinit() do repl
Gnuplot.repl_init(start_key='>')
end
```

69
docs/src/recipes.md
View File

@ -1,20 +1,73 @@
```@setup abc
using Gnuplot
Gnuplot.quitall()
mkpath("assets")
empty!(Gnuplot.options.init)
push!( Gnuplot.options.init, "set term unknown")
empty!(Gnuplot.options.reset)
push!( Gnuplot.options.reset, linetypes(:Set1_5, lw=1.5))
saveas(file) = save(term="pngcairo size 550,350 fontscale 0.8", output="assets/$(file).png")
```
# Plot recipes
A plot *recipe* is a function to convert data from the "Julia world" into one, or more, `Gnuplot.PlotElements` object(s) suitable to be ingested in **Gnuplot.jl**. These objects contain all the informations to create a plot, and can be passed directly to `@gp` or `@gsp`. The main purpose of recipes is to provide quick data visualization procedures.
A plot *recipe* is a quicklook visualization procedure aimed at reducing the amount of repetitive code needed to generate a plot. More specifically, a recipe is a function to convert data from the "Julia world" into a form suitable to be ingested in **Gnuplot.jl**.
There are two kinds of recipes:
- *explicit* recipe: a function which is explicitly invoked by the user. It can have any name and accept any number of arguments and keywords. It is typically used when the visualization of a data type requires some extra information, beside data itself. An example is the quicklook procedure for a `DataFrame` object (shown below);
- *implicit* recipe: a function which is automatically called by **Gnuplot.jl**. It must extend the `Gnuplot.recipe` function, and accept exactly one mandatory argument. It is typically used when the visualization is completely determined by the data type itself. An example is the visualization of a `Matrix{ColorTypes.RGB}` object as an image.
In both cases the recipe function must return a scalar, or a vector of, `PlotElements` object(s), containing all the informations to create a plot, or a part of it.
There are two kinds of plot recipes:
- *explicit* recipe: a function which is explicitly invoked by the user. It can have any name, and accept any number of arguments and keywords. It is typically used when the conversion from Julia data to `Gnuplot.Recipe` objects requires some extra informations, beside data itself. An example is the quick look procedure for a `DataFrame` object (shown below);
The `@gp` or `@gsp`.
In , and can be passed directly to `@gp` or `@gsp`.
- *implicit* recipe: a function which is automatically called by **Gnuplot.jl** (never by the user). It must extend the `Gnuplot.recipe` function, and accept exactly one argument and no keywords. it is typically used when the conversion is completely determined by the data type itself. An example is the plot of a `Matrix{ColorTypes.RGB}` data as an image.
In both cases the recipe function must return a scalar, or a vector of, `Gnuplot.PlotElements` object(s). The fields of the structure are:
. The fields of the `PlotElements` structure are:
- `mid::Int`:: multiplot ID;
- `cmds::Vector{String}`: commands to set plot properties;
- `data::Vector{DataSet}`: data sets to plot;
- `plot::Vector{String}`: plot specifications for each `DataSet`.
- `data::Vector{Dataset}`: data set(s);
- `plot::Vector{String}`: plot specifications for each `Dataset`;
`DataSet` is an abstract type, the actual data sets are stored in the form of either a `DataSetText` object (a textual representation of the data) or a `DataSetBin` object (a binary file). Both `DataSetText` and `DataSetBin` structures provide a number of constructors accepting several types of input data.
where `Dataset` is an abstract type, the actual data sets are stored in the form of either a `DatasetText` object (a textual representation of the data) or a `DatasetBin` object (a binary file). Both `DatasetText` and `DatasetBin` structures provide a number of constructors accepting several types of input data.
As anticipated, a recipe can be explicitly called by the user and the output passed to `@gp` or `@gsp`.
All arguments to `@gp` or `@gsp` (except `Int`s, `String`s, `Tuple`s, `Array` of both numbers and strings) are scanned to check if an implicit recipe exists to handle them, and in this case it is
Although a recipe provides a very efficient mean for data exploration,
## Histogram recipes
## Image recipes
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):
```@example abc
using TestImages
img = testimage("lighthouse");
@gp img
saveas("recipes007b") # hide
```
![](assets/recipes007b.png)
To display a gray image use `with image` in place of `with rgbimage`, e.g.:
```@example abc
img = testimage("walkbridge");
@gp palette(:viridis) recipe(img, "flipy rot=15deg")
saveas("recipes007c") # hide
```
![](assets/recipes007c.png)
Note that we used a custom palette (`:lapaz`, see [Palettes and line types](@ref)) and the rotation angle has been expressed in radians (`-0.5pi`).