Animal model configuration#

[See also the configuration details]

Animal functional groups#

The animals.functional_group_definitions_path configuration setting must point to a CSV defining the animal functional groups to be used in a simulation. Each row in the CSV must provide a unique group name and then a set of functional trait values for that group. The file in the example data is a good template to use for preparing this file. The required trait fields are:

“name”, “taxa”, “diet”, “metabolic_type”, “reproductive_environment”, “reproductive_type”, “development_type”, “development_status”, “offspring_functional_group”, “excretion_type”, “migration_type”, “vertical_occupancy”, “birth_mass”, “adult_mass”

Animal Constants#

[animal.constants]
density_scaling_method = "madingley"
total_heterotroph_biomass_density_kg_m2 = 0.151
madingley_biomass_scaling_terms = [
    0.6,
    300000.0,
]
metabolic_scaling_coefficients = [
    0.037,
    0.69,
]
birth_mass_threshold = 1.5
flow_to_reproductive_mass_threshold = 1.0
dispersal_mass_threshold = 0.8
energy_percentile_threshold = 0.5
tau_f = 0.5
alpha_0_herb = 1e-07
alpha_0_pred = 0.01
b_herb = 0.7
b_pred = 0.05
M_herb_ref = 1.0
h_herb_0 = 0.7
M_pred_ref = 1.0
sigma_opt_pred_prey = 0.7
theta_opt_min_f = 0.01
theta_opt_f = 0.1
sigma_opt_f = 0.02
N_sigma_opt_pred_prey = 3.0
h_pred_0 = 0.5
m_tol = 1.6
c_tol = 6.61
m_tsm = 1.53
c_tsm = 1.51
placeholder_annual_mean_temp = 20.0
placeholder_annual_temp_sd = 5.0
M_disp_ref = 1.0
V_disp = 0.0278
o_disp = 0.48
beta_responsive_bodymass = 0.8
semelparity_mass_loss = 0.5
u_bg = 0.001
lambda_se = 0.003
lambda_max = 1.0
J_st = 0.6
zeta_st = 0.05
metamorph_mortality = 0.1
carbon_excreta_proportion = 0.9
nitrogen_excreta_proportion = 0.1
decay_rate_excrement = 0.25
scavenging_rate_excrement = 0.25
decay_rate_carcasses = 0.0625
scavenging_rate_carcasses = 0.25
migration_mortality = 0.1
aquatic_mortality = 0.1
aquatic_residence_time = 60.0
migration_residence_time = 60.0
seasonal_migration_probability = 0.083

[animal.constants.damuths_law_terms.mammal]
HERBIVORE = [
    -0.75,
    4.23,
]
CARNIVORE = [
    -0.75,
    1.0,
]
OMNIVORE = [
    -0.75,
    3.0,
]

[animal.constants.damuths_law_terms.bird]
HERBIVORE = [
    -0.75,
    5.0,
]
CARNIVORE = [
    -0.75,
    2.0,
]
OMNIVORE = [
    -0.75,
    3.0,
]

[animal.constants.damuths_law_terms.invertebrate]
HERBIVORE = [
    -0.75,
    5.0,
]
CARNIVORE = [
    -0.75,
    2.0,
]
OMNIVORE = [
    -0.75,
    3.0,
]

[animal.constants.damuths_law_terms.amphibian]
HERBIVORE = [
    -0.75,
    5.0,
]
CARNIVORE = [
    -0.75,
    2.0,
]
OMNIVORE = [
    -0.75,
    3.0,
]

[animal.constants.damuths_law_terms.reptile]
HERBIVORE = [
    -0.75,
    5.0,
]
CARNIVORE = [
    -0.75,
    2.0,
]
OMNIVORE = [
    -0.75,
    3.0,
]

[animal.constants.metabolic_rate_terms.endothermic]
basal = [
    41900000000.0,
    0.69,
]
field = [
    908000000000.0,
    0.7,
]

[animal.constants.metabolic_rate_terms.ectothermic]
basal = [
    41900000000.0,
    0.69,
]
field = [
    149000000000.0,
    0.88,
]

[animal.constants.energy_density]
meat = 7000.0
plant = 18200000.0

[animal.constants.conversion_efficiency]
HERBIVORE = 0.1
CARNIVORE = 0.25
OMNIVORE = 0.175

[animal.constants.mechanical_efficiency]
HERBIVORE = 0.9
CARNIVORE = 0.8
OMNIVORE = 0.85

[animal.constants.prey_mass_scaling_terms.endothermic]
mammal = [
    1.0,
    1.0,
]
bird = [
    1.0,
    1.0,
]

