Merge pull request #136 from baggepinnen/plotkwargs

better docs of plotting functions and arguments

docs/src/index.md

@@ -255,7 +255,21 @@ plot(density(p[1]), density(p[2]))
 see also `examples/lhs.jl`.
 
 # Plotting
-An instance of `p::Particles` can be plotted using `plot(p)`, that creates a histogram by default. If [`StatsPlots.jl`](https://github.com/JuliaPlots/StatsPlots.jl) is available, one can call `density(p)` to get a slightly different visualization. Vectors of particles can be plotted using one of
+An instance of `p::Particles` can be plotted using `plot(p)`, that creates a histogram by default. If [`StatsPlots.jl`](https://github.com/JuliaPlots/StatsPlots.jl) is available, one can call `density(p)` to get a slightly different visualization.
+
+For arrays of particles, `plot` takes a number of keyword arguments, indicated here by the available custom plot signatures
+```julia
+plot(y::Array{Particles}, q=0.025; N=true, ri = true, quantile=nothing) # Applies to matrices and vectors
+plot(x::Array{Particles}, y::Array{Particles}, q=0.025; points=false, quantile=nothing)
+```
+
+- `q` and `quantile` denotes the quantiles used for ribbons.
+- `ri` indicates whether or not to plot ribbons.
+- `N` indicates the number of sample trajectories to plot on top of the ribbon. If `N=true`, a maximum of 50 trajectories are plotted.
+- `points` indicates whether or not to plot the individual particles as points. If `false`, error bars are shown instead.
+
+
+Vectors of particles can also be plotted using one of the custom functions
 - `errorbarplot(x,y,[q=0.025])`: `q` determines the quantiles, set to `0` for max/min. You can also specify both bounds, e.g., `q = (0.01, 0.99)`.
 - `mcplot(x,y)`: Plots all trajectories
 - `ribbonplot(x,y,[q=0.025]; N=true)`: Plots with shaded area from quantile `q` to `1-q`. You can also specify both bounds, e.g., `q = (0.01, 0.99)`.

src/bymap.jl

@@ -1,6 +1,7 @@
 import Base.Cartesian.@ntuple
 
 nparticles(p) = length(p)
+nparticles(p::Type) = 1
 nparticles(p::Type{<:AbstractParticles{T,N}}) where {T,N} = N
 nparticles(p::AbstractParticles{T,N}) where {T,N} = N
 nparticles(p::ParticleArray) = nparticles(eltype(p))

src/plotting.jl

@@ -161,6 +161,7 @@ ribbonplot
                 seriesalpha --> max(1/sqrt(nc), 0.1)
                 chosen = randperm(np)[1:nc]
                 M[chosen, :]'
+                # to1series(M[chosen, :]') # We actually want different columns to look different
             end
         end
     end
@@ -207,18 +208,23 @@ end
 
 @recipe function plt(x::AbstractArray, y::Union{MvParticles,AbstractMatrix{<:AbstractParticles}}, q=0.025; N=true, ri=true, quantile=nothing)
     samedim = size(x) === size(y)
+    layout --> max(size(x, 2), size(y, 2))
     q = quantile === nothing ? q : quantile
     if N > 0
         for col = 1:size(y,2)
             yc = y[:,col]
             if ri
                 @series begin
+                    seriescolor --> col
+                    subplot --> col
                     ribbon := quantiles(yc, q)
                     label --> "Mean with ($q, $(1-q)) quantiles"
                     x, pmean.(yc)
                 end
             end
             @series begin
+                seriescolor --> col
+                subplot --> col
                 M = Matrix(yc)
                 np,ny = size(M)
                 primary := !ri

test/runtests.jl

@@ -601,7 +601,10 @@ Random.seed!(0)
         M = randn(3,2) .+ Particles.(10)
         @test_nowarn Plots.plot(p)
         @test_nowarn Plots.plot(v)
+        @test_nowarn Plots.plot(M)
         @test_nowarn Plots.plot(v, ri=false)
+        @test_nowarn Plots.plot(v, N=0)
+        @test_nowarn Plots.plot(M, N=0)
         @test_nowarn Plots.plot(v, N=8)
         @test_nowarn Plots.plot(M, N=10)
         @test_nowarn Plots.plot(x->x^2,v)
@@ -610,11 +613,15 @@ Random.seed!(0)
         @test_nowarn Plots.plot(v,v; points=true)
         @test_nowarn Plots.plot(v,ones(3))
         @test_nowarn Plots.plot(1:3,v)
-        @test_nowarn Plots.plot(1:3,v, rib=false)
-        @test_nowarn Plots.plot(1:3, v, N=10)
-        @test_nowarn Plots.plot(1:3, M, N=10)
+        @test_nowarn Plots.plot(1:3,v, ri=false)
+        @test_nowarn Plots.plot(1:3, v, N=5)
+        @test_nowarn Plots.plot(1:3, M, N=5)
         @test_nowarn Plots.plot((1:3) .* [1 1], M, N=10)
 
+        @test_nowarn Plots.plot(1:3, v, N=0)
+        @test_nowarn Plots.plot(1:3, M, N=0)
+        @test_nowarn Plots.plot((1:3) .* [1 1], M, N=0)
+
         @test_nowarn errorbarplot(1:3,v)
         @test_nowarn errorbarplot(1:3,[v v])
         @test_nowarn mcplot(1:3,v)