adding some docs

docs/src/examples/changing_environment.md

+# Changing environments
+
+In this tutorial, we define a birth function that is time dependent.  This can be related to changing environment, where the optimal adaptive trait changes because of underlying resource variability, e.g. related to climate.
+
+## Defining the variation
+```julia
+  ω = 2* π / 150 # angular frequency
+  optimal_trait(t) = sin(ω * t)
+  tend = 300
+  Plots.plot(1:tend,optimal_trait,label = "Optimal trait",xlabel = "time")
+```
+![](../assets/tutorials/optimal_trait.png)
+
+## Running
+`optimal_trait` function is fed into the birth function, that we define as gaussian.
+
+```julia
+  myspace = (RealSpace{1,Float64}(),)
+  K0 = 1000 # We will have in total 1000 individuals
+  b(X,t) = gaussian(X[1],optimal_trait(t),1)
+  d(X,Y,t) = 1/K0
+  D = (5e-2,)
+  mu = [1.]
+  NMax = 2000
+  p = Dict{String,Any}();@pack! p = d,b,D,mu,NMax
+  myagents = [Agent(myspace,(0,),ancestors=true,rates=true) for i in 1:K0]
+  w0 = World(myagents,myspace,p,0.)
+  @time sim = run!(w0,Gillepsie(),tend,dt_saving=3.)
+```
+
+## Plotting
+
+```julia
+Plots.plot(sim)
+```
+![](../assets/tutorials/time_varying_pop.png)

docs/src/examples/delta_competition_example.md

@@ -96,7 +96,7 @@ Plots.plot(get_tspan(sim),wsize,
                 xlabel ="time",
                 grid = false)
 ```
-![](tutorials/delta_comp_wsize.png)
+![](../assets/tutorials/delta_comp_wsize.png)
 
 
 !!! notes "Callbacks"
@@ -113,4 +113,4 @@ Plots.plot(sim,
         grid = false,
         markersize = 10)
 ```
-![](tutorials/delta_comp_pos.png)
+![delta_comp_pos](../assets/tutorials/delta_comp_pos.png)

docs/src/examples/genetic_structure.md

