Reference

User functions

This page lists the functions that are exported by befwm, in the other where you are likely to use them.

Simulations

# befwm.model_parameters — Function.

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

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

Alternatively, every parameter can be used as a keyword argument when calling the function. For example

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

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.

# befwm.simulate — Function.

Main simulation loop

This function takes two mandatory arguments:

p is a Dict as returned by make_parameters
biomass is a 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
steps (defaults to 5000), the number of internal steps
use (defaults to :ode45), the integration method

Note that the value of steps is the number of intermediate steps when moving from t to t+1. The total number of steps is therefore on the order of (stop - start) * steps.

Because this results in very large simulations, the function will return results with a timestep equal to unity.

The integration method is, by default, :ode45, and can be changed to one of :ode23, :ode45, :ode78, or :ode23s.

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.

If the difference between stop and start is more than an arbitrary threshold (currently 500 timesteps), the simulations will be run in chunks of 500 timesteps each. This is because the amount of memory needed to store the dynamics scales very badly. To avoid OutOfMemory() errors, running the simulation by parts is sufficient.

Measures on output

All of these functions work on the output of simulate

# befwm.population_stability — Function.

Population stability

Takes a matrix with populations in columns, timesteps in rows. This is usually the element :B of the simulation output. 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 measure over the last last=1000 timesteps.

# befwm.population_biomass — Function.

Per species biomass

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

# befwm.total_biomass — Function.

Total biomass

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

# befwm.foodweb_diversity — Function.

Food web diversity

Based on the average of Shannon's entropy over the last last timesteps.

# befwm.save — Function.

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 befwm.save.

Network utilities

# befwm.trophic_rank — Function.

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.

# befwm.nichemodel — Function.

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.

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.

Internal functions

These functions are unlikely to bee needed in a common workflow, but are presented here in case you need to manipulate the internals of befwm.

Preparation of parameters

# befwm.make_initial_parameters — Function.

Make initial parameters

Used internally by model_parameters.

# befwm.make_parameters — Function.

Make the complete set of parameters

This function will add simulation parameters, based on the output of make_initial_parameters. Used internally by model_parameters.

Internal simulation functions

# befwm.dBdt — Function.

Derivatives

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

Note that at the end of the function, we perform different checks to ensure that nothing wacky happens during subsequent integration steps. Specifically, if B+dB/dt < ϵ(0.0), we set dBdt to -B. ϵ(0.0) is the next value above 0.0 that your system can represent.

# befwm.inner_simulation_loop! — Function.

Inner simulation loop

This function is called internally by simulate, and should not be called by the user.

Note that output is a pre-allocated array in which the simulation result will be written, and i is the origin of the simulation.

Numerical integration

# befwm.wrap_ode — Function.

Wrapper for ode functions

These functions will let ODE do its job, then return the results in way we can handle.

# befwm.wrap_ode45 — Function.

Wrapper for ode45

See wrap_ode.

# befwm.wrap_ode78 — Function.

Wrapper for ode78

See wrap_ode.

# befwm.wrap_ode23 — Function.

Wrapper for ode23

See wrap_ode.

# befwm.wrap_ode23s — Function.

Wrapper for ode23s

See wrap_ode.

Internal checks

# befwm.check_parameters — Function.

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.

# befwm.check_food_web — Function.

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.

Other functions

# befwm.shannon — Function.

Shannon's entropy

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

# befwm.coefficient_of_variation — Function.

Coefficient of variation

Corrected for the sample size.

# befwm.distance_to_producer — Function.

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.