README.md 5.61 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
5
[![](https://img.shields.io/badge/docs-dev-blue.svg)](https://vboussange.github.io/EVOID.jl/dev)
[![pipeline status](https://gitlab.ethz.ch/bvictor/EVOID/badges/master/pipeline.svg)](https://gitlab.ethz.ch/bvictor/EVOID/-/commits/master)
Victor's avatar
Victor committed
6

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

Victor's avatar
Victor committed
11
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
12

Victor's avatar
Victor committed
13
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
14

Victor's avatar
Victor committed
15
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
16

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

19
20
- flexible types for **individuals**, which can
    - evolve over any combination of space,
Victor's avatar
Victor committed
21
22
23
    - 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
24
- several **algorithms** for the simulations (Gillepsie, Wright Fisher, etc...),
Victor's avatar
Victor committed
25
- **utility functions** to analyse simulation results.
bvictor's avatar
bvictor committed
26

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

bvictor's avatar
bvictor committed
30
31
```julia
using Pkg;
Victor's avatar
Victor committed
32
Pkg.add("https://gitlab.ethz.ch/bvictor/EVOID.git")
bvictor's avatar
bvictor committed
33
```
Victor's avatar
Victor committed
34

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

bvictor's avatar
bvictor committed
37
## Getting started
Victor's avatar
Victor committed
38
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
39
40

## Similar packages
Victor's avatar
Victor committed
41
[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
42

Victor's avatar
Victor committed
43
-----
Victor's avatar
Victor committed
44
## Tutorial
45
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
46

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

Victor's avatar
Victor committed
54
### 1. Define the evolutionary spaces
55
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
56
57
58
59
60
61
62
63
64

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

Victor's avatar
Victor committed
65
66
67
68
69
70
71
72
73
### 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
74
75
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
76
```
77
> :warning: birth and death functions should have the same number of
Victor's avatar
Victor committed
78
79
80
81
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
82
83

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

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

Victor's avatar
Victor committed
90
```julia
Victor's avatar
Victor committed
91
92
93
94
95
96
97
98
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
99
100
```

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

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


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

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

Victor's avatar
Victor committed
128
129
130
![](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
131

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

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