[animal.constants.prey_mass_scaling_terms.ectothermic]
invertebrate = [
    1.0,
    1.0,
]
amphibian = [
    1.0,
    1.0,
]
reptile = [
    1.0,
    1.0,
]

[animal.constants.cnp_proportion_terms.mammal]
C = 0.5
N = 0.3
P = 0.2

[animal.constants.cnp_proportion_terms.bird]
C = 0.4
N = 0.3
P = 0.3

[animal.constants.cnp_proportion_terms.invertebrate]
C = 0.4
N = 0.2
P = 0.4

[animal.constants.cnp_proportion_terms.amphibian]
C = 0.4
N = 0.2
P = 0.4

[animal.constants.cnp_proportion_terms.reptile]
C = 0.4
N = 0.2
P = 0.4

[animal.constants.territory_size_terms.endothermic]
mammal = [
    -6.09,
    1.13,
]
bird = [
    -6.09,
    1.13,
]

[animal.constants.territory_size_terms.ectothermic]
invertebrate = [
    -6.09,
    1.13,
]
amphibian = [
    -6.09,
    1.13,
]
reptile = [
    -6.09,
    1.13,
]
animal.constants.density_scaling_method

The density scaling method to use within a simulation. Default = madingley

animal.constants.total_heterotroph_biomass_density_kg_m2

Total heterotroph biomass density in the system, used for normalizing density. Default = 0.151

animal.constants.damuths_law_terms

Damuth Law terms, structured by taxonomic type and broad diet category. Default = {<TaxaType.MAMMAL: ‘mammal’>: {<DietType.HERBIVORE: 99487>: (-0.75, 4.23), <DietType.CARNIVORE: 31488>: (-0.75, 1.0), <DietType.OMNIVORE: 130975>: (-0.75, 3.0)}, <TaxaType.BIRD: ‘bird’>: {<DietType.HERBIVORE: 99487>: (-0.75, 5.0), <DietType.CARNIVORE: 31488>: (-0.75, 2.0), <DietType.OMNIVORE: 130975>: (-0.75, 3.0)}, <TaxaType.INVERTEBRATE: ‘invertebrate’>: {<DietType.HERBIVORE: 99487>: (-0.75, 5.0), <DietType.CARNIVORE: 31488>: (-0.75, 2.0), <DietType.OMNIVORE: 130975>: (-0.75, 3.0)}, <TaxaType.AMPHIBIAN: ‘amphibian’>: {<DietType.HERBIVORE: 99487>: (-0.75, 5.0), <DietType.CARNIVORE: 31488>: (-0.75, 2.0), <DietType.OMNIVORE: 130975>: (-0.75, 3.0)}, <TaxaType.REPTILE: ‘reptile’>: {<DietType.HERBIVORE: 99487>: (-0.75, 5.0), <DietType.CARNIVORE: 31488>: (-0.75, 2.0), <DietType.OMNIVORE: 130975>: (-0.75, 3.0)}}

animal.constants.madingley_biomass_scaling_terms

Biomass scaling terms from the Madingley model. Default = (0.6, 300000.0)

animal.constants.metabolic_scaling_coefficients

Metabolic rate scaling coefficients.

These are the coefficients of Madingley style scaling of metabolic rate with mass and temperature, assuming a power-law relationship with mass and an exponential relationship with temperature. The three values are:

  • :math:E_s - energy to mass conversion constant (g/kJ)

  • :math:E_a - aggregate activation energy of metabolic reactions Default = (0.037, 0.69)

animal.constants.metabolic_rate_terms

Parameters from Madingley, mass-based metabolic rates Default = {<MetabolicType.ENDOTHERMIC: ‘endothermic’>: {‘basal’: (41900000000.0, 0.69), ‘field’: (908000000000.0, 0.7)}, <MetabolicType.ECTOTHERMIC: ‘ectothermic’>: {‘basal’: (41900000000.0, 0.69), ‘field’: (149000000000.0, 0.88)}}

animal.constants.energy_density

Energy densities of different food sources [J/g] Default = {‘meat’: 7000.0, ‘plant’: 18200000.0}

animal.constants.conversion_efficiency

Conversion efficiencies by broad diet categories. Default = {<DietType.HERBIVORE: 99487>: 0.1, <DietType.CARNIVORE: 31488>: 0.25, <DietType.OMNIVORE: 130975>: 0.175}

animal.constants.mechanical_efficiency

Mechanical efficiencies by broad diet categories. Default = {<DietType.HERBIVORE: 99487>: 0.9, <DietType.CARNIVORE: 31488>: 0.8, <DietType.OMNIVORE: 130975>: 0.85}

animal.constants.prey_mass_scaling_terms

