Internal Documentation



Functions and methods for networks


Distance to a primary producer

This function measures, for every species, its shortest path to a primary producer using matrix exponentiation. A primary producer has a value of 1, a primary consumer a value of 2, and so forth.


Trophic rank

Based on the average distance of preys to primary producers. Specifically, the rank is defined as the average of the distance of preys to primary producers (recursively). Primary producers always have a trophic rank of 1.


Is the matrix correctly formatted?

A correct matrix has only 0 and 1, two dimensions, and is square.

This function returns nothing, but raises an AssertionError if one of the conditions is not met.

ODE wrappers and functions for integration



This function is the one wrapped by the various integration routines. Based on a timepoint t, an array of biomasses biomass, and a series of simulation parameters p, it will return dB/dt for every species.

Functions to work on output


Shannon's entropy

Corrected for the number of species, removes negative and null values, return NaN in case of problem.

Functions to prepare and check parameters


Create default parameters

This function creates model parameters, based on a food web matrix A. See documentation for more information. Specifically, the default values of the keyword parameters are:

ParameterDefault ValueMeaning
K1.0carrying capacity of producers
Z1.0consumer-resource body mass ratio
bodymass[0.0]default is to calculates masses from Z unless a vector of bodymass is passed
drymass293[0.0]dry masses at 20 degrees celsius
TSR_type:no_responsetemperature size rule: set the function for masses dependence to temperature, see docs
vertebrates[false]metabolic status of species (invertebrates or ectotherm vertebrates)
r1.0growth rate of producers
c0quantifies the predator interference
h1Hill coefficient
e_carnivore0.85assimilation efficiency of carnivores
e_herbivore0.45assimilation efficiency of herbivores
y_invertebrate8maximum consumption rate of invertebrate predators relative to their metabolic rate
y_vertebrate4maximum consumption rate of vertebrate predators relative to their metabolic rate
Γ0.5half-saturation density
α1.0interspecific competition relatively to intraspecific competition
scale_bodymasstruewhether to normalize body masses by the mass of the smallest producer
scale_growthfalsewhether to normalize growth rates by the growth rate of the smallest producer
scale_metabolismfalsewhether to normalize metabolic rates by the growth rate of the smallest producer
scale_maxconsfalsewhether to normalize max. consumption rates by metabolic rates
productivity:speciestype of productivity regulation
dcx -> x .* 0.0density dependent mortality function for consumers
dpx -> x .* 0.0density dependent mortality function for producers
rewire_method:nonemethod for rewiring the foodweb following extinction events
adbm_trigger:extinction(ADBM) trigger for ADBM rewiring (on extinctions or periodic with :interval)
adbm_interval100(ADBM) Δt for periodic rewiring
e1(ADBM) Scaling constant for the net energy gain
a_adbm0.0189(ADBM) Scaling constant for the attack rate
ai-0.491(ADBM) Consumer specific scaling exponent for the attack rate
aj-0.465(ADBM) Resource specific scaling exponent for the attack rate
b0.401(ADBM) Scaling constant for handling time
h_adbm1.0(ADBM) Scaling constant for handling time
hi1.0(ADBM) Consumer specific scaling exponent for handling time
hj1.0(ADBM) Resource specific scaling constant for handling time
n1.0(ADBM) Scaling constant for the resource density
ni0.75(ADBM) Species-specific scaling exponent for the resource density
Hmethod:ratio(ADBM) Method used to calculate the handling time
Nmethod:original(ADBM) Method used to calculate the resource density
cost0.0(Gilljam) Rewiring cost (a consumer decrease in efficiency when exploiting novel resource)
specialistPrefMag0.9(Gilljam) Strength of the consumer preference for 1 prey if preferenceMethod = :specialist
preferenceMethod:generalist(Gilljam) Scenarios with respect to prey preferences of consumers
D0.25(nutrient intake) global turnover rate
ν[1.0, 0.5](nutrient intake) conversion rates for nutrients
K1[0.15](nutient intake) species half saturation densities for nutrient 1
K2[0.15](nutient intake) species half saturation densities for nutrient 2
T273.15(temperature dependence) temperature
growthrateNoEffectTemperature(:r)Function used to calculate growth rate
metabolicrateNoEffectTemperature(:x)Function used to calculate metabolic rate
handlingtimeNoEffectTemperature(:handlintime)Function used to calculate handling time (and max. consumption rate)
attackrateNoEffectTemperature(:attackrate)Function used to calculate attack rate (and Γ)

All of these values are passed as optional keyword arguments to the function.

A = [0 1 1; 0 0 0; 0 0 0]
p = model_parameters(A, Z=100.0, productivity=:system)

The productivity keyword can be either :species (each species has an independant carrying capacity equal to K), :system (the carrying capacity is K divided by the number of primary producers), or :competitive (the species compete with themselves at rate 1.0, and with one another at rate α).

It is possible for the user to specify a vector of species body-mass, called bodymass – please do pay attention to the fact that the default behavior is to assume that primary producers have a bodymass equal to unity, since all biological rates are expressed relatively. We do not perform any check on whether or not the user-supplied body-mass vector is correct (mostly because there is no way of defining correctness for vectors where body-mass of producers are not equal to unity). It is possible to turn off the scaling (scale_bodymass = false), in that case we strongly recommend setting scale_growth = true ( and possibly scale_metabolism = true and scale_maxcons = true).

The keyword vertebrates is an array of true or false for every species in the matrix. If the vector is of size 1 (e.g. [false]), all species will take this metabolic status. By default, all species are invertebrates.

A rewiring method can pe passed to specified if the foodweb should be rewired following extinctions events, and the method that should be used to perform the rewiring. This rewire_method keyword can be eighter :none (no rewiring), :ADBM (allometric diet breadth model as described in Petchey et al., 2008), :DS (rewiring mechanism used by Gilljam et al., 2015, based on diet similarity) or :DO (rewiring mechanism used by Staniczenko et al, 2010, based on diet overlap).

If rewire_methodis :ADBM or :DS, additional keywords can be passed. See the online documentation and the original references for more details.

Temperature dependence for metabolic rates and body masses can be implemented, please check the documentation for more information.


Are the simulation parameters present?

This function will make sure that all the required parameters are here, and that the arrays and matrices have matching dimensions.