Docs updated

docs/make.jl

@@ -2,7 +2,7 @@ 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",

docs/src/advanced.md

@@ -89,7 +89,7 @@ Note that the order of the plots is not relevant, i.e. we would get the same res
 
 ## Customized layout
 
-It is also possible to customize the plot layout using the margin keywords (see [Histograms](@ref) for further info):
+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);
@@ -181,7 +181,15 @@ Gnuplot.quitall()
 ```
 
 ## Histograms
-**Gnuplot.jl** provides a facility to compute (see [`hist()`](@ref) function) an histogram.  It allows to set 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) and return a [`Gnuplot.Histogram1D`](@ref) structure, whose content can be visualized as follows:
+**Gnuplot.jl** provides facilities to compute and display histograms, e.g.:
+```@example abc
+x = randn(1000);
+@gp hist(x)
+saveas("advanced013a") # hide
+```
+![](assets/advanced013a.png)
+
+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.:
 ```@example abc
 x = randn(1000);
 h = hist(x, range=3 .* [-1,1], bs=0.5)
@@ -190,7 +198,17 @@ saveas("advanced013b") # hide
 ```
 ![](assets/advanced013b.png)
 
-**Gnuplot.jl** also allows to compute 2D histograms by passing two vectors (with the same lengths) to [`hist()`](@ref).  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:
+The [`hist()`](@ref) function compute also 2D histograms by passing two vectors (with the same lengths), e.g.: 
+```@example abc
+x = randn(10_000)
+y = randn(10_000)
+h = hist(x, y)
+@gp h
+saveas("advanced014a") # hide
+```
+![](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)
@@ -201,30 +219,41 @@ saveas("advanced014b") # hide
 ![](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("advanced014c") # hide
 ```
 ![](assets/advanced014c.png)
 
-See also [Histogram recipes](@ref) for a quicker way to preview histogram plots.
 
 
 ## 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)
-for i in 1:length(clines)
+y = randn(10_000)
-    @gp :- clines[i].data "w l t '$(clines[i].z)' lw $i lc pal" :-
+h = hist(x, y)
-end
+clines = contourlines(h, "levels discrete 10, 30, 60, 90");
-@gp :- key="outside top center box horizontal"
+@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 dt $i lc pal" :-
+end
+@gp :- key="outside top center box horizontal"
+saveas("advanced014e") # hide
+```
+![](assets/advanced014e.png)
+
 
 ## Animations
 

docs/src/api.md

@@ -10,7 +10,7 @@ The list of **Gnuplot.jl** exported symbols is as follows:
 ```@docs
 @gp
 @gsp
-boxxyerror
+boxxy
 contourlines
 dataset_names
 gpexec

docs/src/basic.md

@@ -161,20 +161,20 @@ where `NaN` in the `xrange` keyword means using axis autoscaling.
 
 **Gnuplot.jl** can display a 2D matrix as an image:
 ```@example abc
-img = randn(Float64, 10, 5)
+img = randn(Float64, 8, 5)
-img[10,:] .= -5
+img[2,:] .= -5
 @gp img "w image notit"
 saveas("basic007a") # hide
 ```
 ![](assets/basic007a.png)
 
-Note that the first index in the `img` matrix corresponds to the rows in the displayed image coordinate when the image is displayed.
+Note that the first index in the `img` matrix corresponds to the rows in the displayed image.
 
 A simple way to remember the convention is to compare how a matrix is displayed in the REPL:
 ```@example abc
 img = reshape(1:15, 5, 3)
 ```
-and its image representation, which is essentially upside down:
+and its image representation, which is essentially upside down (since the Y coordinates increase upwards):
 ```@example abc
 @gp img "w image notit"
 saveas("basic007b") # hide
@@ -190,7 +190,7 @@ Also note that the `img[1,1]` pixel is shown at coordinates x=0, y=0.  See [Imag
 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("basic008") # hide
 ```
 ![](assets/basic008.png)
@@ -205,7 +205,7 @@ 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("basic008a") # hide
 ```
 ![](assets/basic008a.png)

docs/src/recipes.md

@@ -83,6 +83,19 @@ 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

src/Gnuplot.jl

@@ -10,7 +10,7 @@ import Base.show
 export session_names, dataset_names, palette_names, linetypes, palette,
     terminal, terminals, test_terminal,
     stats, @gp, @gsp, save, gpexec,
-    boxxyerror, contourlines, hist, recipe, gpvars, gpmargins, gpranges
+    boxxy, contourlines, hist, recipe, gpvars, gpmargins, gpranges
 
 
 # ╭───────────────────────────────────────────────────────────────────╮
@@ -1865,9 +1865,12 @@ end
 
 # --------------------------------------------------------------------
 """
-    boxxyerror(x, y; xmin=NaN, ymin=NaN, xmax=NaN, ymax=NaN, cartesian=false)
+    boxxy(x, y; xmin=NaN, ymin=NaN, xmax=NaN, ymax=NaN, cartesian=false)
+    boxxy(h::Histogram2D)
+
 """
-function boxxyerror(x, y; xmin=NaN, ymin=NaN, xmax=NaN, ymax=NaN, cartesian=false)
+boxxy(h::Histogram2D) = boxxy(h.bins1, h.bins2, h.counts, cartesian=true)
+function boxxy(x, y, aux...; xmin=NaN, ymin=NaN, xmax=NaN, ymax=NaN, cartesian=false)
     function box(v; vmin=NaN, vmax=NaN)
         vlow  = Vector{Float64}(undef, length(v))
         vhigh = Vector{Float64}(undef, length(v))
@@ -1889,11 +1892,11 @@ function boxxyerror(x, y; xmin=NaN, ymin=NaN, xmax=NaN, ymax=NaN, cartesian=fals
     xlow, xhigh = box(x, vmin=xmin, vmax=xmax)
     ylow, yhigh = box(y, vmin=ymin, vmax=ymax)
     if !cartesian
-        return (x, y, xlow, xhigh, ylow, yhigh)
+        return Dataset(x, y, xlow, xhigh, ylow, yhigh, aux...)
     end
     i = repeat(1:length(x), outer=length(y))
     j = repeat(1:length(y), inner=length(x))
-    return (x[i], y[j], xlow[i], xhigh[i], ylow[j], yhigh[j])
+    return Dataset([x[i], y[j], xlow[i], xhigh[i], ylow[j], yhigh[j], aux...])
 end
 
 

src/recipes.jl

@@ -16,13 +16,19 @@ recipe(h::Histogram1D) =
                 plot="w histep notit lw 2 lc rgb 'black'")
 
 recipe(h::Histogram2D) =
-    PlotElement(cmds=["set autoscale fix", "set size ratio -1"],
+    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.
+"""
 recipe(c::IsoContourLines) = PlotElement(data=c.data, plot="w l t '$(c.z)'")
 recipe(v::Vector{IsoContourLines}) = recipe.(v)