Rewrite Plot and axis-like types. (#67)

* Rewrite Plot and axis-like types. This is a step towards fixing #44 (almost there!). 1. New user-facing plot/plot3 constructor is ```julia Plot([incrementa], [options], data, trailing...) ``` and similarly for `Plot3`. `incremental` defaults to `false`, as this seems to be the most common use case. Some validation is done on `data` (checking for type). This removes the `label` kwarg, and allows us to close #16. Examples now recommend an explicit `\addlegendentry`. Docstrings are added for everything, and examples are rewritten accordingly. 2. Axis-like code cleaned up a bit with macros. Variations on log axes added. Explicitly document that strings are emitted as is. 3. GroupPlot rewritten, allow multiple plots and empty \nextgroupplot, two examples added, one from the manual and one for multiple plots. 4. Replaced random examples with deterministic ones, perhaps stick to this and close #63? Minor indentation issues fixed. 5. Minor fixes for testing framework. * Separate incremental plot constructors, add LegendEntry. The `incremental` flag was removed from `Plot*` constructors in the API, replaced by `PlotInc` and `Plot3Inc`. A LegendEntry type was added. Minor fixes: - remove the INCREMENTAL constant, as it is now unnecessary - clarify docstrings - disabled docstring checks, as they lead to infinite loops for some reason * Trivial docstring fix.
KristofferC · Feb 21, 2018 · 362f58d · 362f58d
1 parent f0589a7
commit 362f58d
Show file tree

Hide file tree

Showing 11 changed files with 380 additions and 196 deletions.
diff --git a/docs/make.jl b/docs/make.jl
@@ -8,6 +8,7 @@ makedocs(
     sitename = "PGFPlotsX.jl",
     doctest = true,
     strict = false,
+    checkdocs = :none,
     pages = Any[
         "Home" => "index.md",
         "Manual" => [
@@ -18,6 +19,7 @@ makedocs(
         "Examples" => [
             "examples/coordinates.md",
             "examples/tables.md",
+            "examples/axislike.md",
             "examples/gallery.md",
             "examples/juliatypes.md"
         ]

diff --git a/docs/src/examples/axislike.md b/docs/src/examples/axislike.md
@@ -0,0 +1,37 @@
+# Axis-like objects
+
+```@setup pgf
+using PGFPlotsX
+savefigs = (figname, obj) -> begin
+    PGFPlotsX.save(figname * ".pdf", obj)
+    run(`pdf2svg $(figname * ".pdf") $(figname * ".svg")`)
+    PGFPlotsX.save(figname * ".tex", obj);
+    return nothing
+end
+```
+------------------------
+
+```@example pgf
+x = linspace(0, 2*pi, 100)
+@pgf GroupPlot(
+    {
+        group_style =
+        {
+            group_size="2 by 1",
+            xticklabels_at="edge bottom",
+            yticklabels_at="edge left"
+        },
+        no_markers
+    },
+    {},
+    PlotInc(Table(x, sin.(x))),
+    PlotInc(Table(x, sin.(x .+ 0.5))),
+    {},
+    PlotInc(Table(x, cos.(x))),
+    PlotInc(Table(x, cos.(x .+ 0.5))))
+savefigs("groupplot-multiple", ans) # hide
+```
+
+[\[.pdf\]](groupplot-multiple.pdf), [\[generated .tex\]](groupplot-multiple.tex)
+
+![](groupplot-multiple.svg)
diff --git a/docs/src/examples/coordinates.md b/docs/src/examples/coordinates.md
@@ -81,8 +81,7 @@ f(x, y) = (1 - x)^2 + 100*(y - x^2)^2
     {
         surf,
     },
-    Coordinates(x, y, f.(x, y'));
-    incremental = false
+    Coordinates(x, y, f.(x, y'))
 )
 savefigs("coordinates-3d-matrix", ans) # hide
 ```
@@ -105,8 +104,7 @@ y = linspace(-0.5, 3, 50)
             surf,
             shader = "flat",
         },
-        Coordinates(x, y, @. √(f(x, y')));
-        incremental = false
+        Coordinates(x, y, @. √(f(x, y')))
     )
 )
 savefigs("coordinates-3d-matrix-heatmap", ans) # hide

diff --git a/docs/src/examples/gallery.md b/docs/src/examples/gallery.md
@@ -77,8 +77,9 @@ savefigs("simple-expression", ans) # hide
         grid = "major",
     },
     [
-        Plot(Expression("-x^5 - 242"); label = "model")
-        Plot(Coordinates(
+        PlotInc(Expression("-x^5 - 242")),
+        LegendEntry("model"),
+        PlotInc(Coordinates(
             [
                 (-4.77778,2027.60977),
                 (-3.55556,347.84069),
@@ -89,8 +90,9 @@ savefigs("simple-expression", ans) # hide
                 (2.55556,-341.40638),
                 (3.77778,-1169.24780),
                 (5.00000,-3269.56775),
-            ];
-        ); label = "estimate")
+            ]
+        )),
+        LegendEntry("estimate")
     ]
 )
 savefigs("cost-gain", ans) # hide
@@ -305,3 +307,37 @@ savefigs("mesh-scatter", ans) # hide
 
 ![](mesh-scatter.svg)
 
+------------------------
+
+```@example pgf
+# this is an imitation of the figure in the manual, as we generate the data
+x = linspace(0, 10, 100)
+@pgf plot = Plot({very_thick}, Table(x = x, y = @. (sin(x * 8) + 1) * 4 * x))
+@pgf GroupPlot(
+    {
+        group_style =
+        {
+            group_size="2 by 2",
+            horizontal_sep="0pt",
+            vertical_sep="0pt",
+            xticklabels_at="edge bottom"
+        },
+        xmin = 0,
+        ymin = 0,
+        height = "3.7cm",
+        width = "4cm",
+        no_markers
+    },
+    nothing,
+    {xmin=5, xmax=10, ymin=50, ymax=100},
+    plot,
+    {xmax=5, ymax=50},
+    plot,
+    {xmin=5, xmax=10, ymax=50, yticklabels={}},
+    plot)
+savefigs("groupplot-nested", ans) # hide
+```
+
+[\[.pdf\]](groupplot-nested.pdf), [\[generated .tex\]](groupplot-nested.tex)
+
+![](groupplot-nested.svg)
diff --git a/docs/src/examples/juliatypes.md b/docs/src/examples/juliatypes.md
@@ -24,13 +24,14 @@ using Colors
 axis = Axis()
 @pgf for (i, col) in enumerate(distinguishable_colors(10))
     offset = i * 50
-    p = Plot(Expression("exp(-(x-$μ)^2 / (2 * $σ^2)) / ($σ * sqrt(2*pi)) + $offset"),
-    {
-        color = col,
-        domain = "-3*$σ:3*$σ",
-        style = { ultra_thick },
-        samples = 50
-    }; incremental = false)
+    p = Plot(
+        {
+            color = col,
+            domain = "-3*$σ:3*$σ",
+            style = { ultra_thick },
+            samples = 50
+        },
+        Expression("exp(-(x-$μ)^2 / (2 * $σ^2)) / ($σ * sqrt(2*pi)) + $offset"))
     push!(axis, p)
 end
 axis
@@ -45,15 +46,13 @@ Using a colormap
 
 ```@example pgf
 using Colors
-@pgf begin
-p = Plot3(
-    Expression("cos(deg(x)) * sin(deg(y))"),
+p = @pgf Plot3(
     {
         surf,
         point_meta = "y",
         samples = 13
-    };
-    incremental = false
+    },
+    Expression("cos(deg(x)) * sin(deg(y))")
 )
 colormaps = ["Blues", "Greens", "Oranges", "Purples"]
 td = TikzDocument()
@@ -63,13 +62,11 @@ end
 
 tp = TikzPicture("scale" => 0.5)
 push!(td, tp)
-gp = GroupPlot({ group_style = {group_size = "2 by 2"}})
+gp = @pgf GroupPlot({ group_style = {group_size = "2 by 2"}})
 push!(tp, gp)
 
 for cmap in colormaps
-    push!(gp, p, { colormap_name = cmap })
-end
-
+    @pgf push!(gp, { colormap_name = cmap }, p)
 end
 savefigs("colormap", td) # hide
 ```
@@ -108,12 +105,13 @@ df = dataset("datasets", "iris") # load the dataset
             {
                 x = "SepalLength",
                 y = "SepalWidth",
-                meta = "Species" },
+                meta = "Species"
+            },
             df, # <--- Creating a Table from a DataFrame
         )
     ),
-    Legend(["Setosa", "Versicolor", "Virginica"])
-    ]
+     Legend(["Setosa", "Versicolor", "Virginica"])
+     ]
 )
 savefigs("dataframes", ans) # hide
 ```
@@ -133,11 +131,10 @@ x = 0.0:0.1:2π
 y = 0.0:0.1:2π
 f = (x,y) -> sin(x)*sin(y)
 @pgf Plot({
-                      contour_prepared,
-                      very_thick
-                  },
-                  Table(contours(x, y, f.(x, y'), 6));
-                  incremental = false)
+        contour_prepared,
+        very_thick
+    },
+    Table(contours(x, y, f.(x, y'), 6)))
 savefigs("contour", ans) # hide
 ```
 
@@ -151,17 +148,18 @@ savefigs("contour", ans) # hide
 
 ```@example pgf
 using StatsBase: Histogram, fit
-Axis(Plot(Table(fit(Histogram, randn(100), closed = :left));
-                  incremental = false),
-         @pgf {
-             "ybar interval",
-             "xticklabel interval boundaries",
-             xticklabel = raw"$[\pgfmathprintnumber\tick,\pgfmathprintnumber\nexttick)$",
-             "xticklabel style" =
-             {
-                 font = raw"\tiny"
-             }
-         })
+@pgf Axis(
+    {
+        "ybar interval",
+        "xticklabel interval boundaries",
+        xmajorgrids = false,
+        xticklabel = raw"$[\pgfmathprintnumber\tick,\pgfmathprintnumber\nexttick)$",
+        "xticklabel style" =
+        {
+            font = raw"\tiny"
+        },
+    },
+    Plot(Table(fit(Histogram, linspace(0, 1, 100).^3, closed = :left))))
 savefigs("histogram-1d", ans) # hide
 ```
 
@@ -171,7 +169,9 @@ savefigs("histogram-1d", ans) # hide
 
 ```@example pgf
 using StatsBase: Histogram, fit
-h = fit(Histogram, (randn(1000), randn(1000)), closed = :left)
+w = linspace(-1, 1, 100) .^ 3
+xy = vec(tuple.(w, w'))
+h = fit(Histogram, (first.(xy), last.(xy)), closed = :left)
 @pgf Axis(
     {
         view = (0, 90),
@@ -184,9 +184,7 @@ h = fit(Histogram, (randn(1000), randn(1000)), closed = :left)
             shader = "flat",
 
         },
-        Table(h);
-        incremental = false
-    )
+        Table(h))
 )
 savefigs("histogram-2d", ans) # hide
 ```

diff --git a/docs/src/examples/tables.md b/docs/src/examples/tables.md
@@ -27,7 +27,7 @@ y = sin.(x)
 You can pass these coordinates in unnamed columns:
 
 ```@example pgf
-Plot(Table([x, y]); incremental = false)
+Plot(Table([x, y]))
 savefigs("table-unnamed-columns", ans) # hide
 ```
 
@@ -38,7 +38,7 @@ savefigs("table-unnamed-columns", ans) # hide
 or named columns:
 
 ```@example pgf
-Plot(Table([:x => x, :y => y]); incremental = false)
+Plot(Table([:x => x, :y => y]))
 savefigs("table-named-columns", ans) # hide
 ```
 
@@ -54,8 +54,7 @@ or rename using options:
         x = "a",
         y = "b",
     },
-    Table([:a => x, :b => y]);
-    incremental = false)
+    Table([:a => x, :b => y]))
 savefigs("table-dict-rename", ans) # hide
 ```
 
@@ -79,8 +78,7 @@ z[z .≤ 0] .= -Inf
             surf,
             shader = "flat",
         },
-        Table(x, x, z);
-        incremental = false
+        Table(x, x, z)
     )
 )
 savefigs("table-jump-3d", ans) # hide

diff --git a/src/PGFPlotsX.jl b/src/PGFPlotsX.jl
@@ -14,8 +14,8 @@ using Requires
 
 export TikzDocument, TikzPicture
 export Axis, GroupPlot, PolarAxis
-export Plot, Plot3, Expression, EmptyLine, Coordinates,
-        Table, Graphics, Legend
+export Plot, PlotInc, Plot3, Plot3Inc, Expression, EmptyLine, Coordinates,
+    Table, Graphics, Legend, LegendEntry
 export @pgf, print_tex, latexengine, latexengine!, CUSTOM_PREAMBLE, push_preamble!
 
 const DEBUG = haskey(ENV, "PGFPLOTSX_DEBUG")