@@ -6,32 +6,32 @@ The genotype space is inspired from the article [The architecture of an empirica
 
 ## Defining the space
 ```julia
-##### Genotype space#####
-dim_neutr = 1000
-magicprop = 523728 / 32896
-g = SimpleGraph{Int16}(dim_neutr,round(Int16,dim_neutr * magicprop))
-initnode = argmax(eigenvector_centrality(g)) # This is the central node the we will use to instantiate the populations
-myspace = (DiscreteSegment(Int8(1),Int8(nodes)),GraphSpace(g)) # union of vector spaces
+    ##### Genotype space#####
+    dim_neutr = 1000
+    magicprop = 523728 / 32896
+    g = SimpleGraph{Int16}(dim_neutr,round(Int16,dim_neutr * magicprop))
+    initnode = argmax(eigenvector_centrality(g)) # This is the central node the we will use to instantiate the populations
+    myspace = (DiscreteSegment(Int8(1),Int8(nodes)),GraphSpace(g)) # union of vector spaces
 ```
 ## Defining birth, death processes and mutation
 
 ```julia
-K0 = 1000
-sigma_K = 1.;
-sigma_a = .8;
-mu = [1.,1.]
-b(X,t) = 1 / nodes
-d(X,Y,t) = (X[1] ≈ Y[1]) / K0
-D = (5e-1,1.4825)
+    K0 = 1000
+    mu = [1.,1.]
+    b(X,t) = 1 / nodes
+    d(X,Y,t) = (X[1] ≈ Y[1]) / K0
+    D = (5e-1,1.4825)
 ```
 
 ## Final set up
 
 ```julia
-NMax = 2000
-# tend = 1.5
-tend = 3000
-p_default = Dict{String,Any}();@pack! p_default = d,b,NMax,mu
-myagents = [Agent(myspace,(rand(Int8(1):Int8(nodes)),initnode),ancestors=true,rates=true) for i in 1:round(K0/nodes)]
+    NMax = 2000
+    # tend = 1.5
+    tend = 3000
+    p_default = Dict{String,Any}();@pack! p_default = d,b,NMax,mu
+    myagents = [Agent(myspace,(rand(Int8(1):Int8(nodes)),initnode),ancestors=true,rates=true) for i in 1:round(K0/nodes)]
     w0 = World(myagents,myspace,p_default,0.)
 ```
+
+## Plotting

docs/src/examples/sympatric_speciation.md

 # Modelling Sympatric speciation
 
 This script aims at reproducing the 1999 article of Doebeli [On The Origin of Species By Sympatric Speciation](http://www.nature.com/articles/22521).
+
+In this article, birth and death functions are defined as gaussian, with respective variance ``\sigma_b`` and ``\sigma_d``. It is shown that when ``\sigma_d < \sigma_b``, speciation in the trait space occurs. This is what we reproduce here.
+
+## Running the world
+![]()
+
+## 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.
+
+![]()
+
+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).

docs/src/index.md

@@ -17,7 +17,17 @@ using ABMEv
 
 ## Tutorial
 We strongly advise to have a look at the tutorial section.
-
+```@contents
+Pages = [
+    "examples/delta_competition_example.md",
+    "examples/changing_environment.md",
+    "examples/sympatric_speciation.md",
+    "examples/gradient_establishment.md",
+    "examples/genetic_structure.md",
+    ""
+    ]
+Depth = 2
+```
 ## How it works
 There general workflow to launch any simulation is the following
 

docs/src/manual/run_world.md

 # Run the World
 
+- ```NMax``` Maximum number of individuals that can be attained. If attained, then the programm stops.
+
+
 For now three algorithms
 ```@docs
 Gillepsie

docs/src/manual/simulation.md

 # Simulation
-A `Simulation` object is return by the function `run!`
+A `Simulation` object is returned by the function `run!`. It is a container for snapshots of the world at every `dt_saving` time steps. It renders post processing easier, through dedicated methods to obtain time series of quantities.
+
+
+!!! note "Default behaviour"
+    If `df_saving` is not provided, initial and last time steps will be saved.
+
+
 
 
-- ```dt_saving = 10.```
-will allow to save the world every 10. time steps. If not specified, the algorithm will return first and last time step world.
-- ```NMax``` Maximum number of individuals that can be attained. If attained, then the programm stops.
-#
 ```@autodocs
 Modules = [ABMEv]
 Pages   = ["ABMEv_Sim.jl"]

examples/genetic_structure.jl

+using ABMEv,UnPack
+
+##### Genotype space#####
+dim_neutr = 1000
+magicprop = 523728 / 32896
+g = SimpleGraph{Int16}(dim_neutr,round(Int16,dim_neutr * magicprop))
+initnode = argmax(eigenvector_centrality(g)) # This is the central node the we will use to instantiate the populations
+myspace = (DiscreteSegment(Int8(1),Int8(nodes)),GraphSpace(g)) # union of vector spaces
+
+K0 = 1000
+mu = [1.,1.]
+b(X,t) = 1 / nodes
+d(X,Y,t) = (X[1] ≈ Y[1]) / K0
+D = (5e-1,1.4825)
+
+NMax = 2000
+# tend = 1.5
+tend = 3000
+p_default = Dict{String,Any}();@pack! p_default = d,b,NMax,mu
+myagents = [Agent(myspace,(rand(Int8(1):Int8(nodes)),initnode),ancestors=true,rates=true) for i in 1:round(K0/nodes)]
+w0 = World(myagents,myspace,p_default,0.)
+
+@time sim = run!(w0,Gillepsie(),tend,dt_saving=3.)
+
+using GraphPlot
+# This is to plot with consistency
+locs_x, locs_y = spring_layout(g)

examples/sympatric_speciation.jl

+using ABMEv,UnPack,Plots
+
+myspace = (RealSpace{1,Float64}(),)
+σ_b = .9;
+σ_d = .7;
+b(X,t) = 1.
+d(X,Y,t) = gaussian(X[1],Y[1],σ_d)/K0 / gaussian(X[1],0.,σ_b)
+D = (1e-2,)
+mu = [.1]
+NMax = 2000
+tend = 1000
+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]
+w0 = World(myagents,myspace,p,0.)
+@time sim = run!(w0,Gillepsie(),tend,dt_saving = 4)
+
+Plots.plot(sim, ylabel = "Adaptive trait")
+savefig(joinpath(@__DIR__, "sympatric_speciation.png"))
+
+# plotting lineages
+world = get_world(sim,get_size(sim))
+xhistall = get_xhist.(world[:],1)
+thist = get_thist.(world[:])
+xplot = Plots.plot(thist,xhistall,
+                linecolor = eth_grad_std[0.],
+                label = "",
+                # title = latexstring("\\sigma_\\mu=",@sprintf("%1.2f",world.p["D"][2][1]),", \\sigma_D=",@sprintf("%1.2f",world.p["D"][1])),
+                grid = false,
+                xlabel = "time",
+                ylabel = "Historical adaptive trait"
+                )
+savefig(joinpath(@__DIR__, "x_hist_sympatric_speciation.png"))
+
+using JLD2
+@save joinpath(@__DIR__,"sim_sympatric_speciation.jld2") sim

examples/time_varying.jl

+using ABMEv,UnPack
+
+
+ω = 2* π / 150 # angular frequency
+optimal_trait(t) = sin(ω * t)
+tend = 300
+Plots.plot(1:tend,optimal_trait,label = "Optimal trait",xlabel = "time")
+# savefig(joinpath(@__DIR__, "optimal_trait.png"))
+
+myspace = (RealSpace{1,Float64}(),)
+sigma_K = 1.;
+K0 = 1000 # We will have in total 1000 individuals
+b(X,t) = gaussian(X[1],optimal_trait(t),sigma_K)
+d(X,Y,t) = 1/K0
+D = (5e-2,)
+mu = [1.]
+NMax = 2000
+p = Dict{String,Any}();@pack! p = d,b,D,mu,NMax
+myagents = [Agent(myspace,(0,),ancestors=true,rates=true) for i in 1:K0]
+w0 = World(myagents,myspace,p,0.)
+@time sim = run!(w0,Gillepsie(),tend,dt_saving=3.)
+
+using Plots
+Plots.plot(sim, ylabel = "Adaptive trait")
+savefig(joinpath(@__DIR__, "time_varying_pop.png"))