Docs updated
This commit is contained in:
Giorgio Calderone
parent
4a1284117b
commit
fa435eee04
267
README.md
267
README.md
@ -1,261 +1,34 @@
|
||||
# Gnuplot.jl
|
||||
## A Julia interface to Gnuplot.
|
||||
|
||||
[](https://travis-ci.org/gcalderone/Gnuplot.jl)
|
||||
|:------------------:|:------------------------------------------------------------------------------------------------------------------------------------:|
|
||||
- ** Build status** | [](https://travis-ci.org/gcalderone/Gnuplot.jl) |
|
||||
|:------------------:|:------------------------------------------------------------------------------------------------------------------------------------:|
|
||||
| **License** | [](LICENSE.md) |
|
||||
|:------------------:|:------------------------------------------------------------------------------------------------------------------------------------:|
|
||||
| **Documentation** | [](https://gcalderone.github.io/Gnuplot.jl/dev/) |
|
||||
|:------------------:|:------------------------------------------------------------------------------------------------------------------------------------:|
|
||||
| **Examples** | [Examples](https://img.shields.io/website?style=flat)](https://lazarusa.github.io/gnuplot-examples//) |
|
||||
|:------------------:|:------------------------------------------------------------------------------------------------------------------------------------:|
|
||||
|
||||
**Gnuplot.jl** allows easy and fast use of [Gnuplot](http://gnuplot.info/) as a data visualization tool in Julia. Its main features are:
|
||||
|
||||
- transparent interface between Julia and Gnuplot to exploit all functionalities of the latter, both present and future ones;
|
||||
|
||||
- fast data transmission to gnuplot through system pipes (no temporary files involved);
|
||||
|
||||
- handles multiple Gnuplot process simultaneously;
|
||||
|
||||
- support for multiplots;
|
||||
|
||||
- save sessions into gnuplot scripts;
|
||||
|
||||
- extremely concise syntax (see examples below) makes it ideal for interactive data exploration;
|
||||
|
||||
- very easy to use: if you know Gnuplot you're ready to go.
|
||||
|
||||
The purpose is similar to the [Gaston](https://github.com/mbaz/Gaston.jl) package, but **Gnuplot.jl** main focus is on on the syntax conciseness and ease of use.
|
||||
**Gnuplot.jl** provides a simple package able to send both data and commands from Julia to an underlying [gnuplot](http://gnuplot.sourceforge.net/) process. Its main purpose it to provide a fast and powerful data visualization framework, using an extremely concise Julia syntax.
|
||||
|
||||
The documentation can be found [here](https://gcalderone.github.io/Gnuplot.jl/dev/), while the gallery of examples is maintained [here](https://lazarusa.github.io/gnuplot-examples/).
|
||||
|
||||
## Installation
|
||||
In the Julia REPL type:
|
||||
|
||||
``` julia
|
||||
using Pkg
|
||||
Pkg.add("Gnuplot")
|
||||
Install with:
|
||||
```julia-repl
|
||||
]dev Gnuplot
|
||||
```
|
||||
You'll also need [gnuplot](http://gnuplot.info/) (ver. >= 4.7) installed on your system, and its executable available in your path.
|
||||
A working [gnuplot](http://gnuplot.sourceforge.net/) package must be installed on your platform.
|
||||
|
||||
## Usage:
|
||||
The simplemost plot ever can be generated with just 7 characters:
|
||||
``` Julia
|
||||
|
||||
Test package:
|
||||
```julia-repl
|
||||
using Gnuplot
|
||||
@gp 1:9
|
||||
```
|
||||
|
||||
A slightly more complicated one showing a parabola with a solid line and a legend:
|
||||
``` Julia
|
||||
x = 1:100
|
||||
@gp x x.^2 "w l tit 'Parabola'"
|
||||
```
|
||||
|
||||
A real life example showing some random noise generated data:
|
||||
``` Julia
|
||||
x = range(-2pi, stop=2pi, length=100);
|
||||
y = 1.5 .* sin.(0.3 .+ 0.7x) ;
|
||||
noise = randn(length(x))./2;
|
||||
e = 0.5 * fill(1., length(x));
|
||||
|
||||
@gp("set key horizontal", "set grid", title="My title",
|
||||
xrange=(-7,7), ylabel="Y label", xlab="X label",
|
||||
x, y, "w l t 'Real model' dt 2 lw 2 lc rgb 'red'",
|
||||
x, y+noise, e, "w errorbars t 'Data'")
|
||||
```
|
||||
The syntax should be familiar to most gnuplot users. With the code above we:
|
||||
- set a few gnuplot properties (`key` and `grid`);
|
||||
- set the X axis range and Y axis label;
|
||||
- send the data to Gnuplot;
|
||||
- plot two data sets specifying a few details (style, line width, color, legend, etc...).
|
||||
|
||||
Note that this simple example already covers the vast majority of use cases, since the remaining details of the plot can be easily tweaked by adding the appropriate Gnuplot commands. Also note that you would barely recognize the Julia language by just looking at the `@gp` call since **Gnuplot.jl** aims to be mostly transparent: the user is supposed to focus only on the data and on the Gnuplot commands, rather than the package interface.
|
||||
|
||||
If you set the verbose option (`Gnuplot.setverbose(true)`, which is `false` by default) you'll be able to see all the communication taking place between the **Gnuplot.jl** package and the underlyng Gnuplot process. Repeating the last command:
|
||||
```Julia
|
||||
julia> @gp("set key horizontal", "set grid", title="My title",
|
||||
xrange=(-7,7), ylabel="Y label", xlab="X label",
|
||||
x, y, "w l t 'Real model' dt 2 lw 2 lc rgb 'red'",
|
||||
x, y+noise, e, "w errorbars t 'Data'")
|
||||
GNUPLOT (default) print GPVAL_TERM
|
||||
GNUPLOT (default) -> wxt
|
||||
GNUPLOT (default) print GPVAL_TERMOPTIONS
|
||||
GNUPLOT (default) -> 0 enhanced
|
||||
GNUPLOT (default) set term wxt 0 enhanced title 'Gnuplot.jl: default'
|
||||
GNUPLOT (default) reset session
|
||||
GNUPLOT (default) set key horizontal
|
||||
GNUPLOT (default) set grid
|
||||
GNUPLOT (default) set title "My title"
|
||||
GNUPLOT (default) set xrange [-7:7]
|
||||
GNUPLOT (default) set ylabel "Y label"
|
||||
GNUPLOT (default) set xlabel "X label"
|
||||
GNUPLOT (default) $data0 << EOD
|
||||
GNUPLOT (default) -6.283185307179586 1.2258873407968363
|
||||
GNUPLOT (default) -6.156252270670907 1.1443471266509504
|
||||
GNUPLOT (default) -6.029319234162229 1.05377837392046
|
||||
GNUPLOT (default) -5.90238619765355 0.9548956415530343
|
||||
GNUPLOT (default) ...
|
||||
GNUPLOT (default) EOD
|
||||
GNUPLOT (default) $data1 << EOD
|
||||
GNUPLOT (default) -6.283185307179586 2.4842815808516905 0.5
|
||||
GNUPLOT (default) -6.156252270670907 1.2062036112716572 0.5
|
||||
GNUPLOT (default) -6.029319234162229 1.206937328889227 0.5
|
||||
GNUPLOT (default) -5.90238619765355 0.23435472973538996 0.5
|
||||
GNUPLOT (default) ...
|
||||
GNUPLOT (default) EOD
|
||||
GNUPLOT (default) set key horizontal
|
||||
GNUPLOT (default) set grid
|
||||
GNUPLOT (default) set title "My title"
|
||||
GNUPLOT (default) set xrange [-7:7]
|
||||
GNUPLOT (default) set ylabel "Y label"
|
||||
GNUPLOT (default) set xlabel "X label"
|
||||
GNUPLOT (default) plot \
|
||||
$data0 w l t 'Real model' dt 2 lw 2 lc rgb 'red', \
|
||||
$data1 w errorbars t 'Data'
|
||||
```
|
||||
The **Gnuplot.jl** package (note the leading `GNUPLOT`...) tells us which commands are being sent to the gnuplot process and the name of the current gnuplot session (`default`). The **Gnuplot.jl** package will also print the replies from gnuplot, e.g.:
|
||||
``` Julia
|
||||
julia> Gnuplot.exec("print GPVAL_TERM");
|
||||
GNUPLOT (default) print GPVAL_TERM
|
||||
GNUPLOT (default) -> qt
|
||||
```
|
||||
Note the different color in the reply (if your terminal is able to display colors).
|
||||
|
||||
So far we have shown how to produce plots with a single command, however such task can also be performed using multiple statements. The syntax is exactly the same, but we should use the `:-` symbol at the beginning of each statement (except the first) and at the end of each statement (except the last), e.g.:
|
||||
``` Julia
|
||||
# Reset the gnuplot session and use a dataset named `MyDataSet1`
|
||||
name = "\$MyDataSet1"
|
||||
@gp x y+noise e name :-
|
||||
|
||||
# Define a model function to be fitted
|
||||
@gp :- "f(x) = a * sin(b + c*x); a = 1; b = 1; c = 1;" :-
|
||||
|
||||
# Fit the function to the dataset
|
||||
@gp :- "fit f(x) $name u 1:2:3 via a, b, c;" :-
|
||||
|
||||
# Prepare a multiplot showing the data, the model...
|
||||
@gp :- "set multiplot layout 2,1" :-
|
||||
@gp :- "plot $name w points tit 'Data'" ylab="Data and model" :-
|
||||
@gp :- "plot $name u 1:(f(\$1)) w lines tit 'Best fit'" :-
|
||||
|
||||
# ... and the residuals (the `2` here refer to the second plot in the multiplot).
|
||||
@gp :- 2 xlab="X label" ylab="Residuals" :-
|
||||
@gp :- "plot $name u 1:((f(\$1)-\$2) / \$3):(1) w errorbars notit"
|
||||
```
|
||||
|
||||
As discussed above, **Gnuplot.jl** allows to trasparently exploit all gnuplot functionalities. E.g., we can show a random image with:
|
||||
```Julia
|
||||
@gp 1:30 2:50 randn(Float64, 30, 50) "w image"
|
||||
```
|
||||
or show an interactive 3D plots using the `@gsp` macro in place of `@gp`, e.g.:
|
||||
|
||||
``` Julia
|
||||
@gsp randn(Float64, 30, 50)
|
||||
```
|
||||
|
||||
Further documentation for the `@gp` and `@gsp` macros is available in the REPL by means of the `@doc` macro or by typing `?` in the REPL followed by the macro name.
|
||||
|
||||
|
||||
### Export to image
|
||||
TODO
|
||||
|
||||
### Save a script file
|
||||
TODO
|
||||
|
||||
### Multiple gnuplot istances
|
||||
|
||||
The **Gnuplot.jl** package can handle multiple Gnuplot istances simultaneously, each idenitified by a unique session name (actually a Julia symbol). To use a specific session simply name it in a `@gp` or `@gsp` call. If the session is not yet created it will be automatically started:
|
||||
|
||||
``` Julia
|
||||
# Plot using a session named GP1
|
||||
x = 1:10
|
||||
@gp :GP1 x x.^2
|
||||
|
||||
# Plot using a session named GP2
|
||||
@gp x x.^2 :GP2
|
||||
|
||||
# Plot using default session (i.e. do not specify any session name)
|
||||
@gp x x.^2
|
||||
```
|
||||
|
||||
### Terminating a session
|
||||
A session and the associated gnuplot process can be terminated by a call to `quit`, specifying the session name, e.g.:
|
||||
``` Julia
|
||||
julia> Gnuplot.quit(:GP1)
|
||||
```
|
||||
A call to `Gnuplot.quitall()` will terminate all active sessions.
|
||||
|
||||
|
||||
|
||||
## Direct execution of gnuplot commands
|
||||
Both the `@gp` and `@gsp` macros store data and commands in the package state to allow using multiple statements for a single plot, or to save all data and commands on a script file. However the user may directly execute command on the underlying Gnuplot process using the `Gnuplot.exec` function. E.g., we can retrieve the values of the fitting parameters of the previous example:
|
||||
```Julia
|
||||
# Retrieve values fr a, b and c
|
||||
a = Meta.parse(Gnuplot.exec("print a"))
|
||||
b = Meta.parse(Gnuplot.exec("print b"))
|
||||
c = Meta.parse(Gnuplot.exec("print c"))
|
||||
println(Gnuplot.gpversion())
|
||||
test_terminal()
|
||||
```
|
||||
|
||||
|
||||
## Customization
|
||||
|
||||
A custom command to start a Gnuplot process can be specified as follows
|
||||
``` Julia
|
||||
Gnuplot.options.cmd = "/path/to/gnuplot/executable"
|
||||
```
|
||||
|
||||
Also, the package may work in *dry* mode, i.e. without any underlying Gnuplot process:
|
||||
``` Julia
|
||||
Gnuplot.options.dry = true
|
||||
```
|
||||
The prupose is to create gnuplot scripts without running them, e.g:
|
||||
```Julia
|
||||
@gp x x.^2 "w l"
|
||||
save("test.gp")
|
||||
```
|
||||
The `test.gp` can then be loaded directly in gnuplot with:
|
||||
```
|
||||
gnuplot> load 'test.gp'
|
||||
```
|
||||
|
||||
Finally, you can specify initialising commands to be executed when the Gnuplot process starts, in the same way as you use `.gnuplotrc`. For instance, to set up a default terminal:
|
||||
```julia
|
||||
push!(Gnuplot.options.init, "set term sixelgd")
|
||||
```
|
||||
The above command should be executed *BEFORE* starting a new session. (use `Gnuplot.quitall()` will terminate all active sessions).
|
||||
|
||||
|
||||
## Plot in a terminal (no X11)
|
||||
Gnuplot supports displaying plot in a terminal application, with no need for X11 or other window frameworks. This is very useful when you run Julia on a remote shell through `ssh`, through a slow network link.
|
||||
|
||||
The Gnuplot terminals able to operate on "terminal" applications are `dumb` and `sixelgd`. You can use them as default with:
|
||||
```julia
|
||||
push!(Gnuplot.options.init, "set term dumb")
|
||||
```
|
||||
or
|
||||
```julia
|
||||
push!(Gnuplot.options.init, "set term sixelgd")
|
||||
```
|
||||
Note that the latter requires Sixel graphics to be enabled (e.g. `xterm -ti vt340`).
|
||||
|
||||
|
||||
## Line styles and palettes
|
||||
The **Gnuplot.jl** package comes with all the [ColorSchemes](https://juliagraphics.github.io/ColorSchemes.jl/stable/basics/#Pre-defined-schemes-1) palettes readily available.
|
||||
|
||||
A gnuplot-compliant palette can be retrieved with `palette()` and used as any other command, as in the following example:
|
||||
```julia
|
||||
pal1 = palette(:deepsea)
|
||||
pal2 = palette(:viridis)
|
||||
|
||||
x = -8:0.25:8
|
||||
y = -8:0.25:8
|
||||
r = [x.^2 .+ y.^2 for x in x, y in y]
|
||||
z = sin.(sqrt.(r)) ./ sqrt.(r)
|
||||
|
||||
@gsp "set multiplot layout 1,2" "set pm3d depthorder" "set border 0"
|
||||
@gsp :- "unset key" "unset xtics" "unset ytics" "unset ztics" "unset colorbox"
|
||||
@gsp :- "set view 60, 30, 1.5, 0.9"
|
||||
@gsp :- 1 title="deepsea (discrete)" pal1 x y z "w pm3d" 2 tit="viridis (continuous)" pal2 x y z "w pm3d"
|
||||
```
|
||||
|
||||
The [ColorSchemes](https://juliagraphics.github.io/ColorSchemes.jl/stable/basics/#Pre-defined-schemes-1) palettes can also be used to generate line styles, e.g.
|
||||
```julia
|
||||
@gp linestyles(:deepsea)
|
||||
x = 1:0.1:4pi
|
||||
for i in 1:5
|
||||
@gp :- x i.* sin.(x) "w l notit ls $i lw 10"
|
||||
end
|
||||
```
|
||||
|
||||
@ -2,14 +2,14 @@ using Documenter, Gnuplot
|
||||
|
||||
makedocs(sitename="Gnuplot.jl",
|
||||
authors = "Giorgio Calderone",
|
||||
#format = Documenter.HTML(prettyurls = false), # uncomment for local use, comment for deployment
|
||||
format = Documenter.HTML(prettyurls = false), # uncomment for local use, comment for deployment
|
||||
modules=[Gnuplot],
|
||||
pages = [
|
||||
"Home" => "index.md",
|
||||
"Installation" => "install.md",
|
||||
"Basic usage" => "basic.md",
|
||||
"Advanced usage" => "advanced.md",
|
||||
"Tips" => "tips.md",
|
||||
"Gnuplot terminals" => "terminals.md",
|
||||
"Examples" => "examples.md",
|
||||
"API" => "api.md"
|
||||
])
|
||||
|
||||
@ -154,8 +154,8 @@ saveas("ex013b") # hide
|
||||
|
||||
**Gnuplot.jl** also allows to compute 2D histograms by passing two vectors (with the same lengths) to [`hist()`](@ref). A quick preview is simply obtained by:
|
||||
```@example abc
|
||||
x = randn(5000)
|
||||
y = randn(5000)
|
||||
x = randn(10_000)
|
||||
y = randn(10_000)
|
||||
@gp "set size ratio -1" hist(x, y)
|
||||
saveas("ex014a") # hide
|
||||
```
|
||||
@ -163,7 +163,7 @@ saveas("ex014a") # hide
|
||||
|
||||
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`](@ref) structure:
|
||||
```@example abc
|
||||
h = hist(x, y, bs1=0.5, nbins2=10, range1=[-3,3], range2=[-3,3])
|
||||
h = hist(x, y, bs1=0.25, nbins2=20, range1=[-3,3], range2=[-3,3])
|
||||
@gp "set size ratio -1" h.bins1 h.bins2 h.counts "w image notit"
|
||||
saveas("ex014b") # hide
|
||||
```
|
||||
@ -183,9 +183,9 @@ saveas("ex014c") # hide
|
||||
## Contour lines
|
||||
Although gnuplot already handles contours by itself (with the `set contour` command), **Gnuplot.jl** provides a way to calculate contour lines paths before displaying them, using the [`contourlines()`](@ref) function. We may use it for, e.g., plot contour lines with customized widths and palette, according to their z level. Continuing previous example:
|
||||
```@example abc
|
||||
clines = contourlines(h.bins1, h.bins2, h.counts, cntrparam="levels discrete 50, 100, 200");
|
||||
clines = contourlines(h.bins1, h.bins2, h.counts, cntrparam="levels discrete 10, 30, 60, 90");
|
||||
for i in 1:length(clines)
|
||||
@gp :- clines[i].data "w l t '$(clines[i].z)' lw $(1.5 * i) lc pal" :-
|
||||
@gp :- clines[i].data "w l t '$(clines[i].z)' lw $i lc pal" :-
|
||||
end
|
||||
@gp :- key="outside top center box horizontal"
|
||||
saveas("ex014d") # hide
|
||||
@ -197,7 +197,7 @@ saveas("ex014d") # hide
|
||||
|
||||
The [Multiplot](@ref) capabilities can also be used to stack plots one above the other in order to create an animation, as in the following example:
|
||||
```@example abc
|
||||
x = y = -10:3.33:10
|
||||
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" cb=[-1,1] zr=[-1,1]
|
||||
@ -210,7 +210,7 @@ for direction in [-1,1]
|
||||
end
|
||||
@gsp
|
||||
```
|
||||
The animation can also be saved in a gif file with:
|
||||
Here the `frame` variable is used as multiplot index. The animation can be saved in a GIF file with:
|
||||
```@example abc
|
||||
save(term="gif animate size 480,360 delay 5", output="assets/animation.gif")
|
||||
```
|
||||
|
||||
@ -227,7 +227,7 @@ Once you choose the proper terminal (i.e. format of the exported file), use the
|
||||
```julia
|
||||
save(term="pngcairo size 480,360 fontscale 0.8", output="assets/output.png")
|
||||
```
|
||||
Note that you can pass both the terminal name and its options via the `term=` keyword.
|
||||
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
|
||||
|
||||
@ -1,19 +1,12 @@
|
||||
# Examples
|
||||
|
||||
An exhaustive gallery of example is available here:
|
||||
The official gallery of high quality examples is maintained in a separate repository:
|
||||
|
||||
[https://lazarusa.github.io/gnuplot-examples/](https://lazarusa.github.io/gnuplot-examples/)
|
||||
|
||||
Further `gnuplot` examples can be found here: [http://www.gnuplotting.org/](http://www.gnuplotting.org/)
|
||||
```julia
|
||||
Gnuplot.quitall()
|
||||
@gp "set term wxt noenhanced size 600,300" :-
|
||||
@gp :- "set margin 0" "set border 0" "unset tics" :-
|
||||
@gp :- xr=[-0.3,1.7] yr=[-0.3,1.1] :-
|
||||
@gp :- "set origin 0,0" "set size 1,1" :-
|
||||
@gp :- "set label 1 at graph 1,1 right offset character -1,-1 font 'Verdana,20' tc rgb '#4d64ae' ' Ver: " * string(Gnuplot.version()) * "' " :-
|
||||
@gp :- "set arrow 1 from graph 0.05, 0.15 to graph 0.95, 0.15 size 0.2,20,60 noborder lw 9 lc rgb '#4d64ae'" :-
|
||||
@gp :- "set arrow 2 from graph 0.15, 0.05 to graph 0.15, 0.95 size 0.2,20,60 noborder lw 9 lc rgb '#4d64ae'" :-
|
||||
@gp :- ["0.35 0.65 @ 13253682", "0.85 0.65 g 3774278", "1.3 0.65 p 9591203"] "w labels notit font 'Mono,160' tc rgb var"
|
||||
save(term="pngcairo noenhanced size 600,300", output="splash.png")
|
||||
```
|
||||
The examples in this documentation are intentionally very simple, in order to focus on the package functionalities. The only relatively complex, publication-quality plot, is discussed in [The `cairolatex` terminal](@ref) section.
|
||||
|
||||
Keep in mind that **Gnuplot.jl** is just an interface to gnuplot, so everything you can do with the latter is achievable from Julia.
|
||||
Further gnuplot examples can be found here:
|
||||
- [http://gnuplot.sourceforge.net/demo_5.2/](http://gnuplot.sourceforge.net/demo_5.2/)
|
||||
- [http://www.gnuplotting.org/](http://www.gnuplotting.org/)
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
# Useful terminals
|
||||
# Gnuplot terminals
|
||||
|
||||
Gnuplot provides dozens of terminals to display plots or export them into files (see [`terminals()`](@ref) to get a list of enabled terminals on your platform). This section discuss a few tips on how to use the most common terminals.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user