Public documentation

disconnected_components(m::Model; kwargs...)
disconnected_components(sol::Model; kwargs...)
disconnected_components(g::Topology)

Iterate over the disconnected component within the topology. This create a collection of topologies with all the same compartments and nodes indices, but with different nodes marked as removed to constitute the various components. See topology.

adjacency_matrix(g::Topology, source, edge, target; transpose = false; prune = true)

Produce a boolean sparse matrix representing the connections of the given edge type, from the given source node compartment (lines) to the given target node compartment (colums). Flip dimensions if transpose is set. Lower prune to keep lines and columns for the nodes marked as removed. See topology.

default_model(
    blueprints...;
    without = ModelComponent[],
)

Generate a model from a foodweb with parameters set to default values.

Let's first illustrate the use of default_model with a simple example.

foodweb = Foodweb([1 => 2])
default_model(foodweb)

In this example, all parameters are set to default values, however for your needs, you can override any of the default parameters. For instance, if you want to override the default metabolic rate, you can do it as follows:

my_x = [0.0, 1.2] # One value per species.
default_model(foodweb, Metabolism(my_x))

foodweb_matrix(g::Topology; kwargs...)

Restriction of species_adjacency_matrix to only :species compartment and :trophic links.

get_extinctions(sol::Solution; date = nothing)

Extract list of extinct species indices and their extinction dates from the solution returned by simulate(). If a simulation date is provided, restrict to the list of species extinct in the simulation at this date.

get_model(sol::Solution)

Retrieve a copy of the model used for this simulation.

get_nutrients_indices(sol::Solution)

Retrieve the correct indices to extract nutrients-related data from simulation output.

get_species_indices(sol::Solution)

Retrieve the correct indices to extract species-related data from simulation output.

get_topology(model::Model; without_species = [], without_nutrients = [])
get_topology(sol::Solution, date = nothing)

Extract model topology to study topological consequences of extinctions. When called on a static model, nodes can be explicitly removed during extraction. When called on a simulation result, extinct nodes are automatically removed with extra arguments passed to extinctions.

isolated_producers(m::Model; kwargs...)
isolated_producers(sol::Solution; kwargs...)
isolated_producers(g::Topology, producers_indices) ⚠*

Iterate over isolated producers nodes, i.e. producers without incoming or outgoing edges, either in the static model topology or during/after simulation. See topology.

• ⚠ : Assumes consistent indices from the same model: will be removed in a future version.

live_consumers(m::Model; kwargs...)
live_consumers(s::Solution; kwargs...)
live_consumers(g::Topology, consumers_indices) ⚠*

Iterate over relative indices of live consumer species after simulation. See topology. ⚠*: Assumes consistent indices from the same model: will be removed in a future version.

live_nutrients(m::Model; kwargs...)
live_nutrients(sol::Solution; kwargs...)
live_nutrients(g::Topology)

Iterate over relative indices of live nutrients within the topology. See topology.

live_preys(m::Model; kwargs...)
live_preys(s::Solution; kwargs...)
live_preys(g::Topology, preys_indices) ⚠*

Iterate over relative indices of live prey species after simulation. See topology. ⚠*: Assumes consistent indices from the same model: will be removed in a future version.

live_producers(m::Model; kwargs...)
live_producers(s::Solution; kwargs...)
live_producers(g::Topology, producers_indices) ⚠*

Iterate over relative indices of live producer species after simulation. See topology. ⚠*: Assumes consistent indices from the same model: will be removed in a future version.

live_species(m::Model; kwargs...)
live_species(sol::Solution; kwargs...)
live_species(g::Topology)

Iterate over relative indices of live species within the topology. See topology.

live_tops(m::Model; kwargs...)
live_tops(s::Solution; kwargs...)
live_tops(g::Topology, tops_indices) ⚠*

Iterate over relative indices of live top species after simulation. See topology. ⚠*: Assumes consistent indices from the same model: will be removed in a future version.

n_live_consumers(m::Model; kwargs...)
n_live_consumers(sol::Solution; kwargs...)
n_live_consumers(g::Topology, consumers_indices) ⚠*

Number of live consumers within the topology after simulation. See topology. ⚠*: Assumes consistent indices from the same model: will be removed in a future version.

