Docstrings · EcologicalNetworksDynamics.jl

EcologicalNetworksDynamics.Internals — Module

EcologicalNetworksDynamics

Provide tools to simulate biomass dynamics in trophic and multiplex networks. Trophic networks only include feeding interactions, while multiplex networks also include non-trophic interactions such as interference between predators, or plant facilitation. The basic workflow has been designed to be as simple as possible, while remaining flexible for the experienced or adventurous user who would like to refine the model and its parameters.

Example of a simple workflow:

trophic_backbone = FoodWeb([1 => [2, 3]]) # species 1 eats plants 2 and 3
multi_net = MultiplexNetwork(trophic_backbone; L_facilitation = 1) # add 1 facilitation link
p = ModelParameters(multi_net) # generate model parameters
sol = simulate(p, rand(3)) # run simulation with random initial conditions

For more information, either go through the online documentation at (https://doc-url) or if you are looking for the help of a specific function read its docstring by writing ?<function_name> in a Julia REPL.

EcologicalNetworksDynamics.Internals.AllometricParams — Type

AllometricParams(aₚ, aₑ, aᵢ, bₚ, bₑ, bᵢ)

Parameters used to compute allometric rates for different metabolic classes.

The rate R is expressed as follow: $R = aMᵇ$, where a and b can take different values depending on the metabolic class of the species. This struct aims at storing these values of a and b. Specifically:

aₚ: a for producers
aₑ: a for ectotherm vertebrates
aᵢ: a for invertebrates
bₚ: b for producers
bₑ: b for ectotherm vertebrates
bᵢ: b for invertebrates

Default parameters values taken from the literature for certain rates can be accessed by calling the corresponding function, i.e. for:

growth rate (r) call DefaultGrowthParams
metabolic rate (x) call DefaultMetabolismParams
max consumption rate (y) call DefaultMaxConsumptionParams

Example

julia> params = AllometricParams(1, 2, 3, 4, 5, 6)
AllometricParams(aₚ=1, aₑ=2, aᵢ=3, bₚ=4, bₑ=5, bᵢ=6)

julia> params.aₚ
1

julia> params.aₑ
2

EcologicalNetworksDynamics.Internals.BioRates — Method

BioRates(
    network::EcologicalNetwork;
    d = allometric_rate(foodweb, DefaultMortalityParams()),
    r = allometric_rate(foodweb, DefaultGrowthParams()),
    x = allometric_rate(foodweb, DefaultMetabolismParams()),
    y = allometric_rate(foodweb, DefaultMaxConsumptionParams()),
    )

Compute the biological rates (r, x, y and e) of each species in the system.

The rates are:

d: the natural mortality rate
r: the growth rate
x: the metabolic rate or metabolic demand
y: the maximum consumption rate
e: the assimilation efficiency If no value are provided for the rates, they take default values assuming an allometric scaling. Custom values can be provided for one or several rates by giving a vector of length 1 or S (species richness). Moreover, if one want to use allometric scaling ($R = aMᵇ$) but do not want to use default values for a and b, one can simply call allometric_rate with custom AllometricParams.

Examples

julia> foodweb = FoodWeb([0 1; 0 0]); # sp. 1 "invertebrate", sp. 2 "producer"

julia> BioRates(foodweb) # default
BioRates:
  d: [0.0, 0.0]
  r: [0.0, 1.0]
  x: [0.314, 0.0]
  y: [8.0, 0.0]
  e: (2, 2) sparse matrix

julia> BioRates(foodweb; r = [1.0, 1.0]) # specify custom vector for growth rate
BioRates:
  d: [0.0, 0.0]
  r: [1.0, 1.0]
  x: [0.314, 0.0]
  y: [8.0, 0.0]
  e: (2, 2) sparse matrix

julia> BioRates(foodweb; x = 2.0) # if single value, fill the rate vector with it
BioRates:
  d: [0.0, 0.0]
  r: [0.0, 1.0]
  x: [2.0, 2.0]
  y: [8.0, 0.0]
  e: (2, 2) sparse matrix

julia> custom_params = AllometricParams(3, 0, 0, 0, 0, 0); # use custom allometric params...

julia> BioRates(foodweb; y = allometric_rate(foodweb, custom_params)) # ...with allometric_rate
BioRates:
  d: [0.0, 0.0]
  r: [0.0, 1.0]
  x: [0.314, 0.0]
  y: [0.0, 3.0]
  e: (2, 2) sparse matrix

EcologicalNetworksDynamics.Internals.BioenergeticResponse — Method

BioenergeticResponse(B, i, j)

Compute the bionergetic functional response for predator i eating prey j, given the species biomass B. The bionergetic functional response is written:

\[F_{ij} = \frac{\omega_{ij} B_j^h}{B_0^h + c_i B_i B_0^h + \sum_k \omega_{ik} B_k^h}\]

With:

$\omega$ the preferency, by default we assume that predators split their time equally among their preys, i.e. ∀j $\omega_{ij} = \omega_{i} = \frac{1}{n_{i,preys}}$ where $n_{i,preys}$ is the number of preys of predator i.
$h$ the hill exponent, if $h = 1$ the functional response is of type II, and of type III if $h = 2$
$c_i$ the intensity of predator intraspecific inteference
$B_0$ the half-saturation density.

Examples

julia> foodweb = FoodWeb([0 0; 1 0]);

julia> F = BioenergeticResponse(foodweb)
BioenergeticResponse:
  B0: [0.5, 0.5]
  c: [0.0, 0.0]
  h: 2.0
  ω: (2, 2) sparse matrix

julia> F([1, 1], 1, 2) # no interaction, 1 does not eat 2
0.0

julia> F([1, 1], 2, 1) # interaction, 2 eats 1
0.8

julia> F([1.5, 1], 2, 1) # increases with resource biomass
0.9

EcologicalNetworksDynamics.Internals.ClassicResponse — Method

ClassicResponse(B, i, j, mᵢ)

Compute the classic functional response for predator i eating prey j, given the species biomass B and the predator body mass mᵢ. The classic functional response is written:

\[F_{ij} = \frac{1}{m_i} \cdot \frac{\omega_{ij} a_{r,ij} B_j^h} {1 + c_i B_i + h_t \sum_k \omega_{ik} a_{r,ik} B_k^h}\]

With:

$\omega$ the preferency, by default we assume that predators split their time equally among their preys, i.e. ∀j $\omega_{ij} = \omega_{i} = \frac{1}{n_{i,preys}}$ where $n_{i,preys}$ is the number of preys of predator i.
$h$ the hill exponent, if $h = 1$ the functional response is of type II, and of type III if $h = 2$
$c_i$ the intensity of predator intraspecific inteference
$a_{r,ij}$ the attack rate of predator i on prey j
$h_t$ the handling time of predators
$m_i$ the body mass of predator i

Examples

julia> foodweb = FoodWeb([0 0; 1 0]);

julia> F = ClassicResponse(foodweb; hₜ = 1.0, aᵣ = 0.5)
ClassicResponse:
  c: [0.0, 0.0]
  h: 2.0
  ω: (2, 2) sparse matrix
  hₜ: (2, 2) sparse matrix
  aᵣ: (2, 2) sparse matrix

julia> F([1, 1], 1, 2, 1) # no interaction, 1 does not eat 2
0.0

julia> round(F([1, 1], 2, 1, 1); digits = 2) # interaction, 2 eats 1
0.33

julia> round(F([1.5, 1], 2, 1, 1); digits = 2) # increases with resource biomass
0.53

EcologicalNetworksDynamics.Internals.Environment — Method

Environment(; T=293.15)

Create environmental parameters of the system.

The environmental parameters are:

T the temperature (in Kelvin) By default, the carrying capacities of producers are assumed to be 1 while capacities of consumers are assumed to be nothing as consumers do not have a growth term.

Examples

julia> e = Environment() # Default behaviour.
       e.T == 293.15 # Kelvin
true

julia> e = Environment(; T = 300.0)
       e.T == 300.0
true

See also AllometricParams

EcologicalNetworksDynamics.Internals.DefaultMaxConsumptionParams — Method

DefaultMaxConsumptionParams()

Default allometric parameters (a, b) values for max consumption rate (y).

See also AllometricParams

EcologicalNetworksDynamics.Internals.DefaultMetabolismParams — Method

DefaultMetabolismParams()

Default allometric parameters (a, b) values for metabolic rate (x).

See also AllometricParams

EcologicalNetworksDynamics.Internals.DefaultMortalityParams — Method

DefaultMortalityParams()

Default allometric parameters (a, b) values for mortality rate (d).

See also AllometricParams

EcologicalNetworksDynamics.Internals.ExtinctionCallback — Method

ExtinctionCallback(extinction_threshold::AbstractVector, verbose::Bool)

Generate a DiffEqCallbacks.DiscreteCallback to extinguish species below the extinction_threshold. The extinction_threshold can be either: a Number (same threshold for every species) or an AbstractVector of length species richness (one threshold per species). If verbose = true a message is printed when a species goes extinct, otherwise no message are printed.

EcologicalNetworksDynamics.Internals.allometric_rate — Method

Compute rate vector (one value per species) with allometric scaling.

EcologicalNetworksDynamics.Internals.allometricparams_to_vec — Method

Create species parameter vectors for a, b of length S (species richness) given the allometric parameters for the different metabolic classes (aₚ,aᵢ,...).

EcologicalNetworksDynamics.Internals.allometricscale — Method

Allometric scaling: parameter expressed as a power law of body-mass (M).

EcologicalNetworksDynamics.Internals.asymmetrize — Method

asymmetrize(V)

Remove duplicate tuples from a symmetric vector of tuples. A vector V of tuples is said to be symmetric ⟺ ((i,j) ∈ V ⟺ (j,i) ∈ V). The tuple that has its 1st element less than its 2nd element is kept i.e. if i < j (i,j) is kept, and (j,i) otherwise.

See also asymmetrize.

EcologicalNetworksDynamics.Internals.synchrony — Method

synchrony(
    solution::Solution;
    threshold = 0,
    last = "10%",
    corrected = true,
    kwargs...,
)

Compute the synchrony of species biomass fluctuations following Loreau & de Mazancourt (2008).

See coefficient_of_variation for the argument details.

Reference

Loreau, M., & de Mazancourt, C. (2008). Species Synchrony and Its Drivers : Neutral and Nonneutral Community Dynamics in Fluctuating Environments. The American Naturalist, 172(2), E48‑E66. https://doi.org/10.1086/589746

EcologicalNetworksDynamics.Internals.top_predators — Method

top_predators(net::EcologicalNetwork)

Top predator indices (species eaten by nobody) of the given network.

julia> foodweb = FoodWeb([1 => 2, 2 => 3])
       top_predators(foodweb) == [1]
true

See also trophic_levels and trophic_classes.

EcologicalNetworksDynamics.Internals.total_richness — Method

total_richness(p::ModelParameters)

Total richness of the system defined as the sum of the number of species and the number of nutrients. If the model p does not include nutrient dynamics for producer growth, then total_richness is equivalent the species richness.

julia> foodweb = FoodWeb([1 => 2]) # 1 eats 2.
       producer_growth = LogisticGrowth(foodweb)
       model = ModelParameters(foodweb; producer_growth)
       total_richness(model) == richness(model) == 2
true

julia> producer_growth = NutrientIntake(foodweb; n_nutrients = 3) # Include nutrients.
       model_with_nutrients = ModelParameters(foodweb; producer_growth)
       S = richness(model_with_nutrients)
       N = nutrient_richness(model_with_nutrients)
       total_richness(model_with_nutrients) == S + N == 5 # 2 + 3
true

See also richness and nutrient_richness.

EcologicalNetworksDynamics.Internals.trophic_classes — Method

trophic_classes(foodweb::FoodWeb)

Categorize each species into three classes: either producers, intermediate_consumers or top_predators.

julia> foodweb = FoodWeb([1 => 2, 2 => 3])
       trophic_classes(foodweb)
(producers = [3], intermediate_consumers = [2], top_predators = [1])

To access the name of the trophic classes you can simply call trophic_classes without any argument.

julia> trophic_classes()
(:producers, :intermediate_consumers, :top_predators)

See also trophic_levels and top_predators.

EcologicalNetworksDynamics.Internals.trophic_levels — Method

trophic_levels(net::EcologicalNetwork)

Trophic level of each species.

julia> foodweb = FoodWeb([1 => 2])
       trophic_levels(foodweb) == [2.0, 1.0]
true

See also top_predators and trophic_classes.

EcologicalNetworksDynamics.Internals.trophic_structure — Method

trophic_structure(solution; threshold = 0, idxs = nothing, kwargs...)

Returns the maximum, mean and weighted mean trophic level averaged over the last timesteps. It also returns the adjacency matrix containing only the living species and the vector of the living species at the last timestep.

kwargs... arguments are forwarded to extract_last_timesteps. See extract_last_timesteps for the argument details.

Examples

julia> foodweb = FoodWeb([0 0 0; 0 0 0; 1 1 0]);
       params = ModelParameters(foodweb);
       B0 = [0.5, 0.5, 0.5];
       sol = simulate(params, B0; verbose = true);
       three_sp = trophic_structure(sol; last = 10);
       three_sp[(:max, :mean)]
(max = 2.0, mean = 1.3333333333333335)

julia> B0 = [0.5, 0.5, 0];
       sol = simulate(params, B0; verbose = true);
       no_consumer = trophic_structure(sol; last = 10);
       no_consumer[(:max, :mean)]
(max = 1.0, mean = 1.0)

julia> foodweb = FoodWeb([0 0 0; 0 1 0; 1 1 0]; quiet = true);
       params = ModelParameters(foodweb);
       B0 = [0.5, 0.5, 0.5];
       sol = simulate(params, B0; verbose = false);
       sum(trophic_structure(sol; last = 1).alive_A) - sum(foodweb.A)
-2

EcologicalNetworksDynamics.Internals.vertebrates — Method

Return indices of the vertebrates of the network (net).

EcologicalNetworksDynamics.Internals.weighted_mean_trophic_level — Method

max_trophic_level(solution::Solution; threshold = 0, kwargs...)
mean_trophic_level(solution::Solution; threshold = 0, kwargs...)
weighted_mean_trophic_level(solution::Solution; threshold = 0, kwargs...)

Return the aggregated trophic level over the last timesteps, either with max or mean aggregation, or by the mean trophic level weighted by species biomasses.

kwargs... arguments are forwarded to extract_last_timesteps. See extract_last_timesteps for the argument details.

These functions also handle biomass vectors associated with a network, as well as a vector of trophic levels (See examples).

Examples

julia> A = [0 0; 1 0];
       max_trophic_level(A)
2.0

julia> mean_trophic_level(A)
1.5

julia> bm = [1, 1];
       max_trophic_level(bm, A)
2.0

julia> mean_trophic_level(bm, A)
1.5

julia> weighted_mean_trophic_level(bm, A)
1.5

julia> bm = [0, 1];
       max_trophic_level(bm, A)
1.0

julia> mean_trophic_level(bm, A)
1.0

julia> weighted_mean_trophic_level(bm, A)
1.0

julia> foodweb = FoodWeb(A; quiet = true);
       params = ModelParameters(foodweb);
       B0 = [0.5, 0.5];
       sol = simulate(params, B0; verbose = false);
       max_trophic_level(sol)
2.0

julia> mean_trophic_level(sol)
1.5

julia> w = weighted_mean_trophic_level(sol);
       round(w; digits = 2)
1.54

EcologicalNetworksDynamics.Internals.xp_sum — Method

Repeat the given expression into terms of a sum, successively replacing indexes in term by elements in (zipped) lists.

julia> import EcologicalNetworksDynamics.Internals: xp_sum

julia> xp_sum([:i], [[1, 2, 3]], :(u^i)) #  Three terms.
:(u ^ 1 + u ^ 2 + u ^ 3)

julia> xp_sum([:i], [[1]], :(u^i)) #  Single term.
:(u ^ 1)

julia> xp_sum([:i], [[]], :(u^i)) #  No terms.
0

julia> xp_sum([:i, :j], [[:a, :b, :c], [5, 8, 13]], :(j * i)) #  Zipped indices.
:(5a + 8b + 13c)

EcologicalNetworksDynamics.Foodweb — Type

The Foodweb component, aka. "Trophic layer", adds a set of trophic links connecting species in the model. This is one of the most structuring components.

Blueprint Creation from Raw Links.

From an adjacency list:

julia> fw = Foodweb([:a => :b, :b => [:c, :d]])
blueprint for Foodweb with 2 trophic links:
  A:
  :a eats :b
  :b eats :c and :d

julia> Model(fw) # Automatically brings a 'Species' component.
Model with 2 components:
  - Species: 4 (:a, :b, :c, :d)
  - Foodweb: 3 links

julia> Model(Foodweb([4 => [2, 1], 2 => 1])) #  From species indices.
Model with 2 components:
  - Species: 4 (:s1, :s2, :s3, :s4)
  - Foodweb: 3 links

From a matrix:

julia> fw = Foodweb([0 0 1; 1 0 1; 0 0 0])
blueprint for Foodweb with 3 trophic links:
  A: 3×3 SparseArrays.SparseMatrixCSC{Bool, Int64} with 3 stored entries:
 ⋅  ⋅  1
 1  ⋅  1
 ⋅  ⋅

julia> Model(fw)
Model with 2 components:
  - Species: 3 (:s1, :s2, :s3)
  - Foodweb: 3 links

Blueprint Creation from Random Models.

Cascade model: specify the desired number of species S and connectance C.

julia> using Random
       Random.seed!(12)
       fw = Foodweb(:cascade; S = 5, C = 0.2)
blueprint for Foodweb with 5 trophic links:
  A: 5×5 SparseArrays.SparseMatrixCSC{Bool, Int64} with 5 stored entries:
 ⋅  1  ⋅  1  1
 ⋅  ⋅  ⋅  ⋅  ⋅
 ⋅  ⋅  ⋅  1  ⋅
 ⋅  ⋅  ⋅  ⋅  1
 ⋅  ⋅  ⋅  ⋅  ⋅

Random foodwebs are drawn until the desired connectance is obtained, within a tolerance level defaulted to tol_C = 0.1 * C, modifiable as a keyword argument.

Niche model: either specify the connectance C or number of links L.

julia> fw = Foodweb(:niche; S = 5, C = 0.2) #  From connectance.
blueprint for Foodweb with 5 trophic links:
  A: 5×5 SparseArrays.SparseMatrixCSC{Bool, Int64} with 5 stored entries:
 ⋅  ⋅  ⋅  ⋅  ⋅
 ⋅  ⋅  ⋅  ⋅  ⋅
 1  1  ⋅  ⋅  ⋅
 ⋅  ⋅  1  ⋅  ⋅
 1  1  ⋅  ⋅  ⋅

julia> fw = Foodweb(:niche; S = 5, L = 4) #  From number of links.
blueprint for Foodweb with 4 trophic links:
  A: 5×5 SparseArrays.SparseMatrixCSC{Bool, Int64} with 4 stored entries:
 ⋅  ⋅  ⋅  ⋅  ⋅
 ⋅  ⋅  ⋅  ⋅  ⋅
 ⋅  ⋅  ⋅  ⋅  ⋅
 1  ⋅  ⋅  ⋅  ⋅
 1  1  1  ⋅  ⋅

The default tolerance levels for the niche model are tol_C = 0.1 * C and tol_L = 0.1 * L, modifiable as keyword arguments.

For either random model, the following keyword arguments can also be specified:

reject_cycles = false (default): raise to forbid trophic cycles.
reject_if_disconnected = true (default): lower to allow disconnected trophic networks.
max_iterations = 10^5 (default): give up if no satisfying network can be found after this number of random trials.

Properties.

A model m with a Foodweb has the following properties.

m.A or m.trophic_links: a view into the matrix of trophic links.
m.n_trophic_links: the number of trophic links in the model.
m.trophic_levels: calculate the trophic level of every species in the model.
Distinguishing between producers (species without outgoing trophic links) and consumers (species with outgoing trophic links):
- m.{producers,consumers}_mask: a boolean vector to select either kind of species.
- m.n_{producers,consumers}: count number of species of either kind.
- is_{producer,consumer}(m, i): check whether species i (name or index) is of either kind.
- m.{producers,consumer}_indices: iterate over either species kind indices.
- m.{producers,consumer}_{sparse,dense}_index: obtain a $species\_name \mapsto species\_index$ mapping:
  - the sparse index yields indices valid within the whole collection of species.
  - the dense index yields indices only valid within the restricted collection of species of either kind.
Distinguishing betwen preys (species with incoming trophic links) and tops predators (species without incoming trophic links) works the same way.
m.producers_links: boolean matrix highlighting potential links between producers.
m.herbivorous_links: highlight only consumer-to-producer trophic links.
m.carnivorous_links: highlight only consumer-to-consumer trophic links.

julia> m = Model(Foodweb([:a => :b, :b => [:c, :d], :d => :e]));

julia> m.n_trophic_links
4

julia> m.A
5×5 EcologicalNetworksDynamics.TrophicLinks:
 0  1  0  0  0
 0  0  1  1  0
 0  0  0  0  0
 0  0  0  0  1
 0  0  0  0  0

julia> m.trophic_levels
5-element EcologicalNetworksDynamics.TrophicLevels:
 3.5
 2.5
 1.0
 2.0
 1.0

julia> m.producers_mask
5-element EcologicalNetworksDynamics.ProducersMask:
 0
 0
 1
 0
 1

julia> m.preys_mask
5-element EcologicalNetworksDynamics.PreysMask:
 0
 1
 1
 1
 1

julia> m.n_producers, m.n_consumers
(2, 3)

julia> m.n_tops, m.n_preys
(1, 4)

julia> is_top(m, 1), is_top(m, 2)
(true, false)

julia> collect(m.consumers_indices)
3-element Vector{Int64}:
 1
 2
 4

julia> m.producers_sparse_index
OrderedCollections.OrderedDict{Symbol, Int64} with 2 entries:
  :c => 3
  :e => 5

julia> m.producers_dense_index
OrderedCollections.OrderedDict{Symbol, Int64} with 2 entries:
  :c => 1
  :e => 2

julia> m.producers_links
5×5 EcologicalNetworksDynamics.ProducersLinks:
 0  0  0  0  0
 0  0  0  0  0
 0  0  1  0  1
 0  0  0  0  0
 0  0  1  0  1

julia> m.herbivorous_links
5×5 EcologicalNetworksDynamics.HerbivorousLinks:
 0  0  0  0  0
 0  0  1  0  0
 0  0  0  0  0
 0  0  0  0  1
 0  0  0  0  0

julia> m.carnivorous_links
5×5 EcologicalNetworksDynamics.CarnivorousLinks:
 0  1  0  0  0
 0  0  0  1  0
 0  0  0  0  0
 0  0  0  0  0
 0  0  0  0  0

EcologicalNetworksDynamics.Model — Type

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.

EcologicalNetworksDynamics.Species — Type

The Species component adds the most basic nodes compartment into the model: species. There is one node per species, and every species is given a unique name and index. The species ordering specified in this compartment is the reference species ordering.

julia> sp = Species(["hen", "fox", "snake"])
blueprint for Species:
  names: 3-element Vector{Symbol}:
 :hen
 :fox
 :snake

julia> m = Model(sp)
Model with 1 component:
  - Species: 3 (:hen, :fox, :snake)

julia> Model(Species(5)) # Default names generated.
Model with 1 component:
  - Species: 5 (:s1, :s2, :s3, :s4, :s5)

Typically, the species component is implicitly brought by other blueprints.

julia> Model(Foodweb([:a => :b]))
Model with 2 components:
  - Species: 2 (:a, :b)
  - Foodweb: 1 link

julia> Model(BodyMass([4, 5, 6]))
Model with 2 components:
  - Species: 3 (:s1, :s2, :s3)
  - Body masses: [4.0, 5.0, 6.0]

The species component makes the following properties available to a model m:

m.S or m.richness or m.species_richness or m.n_species: number of species in the model.
m.species_names: list of species name in reference order.
m.species_index: get a $species\_name \mapsto species\_index$ mapping.

julia> (m.S, m.richness, m.species_richness, m.n_species) # All aliases for the same thing.
(3, 3, 3, 3)

julia> m.species_names
3-element EcologicalNetworksDynamics.SpeciesNames:
 :hen
 :fox
 :snake

julia> m.species_index
OrderedCollections.OrderedDict{Symbol, Int64} with 3 entries:
  :hen   => 1
  :fox   => 2
  :snake => 3

EcologicalNetworksDynamics.default_model — Method

default_model(
foodweb::Foodweb;
kwargs...

)

Generate a model from a food web 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))

