Add Gadfly examples (#275)

docs/Project.toml

@@ -1,13 +1,17 @@
 [deps]
+CategoricalArrays = "324d7699-5711-5eae-9e2f-1d82baa6b597"
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Gadfly = "c91e804a-d5a3-530f-b6f0-dfbca275c004"
 MLJModels = "d491faf4-2d78-11e9-2867-c94bc002c0b7"
 MLJXGBoostInterface = "54119dfa-1dab-4055-a167-80440f4f7a91"
 StatsPlots = "f3b207a7-027a-5e70-b257-86293d7955fd"
 
 [compat]
+CategoricalArrays = "0.8"
 DataFrames = "0.22"
 Documenter = "0.26"
+Gadfly = "1.3"
 MLJModels = "0.14"
 MLJXGBoostInterface = "0.1"
 StatsPlots = "0.14"

docs/make.jl

@@ -14,7 +14,8 @@ makedocs(
         "MCMCChains" => "index.md",
         "Getting started" => "getting-started.md",
         "Plotting" => [
-            "StatsPlots.jl" => "statsplots.md"
+            "StatsPlots.jl" => "statsplots.md",
+            "Gadfly.jl" => "gadfly.md"
         ],
         "API" => [
             "Chains" => "chains.md",

docs/src/gadfly.md

@@ -0,0 +1,60 @@
+# Gadfly.jl plots
+
+To plot the Chains via [Gadfly.jl](https://github.com/GiovineItalia/Gadfly.jl), use the DataFrames constructor:
+
+```@example gadfly
+using DataFrames
+using CategoricalArrays
+using Gadfly
+write_svg(path, p; w=6inch, h=4inch) = Gadfly.draw(Gadfly.SVG(path, w, h), p) # hide
+using MCMCChains
+
+# Define the experiment.
+n_iter = 100
+n_name = 3
+n_chain = 2
+
+# Experiment results.
+val = randn(n_iter, n_name, n_chain) .+ [1, 2, 3]'
+val = hcat(val, rand(1:2, n_iter, 1, n_chain))
+
+chn = Chains(randn(100, 2, 3), [:A, :B])
+df = DataFrame(chn)
+df[!, :chain] = categorical(df.chain)
+
+plot(df, x=:A, color=:chain, Geom.density, Guide.ylabel("Density"))
+```
+
+## Multiple parameters
+
+Or, to show multiple parameters in one plot, use `DataFrames.stack`
+
+```@example gadfly
+sdf = stack(df, names(chn), variable_name=:parameter)
+first(sdf, 5)
+```
+
+and `Gadfly.Geom.subplot_grid`
+
+```@example gadfly
+plot(sdf, ygroup=:parameter, x=:value, color=:chain,
+    Geom.subplot_grid(Geom.density), Guide.ylabel("Density"))
+```
+
+This is very flexible.
+For example, we can look at the first two chains only by using `DataFrames.filter`
+
+```@example gadfly
+first_chain = filter([:chain] => c -> c == 1 || c == 2, sdf)
+
+plot(first_chain, xgroup=:parameter, ygroup=:chain, x=:value,
+    Geom.subplot_grid(Geom.density, Guide.xlabel(orientation=:horizontal)),
+    Guide.xlabel("Parameter"), Guide.ylabel("Chain"))
+```
+
+## Trace
+
+```@example gadfly
+plot(first_chain, ygroup=:parameter, x=:iteration, y=:value, color=:chain,
+    Geom.subplot_grid(Geom.point), Guide.ylabel("Sample value"))
+```