n_live_nutrients(m::Model; kwargs...)
n_live_nutrients(sol::Model; kwargs...)
n_live_nutrients(g::Topology)

Number of live nutrients within the topology. See topology.

n_live_preys(m::Model; kwargs...)
n_live_preys(sol::Solution; kwargs...)
n_live_preys(g::Topology, preys_indices) ⚠*

Number of live preys within the topology after simulation. See topology. ⚠*: Assumes consistent indices from the same model: will be removed in a future version.

n_live_producers(m::Model; kwargs...)
n_live_producers(sol::Solution; kwargs...)
n_live_producers(g::Topology, producers_indices) ⚠*

Number of live producers within the topology after simulation. See topology. ⚠*: Assumes consistent indices from the same model: will be removed in a future version.

n_live_species(m::Model; kwargs...)
n_live_species(sol::Solution; kwargs...)
n_live_species(g::Topology)

Number of live species within the topology. See topology.

n_live_tops(m::Model; kwargs...)
n_live_tops(sol::Solution; kwargs...)
n_live_tops(g::Topology, tops_indices) ⚠*

Number of live tops within the topology after simulation. See topology. ⚠*: Assumes consistent indices from the same model: will be removed in a future version.

persistence(biomasses::AbstractVector; threshold = 0)

Fraction of alive species given a biomass vector. See richness for details.

persistence(solution::Solution; threshold = 0)

Fraction of alive species at each timestep of the simulation. See richness for details.

Examples

julia> S = 20 # Initial number of species.
       foodweb = Foodweb(:niche; S = 20, C = 0.1)
       m = default_model(foodweb)
       B0 = rand(S)
       sol = simulate(m, B0, 2000)
       all(persistence(sol) .== richness(sol) / S)
true

richness(biomasses::AbstractVector; threshold = 0)

Return the number of alive species given a biomass vector. By default, species are considered extinct if their biomass is 0. But, this threshold can be changed using the corresponding keyword argument.

Examples

julia> richness([0.2, 0, 0.3]) # Only two species are non-extinct in this biomass vector.
2

richness(solution::Solution; threshold = 0)

Return the number of alive species at each timestep of the simulation. solution is the output of simulate. By default, species are considered extinct if their biomass is 0. But, this threshold can be changed using the corresponding keyword argument.

Examples

Let's start with a simple example where the richness remains constant:

julia> foodweb = Foodweb([0 0; 1 0])
       m = default_model(foodweb)
       B0 = [0.5, 0.5]
       tmax = 100
       sol = simulate(m, B0, tmax)
       richness_trajectory = richness(sol)
       all(richness_trajectory .== 2) # At each timestep, there are 2 alive species.
true

Now let's assume that the producer is extinct at the beginning of the simulation, while its consumer is not. We expect to observe a decrease in richness from 1 to 0 over time.

julia> B0 = [0, 0.5] # The producer is extinct at the beginning.
       sol = simulate(m, B0, 1_000)
       richness_trajectory = richness(sol)
       richness_trajectory[1] == 1 && richness_trajectory[end] == 0
true

shannon_diversity(biomasses::AbstractVector; threshold = 0)

Shannon diversity index given a biomass vector.

Shannon diversity is a measure of species diversity based on the entropy. According to the Shannon index, for a same number of species, the more evenly the biomass is distributed among them, the higher the diversity.

Example

We consider a simple example with 3 species, but different shannon diversity.

julia> s1 = shannon_diversity([1, 1, 1])
       s2 = shannon_diversity([1, 1, 0.1])
       s3 = shannon_diversity([1, 1, 0.01])
       s1 > s2 > s3
true

We observe as we decrease the biomass of the third species, the shannon diversity tends to 2, as we tend towards an effective two-species community.

shannon_diversity(solution::Solution; threshold = 0)

Shannon diversity index at each timestep of the simulation. solution is the output of simulate. Shannon diversity is a measure of species diversity based on the entropy. According to the Shannon index, for a same number of species, the more evenly the biomass is distributed among them, the higher the diversity.

Example

We start a simple simulation with even biomass distribution, therefore we expect the Shannon diversity to decrease over time as the biomass of the species diverge from each other.

