EvoId.jl (for **Evo**lutionary **I**n**d**ividual-based models) is a package aimed at simulating the eco-evolutionary dynamics of a population in a multidimensional space, at the individual level. The dynamics is specified under the framework of [stochastic models for structured populations](https://arxiv.org/abs/1506.04165).

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`.

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. Spaces can be of any dimensions, discrete or continuous, bounded or unbounded. They can equally consist of graphs. 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`.

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.

...

...

@@ -17,10 +17,10 @@ EvoId.jl provides a **numerical laboratory** for eco-evolutionary dynamics, supp

- 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

- several **algorithms** for the simulations (Gillespie, WrightFisher, etc...),

- several **algorithms** for the simulations ([Gillespie](https://en.wikipedia.org/wiki/Gillespie_algorithm),[Wright-Fisher](https://en.wikipedia.org/wiki/Moran_process), etc...),

-**utility functions** to analyse simulation results.

This will download latest version from git repo and download all dependencies.

## Getting started

Check out the tutorial prodived below. You can also dive into the [documentation](https://vboussange.github.io/EvoId.jl/dev) if you want to use the advanced features of EvoId.jl.

Check out the tutorial prodived below. You can also look at the `example` folder, or dive into the [documentation](https://vboussange.github.io/EvoId.jl/dev) if you want to use the advanced features of EvoId.jl.

## Related papers

-[Topology and habitat assortativity drive neutral and adaptive diversification in spatial graphs](https://www.biorxiv.org/content/10.1101/2021.07.06.451404v2), Boussange et al. 2021.

...

...

@@ -54,7 +54,6 @@ We provide here a tutorial that sums up the 5 steps necessary to launch a simula

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.

Birth and death functions depend on individuals 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\}`$.

I recommend to first clone your branch in the directory you like best, and then to

To develop, you can

I recommend to first clone your branch in the directory you like best, and then to develop, you can

```julia

usingPkg

Pkg.dev("path_to_EvoId_dir")

...

...

@@ -8,13 +7,11 @@ Pkg.dev("path_to_EvoId_dir")

You can also do the same trick with directly the gitlab address, cf [Pkg.jl](https://docs.julialang.org/en/v1/stdlib/Pkg/index.html)

## Future directions

-Try to improve parallelism with the help of Threads.@Threads and @inbounds (cf [tutorial](https://juliagpu.gitlab.io/CUDA.jl/tutorials/introduction/#Introduction-1) )

-Make use of CUDA.jl to accelerate the simulations wih the use of GPU.

## Todo

-We do not need to have the `Rates{}` parameter for `Agent` type.

-Fix `WF` algorithm

-Implement Moran process

- extend the birth function to the form `b(X,Y,t)` for coherence with death function

- make mutation and disperal range features of agents, so that they can also evolve.

-Simplify composite type `Rates{}` parameter for `Agents`.

```julia

abstract type AbstractAgent{A<:Ancestors,R<:Rates}end

```

- extend the birth function to the form `b(X,Y,t)` for coherence with death function

- make mutation and disperal range features of agents, so that they can also evolve.

EvoId.jl (for **Evo**lutionary **I**n**d**ividual-based model) is a package aimed at simulating the evolutionary dynamics of a population in a multidimensional space. The population is modelled at the individual level. Individuals experience four elementary events : birth, death, mutation and migration.

- EvoId.jl hence falls in the realm of *Agent Based Model*.

EvoId.jl provides a numerical laboratory for evolutionary dynamics, supplying

- flexible types for individuals, which can

- evolve over any combination of space

- store ancestors trait,

- flexible types for evolutionary spaces, comprising multidimensional discrete and continuous sets, as well as graphs,

- the possibility for the user to provide any birth and death functions,

- several algorithms for the simulations,

- utility functions to analyse simulation results.

## Features

Agents consist of sets of traits in some combination of evolutionary spaces. An evolutionary space can represent for example a geographical landscape, a trait space, or genetic structure. Spaces can be of any dimensions, discrete or continuous, bounded or unbounded. They can equally consist of graphs.

Vector spaces are used to define birth and death processes, as well as mutation processes.

### Specificities

-[EvoId.jl allows to keep track of agents' trait lineages](@ref lineages)

-[EvoId.jl enables to run evolutionary dynamics on graphs!](@ref genetic_structure)

## Getting started

```@repl

using EvoId

```

## Tutorial

We strongly advise to have a look at the tutorial section. All the scripts of the examples can be found [here](https://gitlab.ethz.ch/bvictor/EvoId/-/tree/master/examples).

```@contents

Pages = [

"examples/delta_competition_example.md",

"examples/changing_environment.md",

"examples/sympatric_speciation.md",

"examples/gradient.md",

"examples/genetic_structure.md",

""

]

Depth = 2

```

## How it works

General workflow to launch any simulation is the following

-[Define the combination of vector spaces you are interested in.](manual/space.md)

- Define birth and death function, that depend on agents position in the space

- Define mutation function

-[Define initial population state and time](manual/world)

-[Run the simulation according to some updating algorithm](manual/run_world.md)

-[Obtain a summary of the population state](manual/callbacks.md)

### Available algorithms

As of now, three types of simulation algorithm can be used:

-[Gillepsie](manual/gillepsie.md)

-[Wright-Fisher](manual/wright_fisher.md)

-[CFM](CFM.md)

## References

-[Champagnat and Ferriere founding article](https://linkinghub.elsevier.com/retrieve/pii/S0040580905001632)

-[Champagnat and Ferriere second article - 2008](https://www.tandfonline.com/doi/full/10.1080/15326340802437710)

## Similar packages

[Agents.jl](https://juliadynamics.github.io/Agents.jl/) This package is oriented towards general ABM modelling, and thus is not as efficient and easy to deploy as EvoId.jl for simulating stochastic models of structured populations.

EvoId.jl (for **Evo**lutionary **I**n**d**ividual-based models) is a package aimed at simulating the eco-evolutionary dynamics of a population in a multidimensional space, at the individual level. The dynamics is specified under the framework of [stochastic models for structured populations](https://arxiv.org/abs/1506.04165).

Callbacks can be used to extract properties of the world at each `dt_saving` time steps of your simulation.

## Constructing the callbacks

A callback has to be of the form

```julia

cb=(names=String[],agg=Function[])

```

It is a tuple, with first value corresponding to the names of the aggregate properties of the world. The second correspond to the aggregation functions.

We provide here an example on how to extract the ``\gamma`` diversity of a simulation biological population. ``\gamma`` diversity can be calculated as the variance of the trait distribution of the population.

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.

is chosen at random with a probability equal to the rate of this event divided by the total rate ``R``.

# The original article by Gillsepie:

[**A general method for numerically simulating the stochastic time evolution of coupled chemical reactions**](https://www.sciencedirect.com/science/article/pii/0021999176900413?via%3Dihub)

[**A general method for numerically simulating the stochastic

time evolution of coupled chemical reactions**](https://www.sciencedirect.com/science/article/pii/0021999176900413?via%3Dihub)