README.md 5.47 KB
Newer Older
Victor's avatar
Victor committed
1
2
# EVOID.jl
<!-- [![](https://img.shields.io/badge/docs-stable-blue.svg)](https://vboussange.github.io/EVOID.jl/stable) -->
Victor's avatar
Victor committed
3
<!-- For now we only direct to dev documentation. In the future, one will need to deploy a ssh key to and use TagBot. -->
Victor's avatar
Victor committed
4
[![](https://img.shields.io/badge/docs-dev-blue.svg)](https://vboussange.github.io/EVOID.jl/dev)
Victor's avatar
Victor committed
5

Victor's avatar
Victor committed
6
<div align="center"> <img
Victor's avatar
Victor committed
7
8
src="https://vboussange.github.io/images/research/conceptual_onlyadapt.png"
alt="" width="400"></img> </div>
Victor's avatar
Victor committed
9

Victor's avatar
Victor committed
10
EVOID.jl is a package aimed at simulating the eco-evolutionary dynamics of a population in a multidimensional space, at the individual level.
Victor's avatar
Victor committed
11

Victor's avatar
Victor committed
12
Individuals are characterised by **a set of traits** in some **combination of evolutionary spaces**. An evolutionary space can represent for example a geographical landscape, a trait space, or genetic structure. Individuals give birth at a rate given by the birth function `b`, and die at a rate given by the death function `d`. When an individual give birth, its offspring can move on the underlying evolutionary spaces. The movement can capture whether migration or mutation processes, and is characterised by a probability `m` and movement range `D`.
Victor's avatar
Victor committed
13

Victor's avatar
Victor committed
14
The user can provide **any birth and death functions**, which should depend on the system state and the individuals' trait. Together with the **movement rate and movement range**, this defines the dynamics of the system.
Victor's avatar
Victor committed
15

Victor's avatar
Victor committed
16
EVOID.jl provides a **numerical laboratory** for eco-evolutionary dynamics, supplying
Victor's avatar
Victor committed
17

18
19
- flexible types for **individuals**, which can
    - evolve over any combination of space,
Victor's avatar
Victor committed
20
21
22
    - store ancestors trait,
- flexible types for **evolutionary spaces**, that can consist of multidimensional **discrete or continuous domains**, as well as **graphs**,
- the possibility to use **callback functions** to save the state of the system at any time step
Victor's avatar
Victor committed
23
- several **algorithms** for the simulations (Gillepsie, Wright Fisher, etc...),
Victor's avatar
Victor committed
24
- **utility functions** to analyse simulation results.
bvictor's avatar
bvictor committed
25

bvictor's avatar
bvictor committed
26
## Installation
Victor's avatar
Victor committed
27
Open Julia in your favorite REPL and type the following
Victor's avatar
Victor committed
28

bvictor's avatar
bvictor committed
29
30
```julia
using Pkg;
Victor's avatar
Victor committed
31
Pkg.add("https://github.com/vboussange/EVOID.jl")
bvictor's avatar
bvictor committed
32
```
Victor's avatar
Victor committed
33

bvictor's avatar
bvictor committed
34
This will download latest version from git repo and download all dependencies.
Victor's avatar
Victor committed
35

bvictor's avatar
bvictor committed
36
## Getting started
Victor's avatar
Victor committed
37
Check out the documentation if you want to use the advanced features of EVOID.jl. Otherwise, you can content yourself with the simple tutorial prodived below.
Victor's avatar
Victor committed
38
39

## Similar packages
Victor's avatar
Victor committed
40
[Agents.jl](https://juliadynamics.github.io/Agents.jl/) is a library oriented towards general ABM modelling, and thus is not as easy to deploy as EVOID.jl for simulating stochastic models of structured populations.
Victor's avatar
Victor committed
41

Victor's avatar
Victor committed
42
-----
Victor's avatar
Victor committed
43
## Tutorial
44
We provide here a tutorial that sums up the 5 steps necessary to launch a simulation. For the sake of the tutorial, we propose to model a population that is structured over the vertices of a graph and characterised by a trait under selection.
Victor's avatar
Victor committed
45

46
### 0. Import the relevant libraries
Victor's avatar
Victor committed
47
Let's import EVOID.jl, and LightGraphs.jl
bvictor's avatar
bvictor committed
48
```julia
Victor's avatar
Victor committed
49
using EVOID
Victor's avatar
Victor committed
50
using LightGraphs
bvictor's avatar
bvictor committed
51
```
Victor's avatar
Victor committed
52

Victor's avatar
Victor committed
53
### 1. Define the evolutionary spaces
54
We define the geographical space as star graph with 7 vertices (i.e. the abstraction of the landscape), and a continuous trait space.
Victor's avatar
Victor committed
55
56
57
58
59
60
61
62
63

```julia
nodes = 7
g = star_graph(nodes)
landscape = GraphSpace(g)
traitspace = RealSpace(1)
evolspace = (landscape,traitspace)
```

Victor's avatar
Victor committed
64
65
66
67
68
69
70
71
72
### 2. Define birth and death function
Birth and death functions depend on agents position in the combination of spaces defined above, i.e. position on the graph and the adaptive trait.
We decide that each vertex selects for an optimal trait value $`\theta_i \in \{-1,1\}`$.

```julia
K = 1000 # carrying capacity
θ = [rand([-1,1]) for i in 1:nodes] # optimal trait values
# X[1] is the geographical position
# X[2] corresponds to the adaptive traits
73
74
b(X,t) = max(1 - 0.5 * (θ[X[1]] - X[2])^2,0.)
d(X,Y,t) = (X[1]  Y[1]) / K
Victor's avatar
Victor committed
75
```
76
> :warning: birth and death functions should have the same number of
Victor's avatar
Victor committed
77
78
79
80
arguments as above.

### 3. Define how individuals move over the evolutionary space
Individual movements correspond to migration and mutation processes. On continuous spaces, one should specify a migration range and a migration rate. On discrete spaces, only a migration rate is needed (one assumes that indivuals can migrate only to neighbour patches).
Victor's avatar
Victor committed
81
82

```julia
Victor's avatar
Victor committed
83
84
D = [nothing,5e-1] # movement ranges
mu = [1.,1.] # movement rates
Victor's avatar
Victor committed
85
86
```

Victor's avatar
Victor committed
87
88
### 4. Define the initial population state

Victor's avatar
Victor committed
89
```julia
Victor's avatar
Victor committed
90
91
92
93
94
95
96
97
myagents = [] # array containing the founder individuals
for i in 1:K
    push!(myagents,Agent(evolspace, #evolutionary spaces
                        [rand(1:nodes), # random position on the graph
                        randn() * D[2]]) # random position on the trait space centered around 0
                        )
end
w0 = World(myagents,evolspace,p) # the initial world, defined at time 0.
Victor's avatar
Victor committed
98
99
```

Victor's avatar
Victor committed
100
### 5. Run
Victor's avatar
Victor committed
101
102
Simulation time, and callback function

Victor's avatar
Victor committed
103
```julia
Victor's avatar
Victor committed
104
tend = 500
Victor's avatar
Victor committed
105
t_saving_cb = collect(range(0.,tend,length=300))
Victor's avatar
Victor committed
106
cb(w) = Dict("N" => size(w))
Victor's avatar
Victor committed
107
108
109
```


Victor's avatar
Victor committed
110
111
112
113
114
115
116
117
And off we go

```julia
sim = run!(w0,
            Gillepsie(), # gillepsie algorithm
            tend,
            b,
            d,
118
            cb = cb,
Victor's avatar
Victor committed
119
120
121
            t_saving_cb = t_saving_cb)
```
### Plotting
Victor's avatar
Victor committed
122
```julia
Victor's avatar
Victor committed
123
using Plots
Victor's avatar
Victor committed
124
plot(sim.tspan, sim["N"])
Victor's avatar
Victor committed
125
126
```

Victor's avatar
Victor committed
127
128
129
![](docs/src/assets/tutorials/delta_comp_wsize.png)

With a few more tricks, one can also plot the population trait density over time, for example the local trait density for individuals living on vertex 1.
Victor's avatar
Victor committed
130

Victor's avatar
Victor committed
131
![](docs/src/assets/ABM_local_trait_dens_adapt.png)
Victor's avatar
Victor committed
132
133

Check out the folder `examples` in the git repo to see this tutorial in a julia file, as well as plenty others!