julia> foodweb = Foodweb([0 0; 1 0])
       m = default_model(foodweb)
       B0 = [0.5, 0.5] # Even biomass, maximal shannon diversity.
       sol = simulate(m, B0, 1_000)
       shannon_trajectory = shannon_diversity(sol)
       biomass_trajectory[1] > biomass_trajectory[end]
true

simulate(model::Model, u0, tmax::Real; kwargs...)

The major feature of the ecological model: transform the model value into a set of ODEs and attempt to resolve them numerically to construct simulated biomasses trajectories.

• u0: Initial biomass(es).
• tmax: Maximum simulation time.
• t0 = 0: Starting simulation date.
• extinction_threshold = 1e-5: Biomass(es) values for which species are considered extinct.
• show_extinctions = false: Raise to display events during simulation.
• show_degenerated = true: Raise to warn about degenerated biomass graph properties.
• ...: additional arguments are passed to DifferentialEquations.solve.

Simulation results in a Solution object produced by the underlying DifferentialEquations package. This object contains an inner copy of the simulated model, which may then be retrieved with get_model().

species_adjacency_matrix(g::Topology, edge::Symbol; kwargs...)

Restriction of adjacency_matrix to only :species compartments.

starving_consumers(m::Model; kwargs...)
starving_consumers(sol::Solution; kwargs...)
starving_consumers(g::Topology, producers_indices, consumers_indices) ⚠*

Iterate over starving consumers nodes, i.e. consumers with no directed trophic path to a producer, either in the static model topology or after simulation. See topology.

• ⚠ : Assumes consistent indices from the same model: will be removed in a future version.

total_biomass(biomasses::AbstractVector)

Total biomass of a community given a biomass vector.

Examples

julia> total_biomass([0.5, 1.5]) # 0.5 + 1.5 = 2.0
2.0

total_biomass(solution::Solution)

Total biomass of a community at each timestep of the simulation. solution is the output of simulate.

Example

Let's consider a consumer feeding on a producer, and let's start the simulation with the producer extinction so we can observe the consumer's biomass decrease over time.

julia> foodweb = Foodweb([0 0; 1 0])
       m = default_model(foodweb)
       B0 = [0, 0.5] # The producer is extinct at the beginning.
       sol = simulate(m, B0, 1_000)
       biomass_trajectory = total_biomass(sol)
       biomass_trajectory[1] == 0.5 && biomass_trajectory[end] == 0
true

trophic_adjacency(m::Model; kwargs...)
trophic_adjacency(sol::Solution; kwargs...)
trophic_adjacency(g::Topology)

Produce a two-level iterators yielding predators on first level and all its preys on the second level. This only includes :species nodes (and not eg. :nutrients). See topology.

Model is the main object that we hand out to user which contains all the information about the underlying ecological model.

Create a Model

The most straightforward way to create a model is to use default_model. This function only requires you to specify the trophic network.

fw = [1 => 2, 2 => 3]
model = default_model(fw)

This function will help you to create a model with ease, however it relies on default values for the parameters, which are not always suitable for your specific case, even though extracted from the literature.

To create a model with custom parameters, you can pass other arguments to default_model.

model = default_model(fw, BodyMass(; Z = 100))

For instance, the above example creates a model with a body mass distribution with a predator-prey mass ratio of 100.

It is also possible to create a model manually by adding the components one by one. First, create an empty model:

m = Model()

Then add your components one by one. Note that you have to add the components in the right order, as some components depend on others. Moreover, some components are mandatory. Specifically, you need to provide a food web, species body masses, a functional response, metabolic rates and a producer growth function.

m = Model()
m += Foodweb([3 => 2, 2 => 1])
m += ClassicResponse(; h = 2, M = BodyMass([0.1, 2, 3]))
m += LogisticGrowth(; r = 1, K = 10)
m += Metabolism(:Miele2019)
m += Mortality(0)

Read and write properties of the model

First all properties contained in the model can be listed with:

properties(m) # Where m is a Model.

Then, the value of a property can be read with get_<X> where X is the name of the property. For instance, to read mortality rates:

get_mortality(m) # Equivalent to: m.mortality.

You can also re-write properties of the model using set_<X>!. However, not all properties can be re-written, because some of them are derived from the others. For instance, many parameters are derived from species body masses, therefore changing body masses would make the model inconsistent. However, terminal properties can be re-written, as the species metabolic rate.