Public Documentation

Documentation for BioEnergeticFoodWebs's public (exported) interface.

See Internal Documentation for documentation on internal functions.



Setting up simulations

# BioEnergeticFoodWebs.model_parametersFunction.

Create default parameters

This function creates model parameters, based on a food web matrix. Specifically, the default values are:

Parameter Default Value Meaning
K 1.0 carrying capacity of producers
Z 1.0 consumer-resource body mass ratio
r 1.0 growth rate of producers
a_invertebrate 0.314 allometric constant for invertebrate consumers
a_producers 1.0 allometric constant of producers
a_vertebrate 0.88 allometric constant for vertebrate consumers
c 0 quantifies the predator interference
h 1 Hill coefficient
e_carnivore 0.85 assimilation efficiency of carnivores
e_herbivore 0.45 assimilation efficiency of herbivores
m_producers 1 body-mass of producers
y_invertebrate 8 maximum consumption rate of invertebrate predators relative to their metabolic rate
y_vertebrate 4 maximum consumption rate of vertebrate predators relative to their metabolic rate
Γ 0.5 half-saturation density
α 1.0 interspecific competition
productivity :species type of productivity regulation

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 model assumes 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).

The final keyword is vertebrates, which is an array of true or false for every species in the matrix. By default, all species are invertebrates.


Generating networks

# BioEnergeticFoodWebs.nichemodelFunction.

Niche model of food webs

Takes a number of species S and a number of interactions L, and returns a food web with predators in rows, and preys in columns. This function is used internally by nichemodel called with a connectance.


Niche model of food webs

Takes a number of species S and a connectance C, and returns a food web with predators in rows, and preys in columns. Note that the connectance is first transformed into an integer number of interactions.

This function has two keyword arguments:

  1. tolerance is the allowed error on tolerance (see below)
  2. toltype is the type or error, and can be :abs (absolute) and :rel

(relative). Relative tolerance is the amount of error allowed, relative to the desired connectance value. If the simulated network has a tolerance x, the target connectance is c, then the relative error is |1-x/c|.


Simulating and saving the output

# BioEnergeticFoodWebs.simulateFunction.

Main simulation loop

simulate(p, biomass; start::Int64=0, stop::Int64=500, use::Symbol=:stiff)

This function takes two mandatory arguments:

  • p is a Dict as returned by make_parameters
  • biomass is an Array{Float64, 1} with the initial biomasses of every species

Internally, the function will check that the length of biomass matches with the size of the network.

In addition, the function takes three optional arguments:

  • start (defaults to 0), the initial time
  • stop (defaults to 500), the final time
  • use (defaults to :stiff), a hint to select the solver

The integration method is, by default, :stiff, and can be changed to :nonstiff. This is because internally, this function used the DifferentialEquations package to pick the most appropriate algorithm.

The simulate function returns a Dict{Symbol, Any}, with three top-level keys:

  • :p, the parameters that were given as input
  • :t, the timesteps
  • :B, an Array{Float64, 2} with the biomasses

The array of biomasses has one row for each timestep, and one column for each species.


# BioEnergeticFoodWebs.saveFunction.

Save the output of a simulation

Takes a simulation output as a mandatory argument. The two keyword arguments are as (can be :json or :jld), defining the file format, and filename (without an extension, defaults to NaN). If :jld is used, the variable is named befwm_simul unless a varname is given.

Called with the defaults, this function will write befwm_xxxxxxxx.json with the current simulation output, where xxxxxxxx is a hash of the p output (ensuring that all output files are unique).

This function is not exported, so it must be called with


Analysis of output

# BioEnergeticFoodWebs.population_stabilityFunction.

Population stability

Population stability is measured as the mean of the negative coefficient of variations of all species with an abundance higher than threshold. By default, the stability is measured over the last last=1000 timesteps.


# BioEnergeticFoodWebs.total_biomassFunction.

Total biomass

Returns the sum of biomass, averaged over the last last timesteps.


# BioEnergeticFoodWebs.population_biomassFunction.

Per species biomass

Returns the average biomass of all species, over the last last timesteps.


# BioEnergeticFoodWebs.foodweb_evennessFunction.

Food web diversity

Based on the average of Shannon's entropy (corrected for the number of species) over the last last timesteps. Values close to 1 indicate that all populations have equal biomasses.


# BioEnergeticFoodWebs.species_richnessFunction.

Number of surviving species

Number of species with a biomass larger than the threshold. The threshold is by default set at eps(), which should be close to 10^-16.


# BioEnergeticFoodWebs.species_persistenceFunction.

Proportion of surviving species

Proportion of species with a biomass larger than the threshold. The threshold is by default set at eps(), which should be close to 10^-16.