updated docs and plot recipes

docs/src/examples/gradient.md

+# Environmental Gradient
+
+In this tutorial, we model agents evolving on a discrete segment, where each patch favours an optimal adaptive trait, along a gradient. This is typically the case along an altitudinal gradient.
+
+## Run the world
+```julia
+using Revise,ABMEv,Plots,UnPack
+
+
+nodes = 9
+dim_neutr = 30
+geospace = DiscreteSegment(Int8(1),Int8(nodes))
+adaptivespace = RealSpace{1,Float16}()
+myspace = (geospace,adaptivespace)
+sigma_K = 1.;
+sigma_a = .8;
+K0 = 1000;
+mu = [1.,1.]
+a = 1
+b(X,t) = gaussian(X[2],X[1] * a,sigma_K) / nodes
+d(X,Y,t) =  (X[1] ≈ Y[1]) * gaussian(X[2],Y[2],sigma_a) / K0
+NMax = 2000
+D = (5e-1,5e-2)
+# tend = 1.5
+tend = 1500
+p = Dict{String,Any}();@pack! p = d,b,NMax,mu,D
+
+myagents = [Agent(myspace,(Int8(5),Float16(5) + Float16(5e-2) * randn(Float16),),ancestors=true,rates=true) for i in 1:round(K0/nodes)]
+
+w0 = World(myagents,myspace,p,0.)
+
+s = run!(w0,Gillepsie(),tend,dt_saving=5);
+Plots.plot(s, ylabel = "Adaptive trait",trait=2)
+```
+![](../assets/tutorials/gradient_adaptive_trait.png)
+
+## Animated trait space
+Here we show how to plot a cool animated scatter plot of the trait space through time.
+
+```julia
+
+```
+![](../assets/tutorials/gradient_2Dtrait.gif)
+
+## Plotting lineages
+A cool feature of ABMEv.jl is its ability to track agents ancestors traits (cf [Agent section](../manual/agent.md))
+
+On can plot it, to get an idea of the coalescence of the population.
+
+![](../assets/tutorials/gradient_lineages_adaptive_trait.png)
+
+Beautiful, isn't it?
+
+!!! tip "Making sense of trait histories"
+    Some metrics are available (cf  [Metrics section](../manual/metrics.md)) that summarize the divergence in trait value (or geographical position) through time).

examples/sympatric_speciation.jl

@@ -11,9 +11,9 @@ mu = [.1]
 NMax = 2000
 tend = 1500
 p = Dict{String,Any}();@pack! p = d,b,D,mu,NMax
-myagents = [Agent(myspace,(1e-2 * randn(),),ancestors=true,rates=true) for i in 1:K0]
+myagents = [Agent(myspace,(1e-2 * randn(),),rates=true) for i in 1:K0]
 w0 = World(myagents,myspace,p,0.)
-@time sim = run!(w0,Gillepsie(),tend,dt_saving = 4)
+@time sim = run!(w0,Gillepsie(),tend,dt_saving = 10)
 
 using JLD2
 @save joinpath(@__DIR__,"sim_sympatric_speciation.jld2") sim
@@ -32,5 +32,5 @@ xplot = Plots.plot(thist,xhistall,
                 grid = false,
                 xlabel = "time",
                 ylabel = "Historical adaptive trait"
-                )a
+                )
 savefig(joinpath(@__DIR__, "x_hist_sympatric_speciation.png"))

src/ABMEv_plot.jl

@@ -41,9 +41,9 @@ last time step in the two  (three) dimensional trait space define by `trait`
         end
     end
     if length(trait) == 2
-        isnothing(time) ? w = get_world(sim[end]) :  w = get_world(sim[time])
-        y = get_x(w,trait[1]);
-        x=get_x(w,trait[2])
+        isnothing(time) ? w = get_world(sim[end]) :  w = get_world(sim,time)
+        x = get_x(w,trait[1]);
+        y = get_x(w,trait[2])
         X = hcat(x,y)
         d = kde(X)
         # by density
@@ -58,15 +58,13 @@ last time step in the two  (three) dimensional trait space define by `trait`
             # markercolor := :blue
             markerstrokewidth := 0
             # seriesalpha := 1.
-            xaxis := "geotrait"
-            yaxis := "trait value"
             label := ""
             grid := false
             # marker := (:rect,20,1.)
             x,y
         end
     end
-    if length(trait) == 2
+    if length(trait) == 3
         throw(ArgumentError("Plot for three traits not yet implemented"))
     end
 end