EcologicalNetworksDynamics.persistence — Method

persistence(vec::AbstractVector; threshold = 0)

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

EcologicalNetworksDynamics.persistence — Method

persistence(solution::AbstractODESolution; 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)
       all(persistence(sol) .== richness(sol) / S)
true

EcologicalNetworksDynamics.richness — Method

richness(vec::AbstractVector; threshold = 0)

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

Examples

julia> foodweb = Foodweb([0 0; 1 0])
       m = default_model(foodweb)
       B0 = [0.5, 0.5]
       sol = simulate(m, B0)
       richness(sol[end]) # Richness at the end of the simulation.
2.0

EcologicalNetworksDynamics.richness — Method

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]
       sol = simulate(m, B0)
       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)
       richness_trajectory = richness(sol)
       richness_trajectory[1] == 1 && richness_trajectory[end] == 0
true

EcologicalNetworksDynamics.shannon_diversity — Method

shannon_diversity(vec::AbstractVector; threshold = 0)

Shannon diversitty index given a biomass vector `vec 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.

EcologicalNetworksDynamics.shannon_diversity — Method

shannon_diversity(solution::AbstractODESolution; 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)
       shannon_trajectory = shannon_diversity(sol)
       biomass_trajectory[1] > biomass_trajectory[end]
true

EcologicalNetworksDynamics.total_biomass — Method

total_biomass(vec::AbstractVector)

Total biomass of a community given a biomass vector vec.

Examples

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

EcologicalNetworksDynamics.total_biomass — Method

total_biomass(solution::AbstractODESolution)

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)
       biomass_trajectory = total_biomass(sol)
       biomass_trajectory[1] == 0.5 && biomass_trajectory[end] == 0
true