fix stuff

Don't run gnuplot process connected to stdout

.travis.yml

@@ -6,15 +6,15 @@ os:
 #  - osx
 
 julia:
-  - 1.2
+  - 1.5
-  - nightly
+#  - nightly
 
 notifications:
   email: false
 
-matrix:
+#matrix:
-  allow_failures:
+#  allow_failures:
-    - julia: nightly
+#    - julia: nightly
 
 addons:
   apt:

ChangeLog.md

@@ -0,0 +1,121 @@
+# Version 1.4.1 (released on: )
+- New features:
+	* Implicit recipes can now returns a `Vector{PlotElement}`;
+
+	* Allow using single quotes in output file names (#52);
+
+	* New function: `palette_levels()` can be used to modify palette levels before passing them to gnuplot;
+
+- Bugfix:
+	* Fixed `BoundsErrors` in `hist()` (#49);
+
+	* Fixed problem when generating documentation (#51);
+
+
+# Version 1.4.0 (released on: May 5, 2021)
+- New features:
+    * Missing values are accepted if the input arrays have `eltype <:
+      AbstractFloat`;
+
+    * Missing values are also accepted in calls to `hist`;
+
+	* VSCode and Pluto sessions are now properly handled (#35 and #43);
+
+- Bugfix:
+	* Multiplot were not displayed in Jupyter (#25);
+
+	* `gpvars()` fails if gnuplot character encoding is utf8
+      (#24);
+
+
+# Version 1.3.0 (released on: Apr. 29, 2020)
+
+- New features:
+    * The new `dgrid3d()` allows to interpolate scattered 2D data on a
+       2D regular grid;
+
+    * The `Options` structure features a new `mime` field containing a
+      dictionary to map a MIME type to gnuplot terminals;
+
+    * The `Options` structure features a new `gpviewer` field allowing
+      to choose the display behaviour (using either gnuplot
+      interactive terminals or anexternal viewer such as Jupyter or
+      Juno);
+
+    * The `save()` function now accepts a `MIME` argument in place of
+      the `term=` keyword.  The actual terminal is retrieved from the
+      `Options.mime` dictionary;
+
+    * The `contourlines()` function now accepts `AbstractVector` and
+      `AbstractMatrix` as arguments, rather than `Vector` and
+      `Matrix`;
+
+    * The `contourlines()` function now accepts a `fractions` input to
+      generate contours encompassing given fractions of the total
+      counts in a 2D histogram;
+
+    * The `palette()` function now accept a boolean `smooth` keyword,
+      allowing to interpolate a discrete palette into a continuous one.
+
+- Breaking changes:
+    * The `Options` structure no longer provides the `term_svg` and
+      `term_png` fields.  They have been replaced by the `mime`
+      dictionary.
+
+
+# Version 1.2.0 (released on: Apr. 20, 2020)
+
+- New features:
+    * REPL mode: a new `Gnuplot.repl_init()` function is available to
+      install a gnuplot REPL;
+
+    * Implemented the "recipe" mechanism: the `recipe()` function can
+      now be extended to register new implicit recipes to display
+      data;
+
+    * `@gp` and `@gsp` now accepts a `Gnuplot.PlotElements` object,
+      containing commands, data and plot specifications in a single
+      argument;
+
+    * 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.term::String` field allows to set the
+      default terminal for interactive sessions;
+
+    * 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 accepted by `@gp` and `@gsp`: `lmargin`, `rmargin`,
+      `bmargin`, `tmargin`, `margins`, to set plot margins;
+
+    * Implemented new implicit recipes to display histograms (as
+      returned by `hist()`), contour lines (as returned by
+      `contourlines()`) and images;
+
+    * Implemented automatic display of plots in both Jupyter and Juno;
+
+    * Documentation updated;
+
+
+- Breaking changes:
+    * The 2D matrix are now sent to gnuplot in a column-major order,
+      to comply with Julia array layout;
+
+
+- Bugfix:
+    * When a `Vector{String}` is passed to `driver()` it used to be
+    modified, and couldn't be used again in a second call.  Now the
+    original is preserved;
+
+    * `contourlines()` used to return a single blanck line to
+    distinguish iso-contour lines, and this may cause problems in 3D
+    plot.  Now two blanck lines are returned;
+
+
+# Version 1.1.0 (released on: Apr. 09, 2020)
+
+- First production ready version;
+- Completed documentation and example gallery;

Project.toml

@@ -1,22 +1,24 @@
 name = "Gnuplot"
 uuid = "dc211083-a33a-5b79-959f-2ff34033469d"
-version = "1.1.0"
+version = "1.4.1"
 
 [deps]
 ColorSchemes = "35d6a980-a343-548e-a6ea-1d62b119f2f4"
 ColorTypes = "3da002f7-5984-5a60-b8a6-cbb66c0b333f"
 Colors = "5ae59095-9a9b-59fe-a467-6f913c188581"
 DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
+REPL = "3fa0cd96-eef1-5676-8a61-b3b8758bbffb"
+ReplMaker = "b873ce64-0db9-51f5-a568-4457d8e49576"
 StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
 StructC14N = "d2514e9c-36c4-5b8e-97e2-51e7675c221c"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [compat]
-julia = "^1.2"
+ColorSchemes = "^3.12"
-ColorSchemes = "^3.5"
+ColorTypes = "^0.11"
-ColorTypes = "^0.10"
 Colors = "^0.12"
-DataStructures = "^0.17"
+DataStructures = "^0.18"
+ReplMaker = "^0.2"
 StatsBase = "^0.33"
 StructC14N = "^0.3"
-
+julia = "^1.6"

README.md

@@ -1,12 +1,12 @@
 # Gnuplot.jl
-## A Julia interface to Gnuplot.
+## A Julia interface to gnuplot.
 
 [![Build Status](https://travis-ci.org/gcalderone/Gnuplot.jl.svg?branch=master)](https://travis-ci.org/gcalderone/Gnuplot.jl)
 [![License](http://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat)](LICENSE.md)
-[![DocumentationStatus](https://img.shields.io/badge/docs-latest-blue.svg?style=flat)](https://gcalderone.github.io/Gnuplot.jl/v1.1.0/)
+[![DocumentationStatus](https://img.shields.io/badge/docs-stable-blue.svg?style=flat)](https://gcalderone.github.io/Gnuplot.jl/v1.4.0/index.html)
 
 
-**Gnuplot.jl** is 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.
+**Gnuplot.jl** is 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. It also has automatic display of plots in Jupyter, Juno and VS Code.
 
 
 ## Installation
@@ -17,6 +17,16 @@ Install with:
 ```
 A working [gnuplot](http://gnuplot.sourceforge.net/) package must be installed on your platform.
 
+You may check the installed **Gnuplot.jl** version with:
+```julia
+]st Gnuplot
+```
+If the displayed version is not v1.4.0 you are probably having a dependency conflict. In this case try forcing installation of the latest version with:
+```julia
+]add Gnuplot@1.4.0
+```
+and check which package is causing the conflict.
+
 
 Test package:
 ```julia
@@ -24,18 +34,17 @@ using Gnuplot
 println(Gnuplot.gpversion())
 test_terminal()
 ```
-The latest version of **Gnuplot.jl** is 1.1.0.
 
 
 ## Quick start
-The following examples are supposed to be self-explaining.  See [documentation](https://gcalderone.github.io/Gnuplot.jl/v1.1.0/) for further informations.
+The following examples are supposed to be self-explaining.  See [documentation](https://gcalderone.github.io/Gnuplot.jl/v1.4.0/) for further informations.
 
 ### A simple parabola
 ```julia
 x = 1.:20
 @gp x x.^2 "with lines title 'Parabola'"
 save(term="pngcairo size 480,360", output="examples/ex1.png")
-save("parabola.gp")  # => save a script file with both data and command to re-create the plot.  
+save("parabola.gp")  # => save a script file with both data and command to re-create the plot.
 ```
 ![ex1.png](examples/ex1.png)
 
@@ -44,9 +53,9 @@ save("parabola.gp")  # => save a script file with both data and command to re-cr
 ```julia
 x = -2pi:0.1:2pi
 approx = fill(0., length(x));
-@gp t="Polynomial approximation of sin(x)"  key="opaque" linetypes(:Blues_3)
+@gp tit="Polynomial approximation of sin(x)" key="opaque" linetypes(:Blues_4)
-@gp :- "set encoding utf8" raw"""set xtics ('-π' -pi, 'π/2' -pi/2, 0, 'π/2' pi/2, 'π' pi)"""
+@gp :- "set encoding utf8" raw"""set xtics ('-π' -pi, '-π/2' -pi/2, 0, 'π/2' pi/2, 'π' pi)"""
-@gp :- xr=3.8.*[-1, 1] yr=[-1.5,1.5] "set grid"
+@gp :- xr=3.8.*[-1, 1] yr=[-1.5,1.5] "set grid front"
 @gp :- x sin.(x) approx .+=  x          "w filledcurve t 'n=0' lt 1"
 @gp :- x sin.(x) approx .+= -x.^3/6     "w filledcurve t 'n=1' lt 2"
 @gp :- x sin.(x) approx .+=  x.^5/120   "w filledcurve t 'n=2' lt 3"
@@ -64,7 +73,7 @@ y = randn(10_000)
 h = hist(x, y, bs1=0.25, nbins2=20)
 @gp "set multiplot layout 1,2"
 @gp :- 1 key="outside top center box horizontal" "set size ratio -1" h
-clines = contourlines(h.bins1, h.bins2, h.counts, cntrparam="levels discrete 10, 30, 60, 90");
+clines = contourlines(h, "levels discrete 10, 30, 60, 90");
 for i in 1:length(clines)
     @gp :- clines[i].data "w l t '$(clines[i].z)' lw $i lc rgb 'gray'" :-
 end

docs/make.jl

@@ -1,4 +1,5 @@
 using Documenter, Gnuplot
+empty!(Gnuplot.options.mime)
 
 makedocs(sitename="Gnuplot.jl",
          authors = "Giorgio Calderone",
@@ -9,8 +10,10 @@ makedocs(sitename="Gnuplot.jl",
              "Installation" => "install.md",
              "Basic usage" => "basic.md",
              "Advanced usage" => "advanced.md",
+             "Package options" => "options.md",
              "Style guide" => "style.md",
              "Gnuplot terminals" => "terminals.md",
+             "Plot recipes" => "recipes.md",
              "Examples" => "examples.md",
              "API" => "api.md"
          ])

docs/src/advanced.md

@@ -1,17 +1,17 @@
-# 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")
+
+Gnuplot.options.term = "unknown"
 empty!(Gnuplot.options.init)
-gpexec("set term unknown")
+push!( Gnuplot.options.init, linetypes(:Set1_5, lw=1.5, ps=1.5))
+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
 
@@ -27,9 +27,9 @@ 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'"
-saveas("ex010") # hide
+saveas("advanced010") # hide
 ```
-![](assets/ex010.png)
+![](assets/advanced010.png)
 
 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.
 
@@ -50,32 +50,36 @@ name = "\$MyDataSet1"
 
 The parameter best fit values can be retrieved as follows:
 ```@example abc
+vars = gpvars();
 @info("Best fit values:",
-a = gpexec("print a"),
+  a = vars.a,
-b = gpexec("print b"),
+  b = vars.b,
-c = gpexec("print c"))
+  c = vars.c)
 ```
 
-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 with the previous example we can plot both data and best fit model (in plot `1`) and residuals (in plot `2`):
+Recycling data from the previous example we can plot both data and best fit model (in plot `1`) and residuals (in plot `2`):
 ```@example abc
+@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"
 @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}]'"
 @gp :-   [extrema(x)...] [0,0] "w l notit dt 2 lc rgb 'black'" # reference line
-saveas("ex011") # hide
+saveas("advanced011") # hide
 ```
-![](assets/ex011.png)
+![](assets/advanced011.png)
 
 Note that the order of the plots is not relevant, i.e. we would get the same results with:
 ```julia
+@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"
 @gp :- 2 "p $name u 1:((f(\$1)-\$2) / \$3):(1) w errorbars t 'Resid. [{/Symbol s}]'"
 @gp :-   [extrema(x)...] [0,0] "w l notit dt 2 lc rgb 'black'" # reference line
@@ -83,6 +87,52 @@ Note that the order of the plots is not relevant, i.e. we would get the same res
 @gp :-   "p $name u 1:(f(\$1)) w l t 'Best fit model'"
 ```
 
+## Customized layout
+
+It is also possible to customize the plot layout using the margin keywords (see [Histograms](@ref) for further info on how to generate andi display histograms):
+```@example abc
+# Generate random numbers
+x = randn(1000);
+y = randn(1000);
+
+# Overall plot margins (normalized in the range 0:1)
+margins = (l=0.08, r=0.98, b=0.13, t=0.98)
+
+# Right and top margins of main plot
+right, top = 0.8, 0.75
+
+# Gap between main plot and histograms
+gap  = 0.015
+
+# Main plot
+@gp "set multiplot"
+@gp :- 1 ma=margins rma=right tma=top :-
+@gp :-   x y "w p notit" xlab="X" ylab="Y"
+xr = gpranges().x  # save current X range
+yr = gpranges().y  # save current Y range
+
+# Histogram on X
+h = hist(x, nbins=10)
+@gp :- 2 ma=margins bma=top+gap rma=right :-
+@gp :-   "set xtics format ''" "set ytics format ''"  xlab="" ylab="" :-
+bs = fill(h.binsize, length(h.bins));
+@gp :-   xr=xr h.bins h.counts./2 bs./2 h.counts./2 "w boxxy notit fs solid 0.4" :-
+
+# Histogram on Y
+h = hist(y, nbins=10)
+@gp :- 3 ma=margins lma=right+gap tma=top :-
+@gp :-     "unset xrange" :-
+bs = fill(h.binsize, length(h.bins));
+@gp :-   yr=yr h.counts./2 h.bins h.counts./2 bs./2 "w boxxy notit fs solid 0.4" :-
+@gp
+saveas("advanced011b") # hide
+```
+![](assets/advanced011b.png)
+
+
+
+
+
 ### Mixing 2D and 3D plots
 A multiplot can also mix 2D and 3D plots:
 
@@ -97,9 +147,9 @@ x = y = -10:0.33:10
 sinc2d(x,y) = sin.(sqrt.(x.^2 + y.^2))./sqrt.(x.^2+y.^2)
 fxy = [sinc2d(x,y) for x in x, y in y]
 @gsp :- 2 x y fxy "w pm3d notit"
-saveas("ex012") # hide
+saveas("advanced012") # hide
 ```
-![](assets/ex012.png)
+![](assets/advanced012.png)
 
 
 ## Multiple sessions
@@ -112,7 +162,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
@@ -128,69 +178,145 @@ 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
-**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 and display histograms, e.g.:
 ```@example abc
 x = randn(1000);
 @gp hist(x)
-saveas("ex013a") # hide
+saveas("advanced013a") # hide
 ```
-![](assets/ex013a.png)
+![](assets/advanced013a.png)
 
-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.
+The [`hist()`](@ref) 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`](@ref)) structure, e.g.:
-
-Moreover, 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)
 @gp h.bins h.counts "w histep t 'Data' lc rgb 'red'"
-saveas("ex013b") # hide
+saveas("advanced013b") # hide
 ```
-![](assets/ex013b.png)
+![](assets/advanced013b.png)
 
-
+The [`hist()`](@ref) function compute also 2D histograms by passing two vectors (with the same lengths), e.g.:
-**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(10_000)
 y = randn(10_000)
-@gp "set size ratio -1" hist(x, y)
+h = hist(x, y)
-saveas("ex014a") # hide
+@gp h
+saveas("advanced014a") # hide
 ```
-![](assets/ex014a.png)
+![](assets/advanced014a.png)
 
 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
+x = randn(10_000)
+y = randn(10_000)
 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
+saveas("advanced014b") # hide
 ```
-![](assets/ex014b.png)
+![](assets/advanced014b.png)
 
 
-Alternatively, 2D histograms may be displayed using the `boxxyerror` plot style which allows more flexibility in, e.g., handling transparencies and drawing the histogram grid.  In this case the data can be prepared using the [`boxxyerror()`](@ref) function, as follows:
+Alternatively, 2D histograms may be displayed using the `boxxyerror` plot style which allows more flexibility in, e.g., handling transparencies and drawing the histogram grid.  In this case the data can be prepared using the [`boxxy()`](@ref) function, as follows:
 ```@example abc
-box = boxxyerror(h.bins1, h.bins2, cartesian=true)
 @gp "set size ratio -1" "set style fill solid 0.5 border lc rgb 'gray'" :-
-@gp :- box... h.counts "w boxxyerror notit lc pal"
+@gp :- boxxy(h) "w boxxy notit lc pal"
-saveas("ex014c") # hide
+saveas("advanced014c") # hide
 ```
-![](assets/ex014c.png)
+![](assets/advanced014c.png)
+
 
 
 ## 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 with the previous example:
+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 preview such lines with:
 ```@example abc
-clines = contourlines(h.bins1, h.bins2, h.counts, cntrparam="levels discrete 10, 30, 60, 90");
+x = randn(10_000)
+y = randn(10_000)
+h = hist(x, y)
+clines = contourlines(h, "levels discrete 10, 30, 60, 90");
+@gp clines
+saveas("advanced014d") # hide
+```
+![](assets/advanced014d.png)
+
+By exploiting the fields of the [`Gnuplot.IsoContourLines`](@ref) structure we may also customize line widths, colors and dashed pattern according to their z level, and plot them on top of the 2D histogram:
+
+```@example abc
+@gp "set size ratio -1" "set style fill solid 0.5 border lc rgb 'gray'" :-
+@gp :- boxxy(h) "w boxxy notit lc pal"
 for i in 1:length(clines)
-    @gp :- clines[i].data "w l t '$(clines[i].z)' lw $i lc pal" :-
+    @gp :- clines[i].data "w l t '$(clines[i].z)' lw $i dt $i lc pal" :-
 end
 @gp :- key="outside top center box horizontal"
-saveas("ex014d") # hide
+saveas("advanced014e") # hide
 ```
-![](assets/ex014d.png)
+![](assets/advanced014e.png)
+
+
+The [`contourlines()`](@ref) function also allows to calculate the contour lines encompassing a given fraction of the total counts of a 2D histogram.  E.g. to plot the contours corresponding to 1, 2, and 3 $\sigma$ of a 2D Gaussian distribution:
+```@example abc
+x = randn(10^5);
+y = randn(10^5);
+h = hist(x, y, nbins1=20, nbins2=20);
+
+# Calculate probability within 0 < r < σ
+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
+saveas("advanced014f") # hide
+```
+![](assets/advanced014f.png)
+
+
+## Interpolation of 2D scattered data
+The `dgrid3d()` function allows to interpolate 2D scattered data onto a 2D regular grid, e.g.:
+```@example abc
+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"
+saveas("advanced015a") # hide
+```
+![](assets/advanced015a.png)
+
+
+!!! 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`:
+
+```@example abc
+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"
+save(term="pngcairo size 1000,400 fontscale 1.0", output="assets/advanced015b.png")  # hide
+```
+![](assets/advanced015b.png)
+
 
 
 ## Animations
@@ -218,63 +344,31 @@ 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:
+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., to retrieve the value of a gnuplot variable:
-```@repl abc
-gpexec("set term wxt");
-```
-The gnuplot process replies are returned as a string, e.g.:
 ```@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.
 
+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:
-```@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.
 
 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](@ref) 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`](@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`;
-
-- `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:
-```@repl abc
-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](@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
-gpexec("set term wxt")  #hide
-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")
-```
-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;
-
-- `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.

docs/src/api.md

@@ -10,14 +10,20 @@ The list of **Gnuplot.jl** exported symbols is as follows:
 ```@docs
 @gp
 @gsp
-boxxyerror
+boxxy
 contourlines
 dataset_names
+dgrid3d
 gpexec
+gpmargins
+gpranges
+gpvars
 hist
 linetypes
 palette
+palette_levels
 palette_names
+recipe
 save
 session_names
 stats
@@ -33,13 +39,19 @@ The following functions are not exported by the **Gnuplot.jl** package since the
 In order to call these functions you should add the `Gnuplot.` prefix to the function name.
 
 ```@docs
+Gnuplot.Dataset
+Gnuplot.DatasetEmpty
+Gnuplot.DatasetText
+Gnuplot.DatasetBin
 Gnuplot.Histogram1D
 Gnuplot.Histogram2D
 Gnuplot.IsoContourLines
 Gnuplot.Options
 Gnuplot.Path2d
+Gnuplot.PlotElement
 Gnuplot.gpversion
 Gnuplot.quit
 Gnuplot.quitall
+Gnuplot.repl_init
 Gnuplot.version
 ```

docs/src/basic.md

@@ -3,9 +3,10 @@ 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")
+Gnuplot.options.term = "unknown"
 empty!(Gnuplot.options.init)
-gpexec("set term unknown")
+push!( Gnuplot.options.init, linetypes(:Set1_5, lw=1.5, ps=1.5))
+saveas(file) = save(term="pngcairo size 550,350 fontscale 0.8", output="assets/$(file).png")
 ```
 
 # Basic usage
@@ -14,13 +15,16 @@ The main purpose of the **Gnuplot.jl** package is to send data and commands to t
 
 The most important symbols exported by the package are the [`@gp`](@ref) (for 2D plots) and [`@gsp`](@ref) (for 3D plots) macros.  The simplemost example is as follows:
 ```@example abc
+using Gnuplot
 @gp 1:20
-saveas("ex000") # hide
+saveas("basic000") # hide
 ```
-![](assets/ex000.png)
+![](assets/basic000.png)
+
+The plots are displayed either in an interactive window (if running in the Julia REPL), as an inline image (if running in Jupyter) or in the plot pane (if running in Juno).  See [Display options](@ref) for further informations.
 
 
-Both macros accept any number of arguments, whose meaning is interpreted as follows:
+Both the [`@gp`](@ref) and [`@gsp`](@ref) macros accept any number of arguments, whose meaning is interpreted as follows:
 
 - one, or a group of consecutive, array(s) build up a dataset.  The different arrays are accessible as columns 1, 2, etc. from the gnuplot process.  The number of required input arrays depends on the chosen plot style (see gnuplot documentation);
 
@@ -53,17 +57,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`.
@@ -74,9 +78,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.
 
@@ -86,9 +90,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)
 
 
 ---
@@ -96,9 +100,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.
@@ -109,9 +113,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.
@@ -132,6 +136,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.
 
@@ -148,39 +157,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, 8, 5)
-img[10,:] .= -5
+img[2,:] .= -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.
 
-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 a matrix is displayed in the REPL:
 ```@example abc
-using TestImages
+img = reshape(1:15, 5, 3)
-img = testimage("lighthouse");
-@gp "set size square" "set autoscale fix" img "rotate=-90deg with rgbimage notit"
-saveas("ex007b") # hide
 ```
-![](assets/ex007b.png)
+and its image representation, which is essentially upside down (since the Y coordinates increase upwards):
-
-
-To display a gray image use `with image` in place of `with rgbimage`, e.g.:
 ```@example abc
-img = testimage("walkbridge");
+@gp img "w image notit"
-@gp palette(:viridis) "set size square" "set autoscale fix" img "rotate=-0.5pi with image notit"
+saveas("basic007b") # hide
-saveas("ex007c") # hide
 ```
-![](assets/ex007c.png)
+![](assets/basic007b.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`).
 
+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)
@@ -189,10 +190,10 @@ Note that we used a custom palette (`:lapaz`, see [Palettes and line types](@ref
 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"
+@gsp cbr=[-1,1].*30  x  x.*sin.(x)  x.*cos.(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.
 
@@ -204,22 +205,20 @@ A gnuplot-compliant palette can be retrieved with [`palette()`](@ref), and used
 ```@example abc
 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"
+@gsp :-  x  x.*sin.(x)  x.*cos.(x)  x./20  "w p pt 7 ps var lc pal"
-saveas("ex008a") # hide
+saveas("basic008a") # hide
 ```
-![](assets/ex008a.png)
+![](assets/basic008a.png)
 
-
+The palette levels may be easily stretched by using the [`palette_levels()`](@ref) and modifying the numeric levels, e.g.:
-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.
 ```@example abc
-@gp linetypes(:deepsea)
+x = 0:0.1:10pi
-x = 1:0.1:4pi
+v, l, n = palette_levels(:viridis)
-for i in 1:5
+@gsp palette(v.^0.25, l, n) cbr=[-1,1].*30 :-
-    @gp :- x i.* sin.(x) "w l notit lw 5"
+@gsp :-  x  x.*sin.(x)  x.*cos.(x)  x./20  "w p pt 7 ps var lc pal"
-end
+saveas("basic008b") # hide
-saveas("ex009") # hide
 ```
-![](assets/ex009.png)
+![](assets/basic008b.png)
 
 The list of all available palette can be retrieved with [`palette_names()`](@ref):
 ```@repl abc
@@ -227,9 +226,38 @@ 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 key="left" linetypes(:Set1_5, lw=2)
+for i in 1:10
+    @gp :- i .* (0:10) "w lp t '$i'"
+end
+saveas("basic009a") # hide
+```
+![](assets/basic009a.png)
+
+
+```@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=1.5, ps=1.5))
+```
+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()
 ```
@@ -237,13 +265,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 +285,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,24 +311,25 @@ set output
 ```
 
 While the following:
-```julia
+```@example abc
-img = testimage("lighthouse");
+img = randn(100, 300);
-@gp "set size square" "set autoscale fix" img "rotate=-90deg with rgbimage notit"
+@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
 ```
 
 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.
 

docs/src/index.md

@@ -1,5 +1,7 @@
 # Gnuplot.jl
 ## A Julia interface to gnuplot.
+[![Stars](https://img.shields.io/github/stars/gcalderone/Gnuplot.jl?style=social)](https://github.com/gcalderone/Gnuplot.jl)
+
 
 The **Gnuplot.jl** package allows easy and fast use of [gnuplot](http://gnuplot.info/) as a data visualization tool in Julia.  Have a look at [Basic usage](@ref) and [Examples](@ref) for a quick overview.  The package main features are:
 
@@ -19,11 +21,16 @@ The **Gnuplot.jl** package allows easy and fast use of [gnuplot](http://gnuplot.
 
 - enhanced support for contour plots;
 
+- 2D interpolation of scattered data on a regular grid;
+
 - export to a huge number of formats such as `pdf`, `png`, `gif`, ``\LaTeX``, `svg`, etc. (actually all those supported by gnuplot);
 
+- compatibility with Jupyter and Juno;
+
 - save sessions into gnuplot scripts, to enable easy plot customization and reproducibility.
 
 If you're unfamiliar with gnuplot have a look at:
+
 - [Main gnuplot site](http://gnuplot.info/)
 - [gnuplot FAQ](http://gnuplot.info/faq/index.html)
 
@@ -33,6 +40,7 @@ If you're unfamiliar with gnuplot have a look at:
 A powerful plotting framework is among the most important tool in the toolbox of any modern scientist and engineer.  As such, it is hard to find a single package to fit all needs, and many solutions are indeed available in the Julia [ecosystem](https://github.com/JuliaPlots).
 
 **Gnuplot.jl** package fills the niche of users who needs:
+
 1. publication-quality plots, by exploiting the capabilities of a widely used tool such as gnuplot, and its many output formats available;
 1. a well-documented framework, by taking advantage of all the gnuplot documentation, tutorials and examples available on the web;
 1. a fast response, by relying on an external program (rather than on a large Julia code base);
@@ -46,13 +54,18 @@ The **Gnuplot.jl** package development follows a minimalistic approach: it is es
 The functionalities 1, 2 and 3 listed above are similar to those provided by the [Gaston](https://github.com/mbaz/Gaston.jl) package.  **Gnuplot.jl** also provides features 4 and 5, as well as the minimalistic approach.
 
 
-## Do Gnuplot.jl suits my needs?
+## Does Gnuplot.jl suit my needs?
 
-Any modern plotting package is able to produce a simple scatter plot, with custom symbols, line styles, colors and axis labels.  Indeed, this is exactly the example that is reported in every package documentation (also here: see [2D plots](@ref plots2d)). Still, producing complex and publication-quality plots is not an easy task.  As a consequence is also not easy to determine whether a package can cope with the most difficult cases (unless you actually try it out) and a reasonable choice is typically to rely on the size of the user base, the availability of documentation / tutorials, and the possibility to preview complex examples.
+Any modern plotting framework is able to produce a simple scatter plot, with custom symbols, line styles, colors and axis labels.  Indeed, this is exactly the example that is reported in every package documentation (also here: see [2D plots](@ref plots2d)). Still, producing complex and publication-quality plots is not an easy task.  As a consequence is also hard to tell whether a package can cope with the most difficult cases, unless you actually try it out.  A reasonable choice, then, is to rely on the size of the user base, the availability of documentation / tutorials, and the possibility to preview complex examples.
 
-**Gnuplot.jl** aims to be ready for even the most challenging plots by relying on the widely used gnuplot application, and by allowing each native feature (both present and future ones) to be immediately available in the Julia language.  Moreover, **Gnuplot.jl** provides a unique syntax specifically aimed to increase productivity while performing interactive data exploration.
+By allowing transparent access to the underlying gnuplot process, the **Gnuplot.jl** package immediately exposes all capabilities of the backend and allows to take advantage of the many resources available online.  The minimalistic approach allows to value the widely spread knowledge of gnuplot syntax, and ensures a shallow learning curve for the package.  Finally, its extremely concise syntax makes it ideal for interactive data exploration.
 
-Last but not least, have a look at the **Gnuplot.jl** [Examples](@ref) page.
+As a final remark, note that the **Gnuplot.jl** features directly maps onto the different stages of production of a plot:
+- syntax conciseness, interactivity, [Plot recipes](@ref) => preliminary data exploration;
+- access to all gnuplot capabilities, allowing to tweak even the smallest detail of a plot => plot preparation;
+- [Gnuplot scripts](@ref) => post-production.
+
+Before continuing, have a look at the [Examples](@ref) page!
 
 
 ## Notation
@@ -63,5 +76,5 @@ In this documentation:
 
 ## Table of Contents
 ```@contents
-Pages = ["index.md", "install.md", "basic.md", "advanced.md", "tips.md", "examples.md", "api.md"]
+Pages = ["index.md", "install.md", "basic.md", "advanced.md", "options.md", "style.md", "terminals.md", "recipes.md", "examples.md", "api.md"]
 ```

docs/src/install.md

@@ -10,14 +10,32 @@ In the Julia REPL type:
 ```julia-repl
 julia> ]add Gnuplot
 ```
-Then hit backspace key to return to Julia REPL.
+The `]` character starts the Julia [package manager](https://julialang.github.io/Pkg.jl/v1/getting-started.html#Basic-Usage-1). Hit backspace key to return to Julia prompt.
+
 
 ## Check installation
+
+Check **Gnuplot.jl** version with:
+```julia-repl
+julia> ]st Gnuplot
+Status `~/.julia/environments/v1.4/Project.toml`
+  [dc211083] Gnuplot v1.4.1
+```
+If the displayed version is not `v1.4.1` you are probably having a dependency conflict.  In this case try forcing installation of the latest version with:
+```julia-repl
+julia> ]add Gnuplot@1.4.1
+```
+and check which package is causing the conflict.
+
+
+
 Check execution and version of the underlying `gnuplot` process:
 ```@repl
 using Gnuplot
 Gnuplot.gpversion()
 ```
+The minimum required version is `v5.0`.
+
 
 Generate the first plot:
 ```julia-repl

docs/src/options.md

@@ -0,0 +1,114 @@
+```@setup abc
+using Gnuplot
+Gnuplot.quitall()
+mkpath("assets")
+
+Gnuplot.options.term = "unknown"
+empty!(Gnuplot.options.init)
+push!( Gnuplot.options.init, linetypes(:Set1_5, lw=1.5, ps=1.5))
+saveas(file) = save(term="pngcairo size 550,350 fontscale 0.8", output="assets/$(file).png")
+```
+
+# Display options
+
+The display behaviour of **Gnuplot.jl** depends on the value of the `Gnuplot.options.gpviewer` flag:
+
+- if `true` the plot is displayed in a gnuplot window, using one of the interactive terminals such as `wxt`, `qt` or `aqua`.  This is the default setting when running a Julia REPL session; The terminal options can be customized using `Gnuplot.options.term`;
+
+- if `false` the plot is displayed through the Julia [multimedia interface](https://docs.julialang.org/en/v1/base/io-network/#Multimedia-I/O-1), i.e. it is exported as either a `png`, `svg` or `html` file, and displayed in an external viewer.  This is the default setting when running a Jupyter, JupyterLab or Juno session.  The terminal options can be customized using the `Gnuplot.options.mime` dictionary.
+
+The `Gnuplot.options.gpviewer` flag is automatically set when the package is first loaded according to the runtime environment, however the user can change its value at any time to fit specific needs.  Further informations and examples for both options are available in this Jupyter [notebook](https://github.com/gcalderone/Gnuplot.jl/blob/gh-pages/v1.3.0/options/display.ipynb).
+
+
+
+
+# Package options and initialization
+
+## Options
+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 as [Dry sessions](@ref).  Default is `false`, but if the package is not able to start a gnuplot process it will automatically switch to `true`;
+
+- `cmd::String`: command to start the gnuplot process, default value is `"gnuplot"`.  Use this field to specify a custom path to the gnuplot executable;
+
+- `gpviewer::Bool`: use a gnuplot terminal as main plotting device (if `true`) or an external viewer (if `false`);
+
+- `term::String`: default terminal for interactive use (default is an empty string, i.e. use gnuplot settings).  A custom terminal can be set with, e.g.:
+```@repl abc
+Gnuplot.options.term = "wxt size 700,400";
+```
+
+- `mime::Dict{MIME, String}`: dictionary of MIME types and corresponding gnuplot terminals.  Used to export images with either [`save()`](@ref) or `show()` (see [Display options](@ref)).  Default values are:
+  - `MIME"application/pdf" => "pdfcairo enhanced"`
+  - `MIME"image/jpeg"      => "jpeg enhanced"`
+  - `MIME"image/png"       => "pngcairo enhanced"`
+  - `MIME"image/svg+xml"   => "svg enhanced mouse standalone dynamic background rgb 'white'"`
+  - `MIME"text/html"       => "svg enhanced mouse standalone dynamic"`
+  - `MIME"text/plain"      => "dumb enhanced ansi"`
+
+
+- `init::Vector{String}`: commands to initialize the session when it is created or reset.  It can be used to, e.g., set a custom linetypes or palette:
+```@repl abc
+push!(Gnuplot.options.init, linetypes(:Set1_5, lw=1.5, ps=1.5));
+```
+Note that this option affect all the sessions, and that all inserted commands are saved in [Gnuplot scripts](@ref);
+
+- `verbose::Bool`: a flag to set verbosity of the package.  If `true` all communication with the underlying process will be printed on stdout. E.g.:
+```@repl abc
+empty!(Gnuplot.options.init);                              # hide
+gpexec("set term wxt");                                    # hide
+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
+push!(Gnuplot.options.init, 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`;
+
+
+## Package initialization
+
+If you use **Gnuplot.jl** frequently you may find convenient to automatically apply the package settings ([Options](@ref)) whenever the package is loaded.  A possibility is to use [Requires.jl](https://github.com/JuliaPackaging/Requires.jl) and put the following code in the `~/.julia/config/startup.jl` initialization file (further info [here](https://docs.julialang.org/en/v1/stdlib/REPL/)):
+```julia
+using Requires
+@require Gnuplot="dc211083-a33a-5b79-959f-2ff34033469d" begin
+        @info "Custom Gnuplot initialization"
+        # Uncomment the following if you don't have the gnuplot
+        # executable installed on your platform:
+        #Gnuplot.options.dry = true;
+
+        # Set the proper path if the gnuplot executable is not
+        # available in your $PATH
+        #Gnuplot.options.cmd = "/path/to/gnuplot";
+
+        # Force a specific display behaviour (see documentation).  If
+        # not given explicit Gnuplot.jl will choose the best option
+        # according to your runtime environment.
+        #Gnuplot.options.gpviewer = true
+
+        # Set the default terminal for interacitve use
+        Gnuplot.options.term = "wxt size 700,400";
+
+        # Set the terminal options for the exported MIME types:
+        #Gnuplot.options.mime[MIME"image/png"] = "";
+        #Gnuplot.options.mime[MIME"image/svg+xml"] = "svg enhanced standalone dynamic";
+        #Gnuplot.options.mime[MIME"text/html"] = "svg enhanced standalone mouse dynamic";
+
+        # Set the terminal to plot in a terminal emulator:
+        # (try with `save(MIME"text/plain")`):
+        #Gnuplot.options.mime[MIME"text/plain"] = "sixelgd enhanced"; # requires vt340 emulation
+
+        # Set the default linetypes
+        empty!(Gnuplot.options.init);
+        push!(Gnuplot.options.init, Gnuplot.linetypes(:Set1_5, lw=1.5, ps=1.5));
+
+        # Initialize the gnuplot REPL using the provided `start_key`.
+        if Gnuplot.options.gpviewer;
+            Gnuplot.repl_init(start_key='>');
+        end;
+end
+```
+
+The above code will be automatically when you first load the package with `using Gnuplot`.

docs/src/recipes.md

@@ -0,0 +1,136 @@
+```@setup abc
+using Gnuplot
+Gnuplot.quitall()
+mkpath("assets")
+
+Gnuplot.options.term = "unknown"
+empty!(Gnuplot.options.init)
+push!( Gnuplot.options.init, linetypes(:Set1_5, lw=1.5, ps=1.5))
+saveas(file) = save(term="pngcairo size 550,350 fontscale 0.8", output="assets/$(file).png")
+```
+
+
+# Plot recipes
+
+A plot *recipe* is a quicklook visualization procedure aimed at reducing the amount of repetitive code to generate a plot.  More specifically, a recipe is a function that convert data from the "Julia world" into a form suitable to be ingested in **Gnuplot.jl**, namely a scalar (or a vector of) [`Gnuplot.PlotElement`](@ref) object(s).  The latter contain informations on how to create a plot, or a part of it, and can be used directly as arguments in a `@gp` or `@gsp` call.
+
+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 (e.g. to plot data from a `DataFrame` object, see [Explicit recipe (example)](@ref));
+
+- *implicit* recipe: a function which is automatically called by **Gnuplot.jl**.  It must extend the [`recipe()`](@ref) function, and accept exactly one mandatory argument.  It is typically used when the visualization is completely determined by the data type itself (e.g. the visualization of a `Matrix{ColorTypes.RGB}` object as an image, see [Image recipes](@ref));
+
+An implicit recipe is invoked whenever the data type of an argument to `@gp` or `@gsp` is not among the allowed ones (see [`@gp()`](@ref) documentation).  If a suitable recipe do not exists an error is raised.  On the other hand, an explicit recipe needs to be invoked by the user, and the output passed directly to `@gp` or `@gsp`.
+
+Although recipes provides very efficient tools for data exploration, their use typically hide the details of plot generation.  As a consequence they provide less flexibility than the approaches described in [Basic usage](@ref) and [Advanced usage](@ref).
+
+Currently, the **Gnuplot.jl** package provides no built-in explicit recipe.  The implicit recipes are implemented in [recipes.jl](https://github.com/gcalderone/Gnuplot.jl/blob/master/src/recipes.jl).
+
+
+
+## Explicit recipe (example)
+
+To generate a plot using the data contained in a `DataFrame` object we need, beside the data itself, the name of the columns to use for the X and Y coordinates.  The following example shows how to implement an explicit recipe to plot a `DataFrame` object:
+```@example abc
+using RDatasets, DataFrames, Gnuplot
+import Gnuplot: PlotElement, DatasetText
+
+function plotdf(df::DataFrame, colx::Symbol, coly::Symbol; group=nothing)
+    if isnothing(group)
+        return PlotElement(data=DatasetText(df[:, colx], df[:, coly]),
+                           plot="w p notit",
+                           xlab=string(colx), ylab=string(coly))
+    end
+
+    out = Vector{Gnuplot.PlotElement}()
+    push!(out, PlotElement(;xlab=string(colx), ylab=string(coly)))
+    for g in sort(unique(df[:, group]))
+        i = findall(df[:, group] .== g)
+        if length(i) > 0
+            push!(out, PlotElement(data=DatasetText(df[i, colx], df[i, coly]),
+                                   plot="w p t '$g'"))
+        end
+    end
+    return out
+end
+
+# Load a DataFrame and convert it to a PlotElement
+iris = dataset("datasets", "iris")
+@gp plotdf(iris, :SepalLength, :SepalWidth, group=:Species)
+saveas("recipes001") # hide
+```
+![](assets/recipes001.png)
+
+
+
+## Histogram recipes
+The object returned by the [`hist()`](@ref) function can be readily visualized by means of implicit recipes defined on the `Gnuplot.Histogram1D` and `Gnuplot.Histogram2D` types:
+
+```@example abc
+x = randn(1000);
+@gp hist(x)
+saveas("recipes002") # hide
+```
+![](assets/recipes002.png)
+
+
+```@example abc
+x = randn(10_000);
+y = randn(10_000);
+@gp hist(x, y)
+saveas("recipes002a") # hide
+```
+![](assets/recipes002a.png)
+
+
+## Contour lines recipes
+The object returned by the [`contourlines()`](@ref) function can be readily visualized by means of implicit recipes defined on the `Gnuplot.IsoContourLines` types:
+```@example abc
+x = randn(10_000);
+y = randn(10_000);
+h = hist(x, y)
+clines = contourlines(h, "levels discrete 10, 30, 60, 90");
+@gp clines
+saveas("recipes002b") # hide
+```
+![](assets/recipes002b.png)
+
+
+
+
+## Image recipes
+
+The **Gnuplot.jl** package provides implicit recipes to display images in the following formats:
+- `Matrix{ColorTypes.RGB{T}}`;
+- `Matrix{ColorTypes.RGBA{T}}`
+- `Matrix{ColorTypes.Gray{T}}`;
+- `Matrix{ColorTypes.GrayA{T}}`;
+
+To use these recipes simply pass an image to `@gp`, e.g.:
+```@example abc
+using TestImages
+img = testimage("lighthouse");
+@gp img
+saveas("recipes007b") # hide
+```
+![](assets/recipes007b.png)
+
+
+All such recipes are defined as:
+```julia
+function recipe(M::Matrix{ColorTypes.RGB{T}}, opt="flipy")
+  ...
+end
+```
+with only one mandatory argument.  In order to exploit the optional keyword we can explicitly invoke the recipe as follows:
+```@example abc
+img = testimage("walkbridge");
+@gp palette(:gray1) recipe(img, "flipy rot=15deg")
+saveas("recipes007c") # hide
+```
+![](assets/recipes007c.png)
+
+Note that we used both a palette (`:gray`, see [Palettes and line types](@ref)) and a custom rotation angle.
+
+
+The `flipy` option is necessary for proper visualization (see discussion in [Plot matrix as images](@ref)).

docs/src/style.md

@@ -1,6 +1,6 @@
 # Style Guide
 
-The **Gnuplot.jl** loose syntax allows to create a plot using very different approaches.  While this was one of the initial purposes for the package, it may lead to decreased code readability if not used judiciously.
+The **Gnuplot.jl** loose syntax allows to create a plot using very different approaches.  While this was one of the initial purposes for the package, it may lead to a reduced code readability if not used judiciously.
 
 Here I will summarize a few, non-mandatory, guidelines which allows to maintain a neat syntax and a high readability:
 

docs/src/terminals.md

@@ -2,13 +2,9 @@
 
 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.
 
-To use a specific terminal for interactive use you may either add it as initialization command for all new session with (see [Options](@ref)):
+To use a specific terminal for interactive use you may either set it as initialization command for all new session with (see [Options](@ref)):
 ```julia
-push!(Gnuplot.options.init, "set term wxt")
+Gnuplot.options.term = "wxt"
-```
-or directly send the command to a specific session (see [Direct command execution](@ref))
-```julia
-gpexec("set term wxt")
 ```
 See official [gnuplot documentation](http://gnuplot.sourceforge.net/documentation.html) for further info on terminals and their options.
 
@@ -16,13 +12,13 @@ See official [gnuplot documentation](http://gnuplot.sourceforge.net/documentatio
 ## Interactive terminals (`wxt` and `qt`)
 The multiplatform `wxt` and `qt` terminals are among the most widely used ones for their nicely looking outputs on display and for their interactive capabilities.
 
-You may set them as terminal with:
+You may use such terminals with:
 ```
-"set term wxt size 800,600"
+Gnuplot.options.term = "wxt size 800,600"
 ```
 or
 ```
-"set term qt  size 800,600"
+Gnuplot.options.term = "qt  size 800,600"
 ```
 (the `size 800,600` is optional and can be omitted).
 
@@ -30,13 +26,35 @@ Press the `h` key on the window to display an help message with all available ke
 
 
 ## Plot in a terminal application (`dumb`, `sixel` and `sixelgd`)
-Gnuplot supports plotting in a terminal application, with no need for X11 or other GUI support, via the `dumb`, `sixel` and `sixelgd` terminals.  These are extremely useful when you run Julia on a remote shell through `ssh`, with no X11 forwarding.  You may set these terminals with one of the following command:
+Gnuplot supports plotting in a terminal application, with no need for X11 or other GUI support, via the `dumb`, `sixel` and `sixelgd` terminals.  These are extremely useful when you run Julia on a remote shell through `ssh`, with no X11 forwarding. The `dumb` terminal uses ASCII characters to draw a plot, while `sixel` and `sixelgd` actually use bitmaps (but require Sixel support to be enabled in the terminal, e.g. `xterm -ti vt340`).
+
+Dumb terminal can be used as follows:
+
+```jldoctest; setup = :(using Gnuplot)
+julia> origterm = Gnuplot.options.term;
+
+julia> Gnuplot.options.term = "dumb size 60,15";
+
+julia> @gp "plot sin(x)"
+
+    1 +-------------------------------------------------+
+  0.8 |-+         *+ *         + ** **      +    *  * +-|
+  0.6 |-+        *   **          *   *   sin(x) *******-|
+  0.4 |*+        *    *         *     *         *    *+-|
+  0.2 |*+       *      *        *     *        *      *-|
+    0 |*+       *      *       *       *       *      *-|
+      | *      *       *       *       *      *        *|
+ -0.2 |-*      *        *     *        *      *       +*|
+ -0.4 |-+*    *         *     *         *    *        +*|
+ -0.6 |-+*    *          *   *          **   *        +-|
+ -0.8 |-+ *  *     +     ** ** +         *  *         +-|
+   -1 +-------------------------------------------------+
+     -10          -5           0            5           10
+
+julia> Gnuplot.options.term = origterm;
+
 ```
-"set term dumb"
+A sixel plot on `xterm` looks as follows:
-"set term sixel"
-"set term sixelgd"
-```
-The `dumb` terminal uses ASCII characters to draw a plot, while `sixel` and `sixelgd` actually use bitmaps (but require Sixel support to be enabled in the terminal, e.g. `xterm -ti vt340`).  A sixel plot on `xterm` looks as follows:
 ![](assets/sixelgd.png)
 
 The above terminals are available if gnuplot has been compiled with the `--with-bitmap-terminals` option enabled and Libgd (only for `sixelgd`).
@@ -45,7 +63,7 @@ The above terminals are available if gnuplot has been compiled with the `--with-
 ## Export to image files
 
 Gnuplot provides dozens of terminals able to export on files.  Examples are:
-- `cairopng` to export PNG files;
+- `pngcairo` to export PNG files;
 - `pdfcairo` for PDF;
 - `jpeg` for JPG;
 - `gif` for GIF (see [Animations](@ref)).
@@ -62,7 +80,7 @@ Gnuplot is also able to export vector (i.e. non-raster) plots through the `svg`
 The `cairolatex` terminal allows to produce high quality plots by splitting the output into a PDF file (containing a rasterized image of a plot) and a `.tex` file (containing all the text as ``\LaTeX`` code).  The following example shows how to write plot tics and an equation in ``\LaTeX``:
 ```julia
 x = LinRange(-2pi, 2pi, 1000)
-@gp t="Polynomial approximation of sin(x)"  "set style fill transparent solid 0.6 noborder"
+@gp tit="Polynomial approximation of sin(x)"  "set style fill transparent solid 0.6 noborder"
 @gp :- raw"""set xtics ('$-\pi$' -pi, '$-\pi/2$' -pi/2, 0, '$\pi/2$' pi/2, '$\pi$' pi)"""
 @gp :- xr=3.8.*[-1, 1] yr=[-1.5,1.5] key="box opaque left horiz" linetypes(:Blues_3) "set grid front"
 latex = raw"""\begin{minipage}[c]{\textwidth}\begin{equation*}""" *
@@ -78,7 +96,7 @@ approx = fill(0., length(x));
 save(term="cairolatex pdf input color dashed size 5in,3.3in", output="test.tex")
 ```
 !!! warning
-    If you add a path in the `output=` keyword this will also be copied in the the `.tex` file.  I suggest to use just filenames, with no path, in order to avoid possible errors when compiling ``\LaTeX`` code.
+    If you add a path in the `output=` keyword this will also be copied in the the `.tex` file, and may generate errors when compiling ``\LaTeX`` code.  The simplest way to solve this problem is to use just filenames, with no paths.
 
 The two output files (`test.tex` and `test.pdf`) can then be included in a ``\LaTeX`` file as follows:
 ```latex

examples/hidden2.3.jl

@@ -32,10 +32,10 @@ for loop in 1:2
     x = [cos(u) + .5 * cos(u) * cos(v)      for u in U, v in V]
     y = [sin(u) + .5 * sin(u) * cos(v)      for u in U, v in V]
     z = [.5 * sin(v)                        for u in U, v in V]
-    @gsp :-  x y z "w pm3d"
+    @gsp :- x' y' z' "w pm3d"
 
     x = [1 + cos(u) + .5 * cos(u) * cos(v)  for u in U, v in V]
     y = [.5 * sin(v)                        for u in U, v in V]
     z = [sin(u) + .5 * sin(u) * cos(v)      for u in U, v in V]
-    @gsp :- x y z "w pm3d"
+    @gsp :- x' y' z' "w pm3d"
 end

src/recipes.jl

@@ -0,0 +1,73 @@
+# ╭───────────────────────────────────────────────────────────────────╮
+# │                       IMPLICIT RECIPES                            │
+# ╰───────────────────────────────────────────────────────────────────╯
+
+# --------------------------------------------------------------------
+# Histograms
+"""
+    recipe(h::Histogram1D)
+    recipe(h::Histogram2D)
+
+Implicit recipes to visualize 1D and 2D histograms.
+"""
+recipe(h::Histogram1D) =
+    PlotElement(cmds="set grid",
+                data=DatasetText(h.bins, h.counts),
+                plot="w histep notit lw 2 lc rgb 'black'")
+
+recipe(h::Histogram2D) =
+    PlotElement(cmds=["set autoscale fix"],
+                data=DatasetText(h.bins1, h.bins2, h.counts),
+                plot="w image notit")
+
+
+# --------------------------------------------------------------------
+# Contour lines
+"""
+    recipe(c::IsoContourLines)
+    recipe(v::Vector{IsoContourLines})
+
+Implicit recipes to visualize iso-contour lines.
+"""
+function recipe(c::IsoContourLines)
+    if isnan(c.prob)
+        return PlotElement(data=c.data, plot="w l t '$(c.z)'")
+    end
+    return PlotElement(data=c.data, plot="w l t '$(round(c.prob * 100, sigdigits=6))%'")
+end
+recipe(v::Vector{IsoContourLines}) = recipe.(v)
+
+
+# --------------------------------------------------------------------
+# Images
+"""
+    recipe(M::Matrix{ColorTypes.RGB{T}}, opt="flipy")
+    recipe(M::Matrix{ColorTypes.RGBA{T}}, opt="flipy")
+    recipe(M::Matrix{ColorTypes.Gray{T}}, opt="flipy")
+    recipe(M::Matrix{ColorTypes.GrayA{T}}, opt="flipy")
+
+Implicit recipes to show images.
+"""
+recipe(M::Matrix{ColorTypes.RGB{T}}, opt="flipy") where T =
+    PlotElement(cmds=["set autoscale fix", "set size ratio -1"],
+                data=DatasetBin(256 .* getfield.(M, :r),
+                                256 .* getfield.(M, :g),
+                                256 .* getfield.(M, :b)),
+                plot="$opt with rgbimage notit")
+
+recipe(M::Matrix{ColorTypes.RGBA{T}}, opt="flipy") where T =
+    PlotElement(cmds=["set autoscale fix", "set size ratio -1"],
+                data=DatasetBin(256 .* getfield.(M, :r),
+                                256 .* getfield.(M, :g),
+                                256 .* getfield.(M, :b)),
+                plot="$opt with rgbimage notit")
+
+recipe(M::Matrix{ColorTypes.Gray{T}}, opt="flipy") where T =
+    PlotElement(cmds=["set autoscale fix", "set size ratio -1"],
+                data=DatasetBin(256 .* getfield.(M, :val)),
+                plot="$opt with image notit")
+
+recipe(M::Matrix{ColorTypes.GrayA{T}}, opt="flipy") where T =
+    PlotElement(cmds=["set autoscale fix", "set size ratio -1"],
+                data=DatasetBin(256 .* getfield.(M, :val)),
+                plot="$opt with image notit")

test/runtests.jl

@@ -1,20 +1,15 @@
 using Test, Gnuplot
 try
-    @info "Gnuplot version: " * string(Gnuplot.gpversion())
+    @info "Gnuplot.jl version: " * string(Gnuplot.version())
+    @info "gnuplot    version: " * string(Gnuplot.gpversion())
 catch
     Gnuplot.options.dry = true
 end
-push!(Gnuplot.options.init, "set term unknown")
+Gnuplot.options.gpviewer = true
 
 x = [1, 2, 3]
 y = [4, 5, 6]
 
-s = Gnuplot.arrays2datablock(1)
-@test all(s .== [" 1"])
-
-s = Gnuplot.arrays2datablock(1, 2)
-@test all(s .== [" 1 2"])
-
 s = Gnuplot.arrays2datablock(x)
 @test all(s .== [" 1"   ,
                  " 2"   ,
@@ -94,15 +89,37 @@ s = Gnuplot.arrays2datablock(1:3, 1:3, ["One", "Two", "Three"])
 
 
 #-----------------------------------------------------------------
+dummy = palette_names()
 pal = palette(:deepsea)
 @test pal == "set palette defined (0.0 '#2B004D', 0.25 '#4E0F99', 0.5 '#3C54D4', 0.75 '#48A9F8', 1.0 '#C5ECFF')\nset palette maxcol 5\n"
-ls = linetypes(:deepsea)
+ls = linetypes(:Set1_5, lw=1.5, ps=2)
-@test ls == "set linetype 1 lc rgb '#2B004D\nset linetype 2 lc rgb '#4E0F99\nset linetype 3 lc rgb '#3C54D4\nset linetype 4 lc rgb '#48A9F8\nset linetype 5 lc rgb '#C5ECFF\nset linetype cycle 5\n"
+@test ls == "unset for [i=1:256] linetype i\nset linetype 1 lc rgb '#E41A1C' lw 1.5 dt solid pt 1 ps 2\nset linetype 2 lc rgb '#377EB8' lw 1.5 dt solid pt 2 ps 2\nset linetype 3 lc rgb '#4DAF4A' lw 1.5 dt solid pt 3 ps 2\nset linetype 4 lc rgb '#984EA3' lw 1.5 dt solid pt 4 ps 2\nset linetype 5 lc rgb '#FF7F00' lw 1.5 dt solid pt 5 ps 2\nset linetype cycle 5\n"
+
+dummy = terminals()
+# if "sixelgd" in terminals()
+#     Gnuplot.options.term = "sixelgd enhanced"
+# elseif "sixel" in terminals()
+#     Gnuplot.options.term = "sixel enhanced"
+# elseif "dumb" in terminals()
+#     Gnuplot.options.term = "dumb"
+# else
+#     Gnuplot.options.term = "unknown"
+# end
+# Gnuplot.quitall()
+
+# Force unknown on Travis CI
+Gnuplot.options.term = "unknown"
+
+@gp 1:9
+@info "using terminal: " terminal()
+#test_terminal("unknown")
 
 #-----------------------------------------------------------------
 # Test wth empty dataset
 @gp Float64[]
 @gsp Float64[]
+@gp Float64[] Float64[]
+@gsp Float64[] Float64[]
 
 
 #-----------------------------------------------------------------
@@ -121,9 +138,9 @@ Gnuplot.quitall()
 @gp "plot sin(x)" "pl cos(x)"
 @gp "plo sin(x)" "s cos(x)"
 
-@gp "plot sin(x)" :-
+@gp mar="0,1,0,1" "plot sin(x)"
-@gp :- "plot cos(x)"
+@gp :- mar=gpmargins() "plot cos(x)"
-
+@gp :- 0. 0.
 
 @gp "plot sin(x)" 2 xr=(-2pi,2pi) "pause 2" "plot cos(4*x)"
 
@@ -134,7 +151,7 @@ noise = err .* randn(length(x));
 
 h = hist(noise, nbins=10)
 @gp h.bins h.counts "w histeps"
-
+@gp h
 
 @gp x y
 @gp x y "w l"
@@ -181,9 +198,9 @@ name = "\$MyDataSet1"
 @gp :- :dry 2 xlab="X label" ylab="Residuals"                :-
 @gp :- :dry "plot $name u 1:((f(\$1)-\$2) / \$3):(1) w errorbars notit" :-
 @gp :- :dry
-save("test.gp")        # write on file test.gp
+save(:dry, "test.gp")        # write on file test.gp
 Gnuplot.quitall()
-gpexec("load 'test.gp'") # load file test.gp
+#gpexec("load 'test.gp'") # load file test.gp, commented to avoid errors in CI
 
 #-----------------------------------------------------------------
 @gp("""
@@ -247,4 +264,30 @@ gpexec("load 'test.gp'") # load file test.gp
 	"splot x7, v, (u<0.5) ? -1 : sinc(x7,v) notitle",
 	"splot x8, v, (u<0.5) ? -1 : sinc(x8,v) notitle",
 	"splot x9, v, (u<0.5) ? -1 : sinc(x9,v) notitle")
+
+
+
+x = randn(5000);
+y = randn(5000);
+h = hist(x, y, nbins1=20, nbins2=20);
+clines = contourlines(h, "levels discrete 15, 30, 45");
+@gp clines
+@gp "set size ratio -1"
+for i in 1:length(clines)
+    @gp :- clines[i].data "w l t '$(clines[i].z)' lw $i dt $i"
+end
+
+
+Gnuplot.options.verbose = true
+@gp randn(10^6) randn(10^6)
+@gp :- 0. 0.
+Gnuplot.quit(:default)
+
+Gnuplot.options.dry = true
+@gp hist(randn(1000))
+
+# Various hist() corner cases
+@gp hist([1,2,3], bs=2)
+@gp hist([1,1,1], bs=1)
+
 Gnuplot.quitall()