Prey mass scaling terms by metabolic type. Default = {<MetabolicType.ENDOTHERMIC: ‘endothermic’>: {<TaxaType.MAMMAL: ‘mammal’>: (1.0, 1.0), <TaxaType.BIRD: ‘bird’>: (1.0, 1.0)}, <MetabolicType.ECTOTHERMIC: ‘ectothermic’>: {<TaxaType.INVERTEBRATE: ‘invertebrate’>: (1.0, 1.0), <TaxaType.AMPHIBIAN: ‘amphibian’>: (1.0, 1.0), <TaxaType.REPTILE: ‘reptile’>: (1.0, 1.0)}}

animal.constants.cnp_proportion_terms

Stoichiometric proportions structured by taxon type. Default = {<TaxaType.MAMMAL: ‘mammal’>: {‘C’: 0.5, ‘N’: 0.3, ‘P’: 0.2}, <TaxaType.BIRD: ‘bird’>: {‘C’: 0.4, ‘N’: 0.3, ‘P’: 0.3}, <TaxaType.INVERTEBRATE: ‘invertebrate’>: {‘C’: 0.4, ‘N’: 0.2, ‘P’: 0.4}, <TaxaType.AMPHIBIAN: ‘amphibian’>: {‘C’: 0.4, ‘N’: 0.2, ‘P’: 0.4}, <TaxaType.REPTILE: ‘reptile’>: {‘C’: 0.4, ‘N’: 0.2, ‘P’: 0.4}}

animal.constants.birth_mass_threshold

Mass threshold for reproduction Default = 1.5

animal.constants.flow_to_reproductive_mass_threshold

Threshold of trophic flow to reproductive mass. Default = 1.0

animal.constants.dispersal_mass_threshold

Mass threshold for dispersal. Default = 0.8

animal.constants.energy_percentile_threshold

Energy threshold for initiating migration. Default = 0.5

animal.constants.tau_f

Proportion of time for which functional group is active. Default = 0.5

animal.constants.alpha_0_herb

Effective rate per unit mass at which a herbivore searches its environment. Default = 1e-07

animal.constants.alpha_0_pred

Effective rate per unit mass at which a predator searches its environment. Default = 0.01

animal.constants.b_herb

Herbivore exponent of the power-law function relating the handling time of autotroph matter to herbivore mass. Default = 0.7

animal.constants.b_pred

Carnivore exponent of the power-law relationship between the handling time of prey and the ratio of prey to predator body mass. Default = 0.05

animal.constants.M_herb_ref

Reference mass for herbivore handling time. Default = 1.0

animal.constants.h_herb_0

Time that it would take a herbivore of body mass equal to the reference mass, to handle one gram of autotroph biomass Default = 0.7

animal.constants.M_pred_ref

The reference value for predator mass. Default = 1.0

animal.constants.sigma_opt_pred_prey

Standard deviation of the normal distribution describing realized attack rates around the optimal predator-prey body mass ratio. Default = 0.7

animal.constants.theta_opt_min_f

The minimum optimal prey-predator body mass ratio. Default = 0.01

animal.constants.theta_opt_f

The mean optimal prey-predator body mass ratio, from which actual cohort optima are drawn. Default = 0.1

animal.constants.sigma_opt_f

The standard deviation of optimal predator-prey mass ratios among cohorts. Default = 0.02

animal.constants.N_sigma_opt_pred_prey

The standard deviations of the realized attack rates around the optimal predator-prey body mass ratio for which to calculate predator specific cumulative prey densities. Default = 3.0

animal.constants.h_pred_0

Time that it would take a predator of body mass equal to the reference mass, to handle a prey individual of body mass equal to one gram. Default = 0.5

animal.constants.m_tol

Slope of the relationship between monthly temperature variability and the upper critical temperature limit relative to annual mean temperature, for terrestrial ectothermic functional groups. Default = 1.6

animal.constants.c_tol

Intercept of the relationship between monthly temperature variability and the upper critical temperature limit relative to annual mean temperature, for terrestrial ectothermic functional groups. Default = 6.61

animal.constants.m_tsm

Slope of the relationship between monthly temperature variability and the optimal temperature relative to annual mean temperature, for terrestrial ectothermic functional groups. Default = 1.53

animal.constants.c_tsm

Intercept of the relationship between monthly temperature variability and the optimal temperature relative to annual mean temperature, for terrestrial ectothermic functional groups. Default = 1.51

animal.constants.placeholder_annual_mean_temp

Annual mean temperature used as a toy stand-in for \(T_{Annual}^C\) [°C]. Replace once abiotic model exposes this. Default = 20.0

animal.constants.placeholder_annual_temp_sd

Standard deviation of monthly temperatures across the climatological year, used as a toy stand-in for \(\sigma_{T_{Annual}^C}\) [°C]. Replace once abiotic model exposes this. Default = 5.0

animal.constants.M_disp_ref

The reference mass for calculating diffusive juvenile dispersal in grams. Default = 1.0

animal.constants.V_disp

Diffusive dispersal speed on an individual of body-mass equal to M_disp_ref in km/month. Default = 0.0278

animal.constants.o_disp

Power law exponent for the scaling relationship between body-mass and dispersal distance as mediated by a reference mass, M_disp_ref. Default = 0.48

animal.constants.beta_responsive_bodymass

Ratio of current body-mass to adult body-mass at which starvation-response dispersal is attempted. Default = 0.8

animal.constants.semelparity_mass_loss

The proportion of non-reproductive mass lost in semelparous reproduction. Default = 0.5

animal.constants.u_bg

The constant background mortality faced by all animal. Default = 0.001

animal.constants.lambda_se

The instantaneous rate of senescence mortality at the point of maturity. Default = 0.003

animal.constants.lambda_max

The maximum possible instantaneous fractional starvation mortality rate. Default = 1.0

animal.constants.J_st

Determines the inflection point of the logistic function describing ratio of the realised mortality rate to the maximum rate. Default = 0.6

animal.constants.zeta_st

The scaling parameter of the logistic function describing the ratio of the realised starvation mortality rate to the maximum starvation mortality rate. Default = 0.05

animal.constants.metamorph_mortality

The mortality proportion inflicted on a larval cohort undergoing metamorphosis. Default = 0.1

animal.constants.carbon_excreta_proportion

The proportion of metabolic wastes that are carbonaceous. This is a temporary fix to facilitate building the machinery and will be updated with stoichiometry. Default = 0.9

animal.constants.nitrogen_excreta_proportion

The proportion of metabolic wastes that are nitrogenous. This is a temporary fix to facilitate building the machinery and will be updated with stoichiometry. Default = 0.1

animal.constants.decay_rate_excrement

Rate at which excrement decays due to microbial activity [day^-1].

In reality this should not be constant, but as a simplifying assumption it is. Default = 0.25

animal.constants.scavenging_rate_excrement

Rate at which excrement is scavenged by animals [day^-1].

Used along with AnimalConstants.decay_rate_excrement to calculate the split of excrement between scavengable excrement and flow into the soil. In reality this should be a constant, but as a simplifying assumption it is. Default = 0.25

animal.constants.decay_rate_carcasses

Rate at which carcasses decay due to microbial activity [day^-1].

In reality this should not be constant, but as a simplifying assumption it is. Default = 0.0625

animal.constants.scavenging_rate_carcasses

Rate at which carcasses are scavenged by animals [day^-1].

Used along with AnimalConstants.decay_rate_carcasses to calculate the split of carcass biomass between scavengable carcass biomass and flow into the soil. In reality this should be a constant, but as a simplifying assumption it is. Default = 0.25

animal.constants.migration_mortality

Proportion of mortality that occurs on return from a migration [unitless]. Default = 0.1

animal.constants.aquatic_mortality

Proportion of mortality that occurs on return from aquatic status [unitless]. Default = 0.1

animal.constants.aquatic_residence_time

Amount of time a new cohort spends living in aquatic environment [days]. Default = 60.0

animal.constants.migration_residence_time

Amount of time a migrated cohort spends away [days]. Default = 60.0

animal.constants.seasonal_migration_probability

The probability a seasonal migration event occurs per time step (month). Default = 0.083

animal.constants.territory_size_terms

Territory size scaling terms (intercept, exponent) by metabolic and taxa type.

Tuple entries are (intercept, exponent) for the log-log relationship: ln(territory_ha) = intercept + exponent * ln(BM_g)

All entries currently use the Ofstad et al. (2016) closed-habitat ungulate parameters as a placeholder. The data team should replace these with taxon-specific fits as they become available.

Reference: Ofstad EG et al. 2016 Proc. R. Soc. B 283: 20161234. https://doi.org/10.1098/rspb.2016.1234 Default = {<MetabolicType.ENDOTHERMIC: ‘endothermic’>: {<TaxaType.MAMMAL: ‘mammal’>: (-6.09, 1.13), <TaxaType.BIRD: ‘bird’>: (-6.09, 1.13)}, <MetabolicType.ECTOTHERMIC: ‘ectothermic’>: {<TaxaType.INVERTEBRATE: ‘invertebrate’>: (-6.09, 1.13), <TaxaType.AMPHIBIAN: ‘amphibian’>: (-6.09, 1.13), <TaxaType.REPTILE: ‘reptile’>: (-6.09, 1.13)}}