API for the animal_cohorts module
The ‘’animals’’ module provides animal module functionality.
Notes: - assume each grid = 1 km2 - assume each tick = 1 day (28800s) - damuth ~ 4.23*mass**(-3/4) indiv / km2
Classes:
|
This is a class of animal cohorts. |
- class virtual_ecosystem.models.animals.animal_cohorts.AnimalCohort(functional_group: FunctionalGroup, mass: float, age: float, individuals: int, constants: AnimalConsts = AnimalConsts())
This is a class of animal cohorts.
Methods:
F_i_j_individual(animal_list, target_cohort)Method to determine instantaneous predation rate on cohort j.
F_i_k(plant_list, target_plant)Method to determine instantaneous herbivory rate on plant k.
Calculate search efficiency.
Calculates the mass to be consumed from a plant resource by the herbivore.
Calculates the mass to be consumed from a prey cohort by the predator.
Calculate potential consumed biomass for the target plant.
calculate_potential_prey_consumed(alpha, ...)Calculate the potential number of prey consumed.
Calculate the search rate of the predator.
calculate_predation_success_probability(M_target)Calculate the probability of a successful predation event.
Calculate the optimal predation param based on predator-prey mass ratio.
Calculate total handling time across all plant resources.
Calculate the total handling time for preying on available animal cohorts.
delta_mass_herbivory(plant_list, excrement_pool)This method handles mass assimilation from herbivory.
delta_mass_predation(animal_list, ...)This method handles mass assimilation from predation.
die_individual(number_dead, carcass_pool)The function to reduce the number of individuals in the cohort through death.
eat(mass_consumed)Handles the mass gain from consuming food.
excrete(excrement_pool, mass_consumed)Transfer waste mass from an animal cohort to the excrement pool.
forage_cohort(plant_list, animal_list, ...)This function handles selection of resources from a list for consumption.
get_eaten(potential_consumed_mass, predator, ...)Removes individuals according to mass demands of a predation event.
increase_age(dt)The function to modify cohort age as time passes.
inflict_natural_mortality(carcass_pool, ...)Inflicts natural mortality in a cohort.
is_below_mass_threshold(mass_threshold)Check if cohort's total mass is below a certain threshold.
metabolize(temperature, dt)The function to reduce mass_current through basal metabolism.
The probability that a juvenile cohort will migrate to a new grid cell.
theta_i_j(animal_list)Cumulative density method for delta_mass_predation.
update_carcass_pool(carcass_mass, carcass_pool)Updates the carcass pool based on consumed mass and predator's efficiency.
Attributes:
The per-day probability of an individual dying to natural causes.
The age of the animal cohort [days].
Animal constants.
The number of individuals in an average cohort of this type.
The fraction of carcass biomass which decays before it gets consumed.
The fraction of excrement which decays before it gets consumed.
The functional group of the animal cohort which holds constants.
The number of individuals in this cohort.
The individual rate of plant mass consumption over an 8hr foraging day [kg/day].
Whether the cohort is alive [True] or dead [False].
The current average body mass of an individual [kg].
The functional type name of the animal cohort.
The identification of useable food resources.
The pool of biomass from which the material of reproduction is drawn.
- F_i_j_individual(animal_list: Sequence[AnimalCohort], target_cohort: AnimalCohort) float
Method to determine instantaneous predation rate on cohort j.
- Parameters:
animal_list – A sequence of animal cohorts that can be consumed by the predator.
target_cohort – The prey cohort from which mass will be consumed.
- Returns:
Float fraction of target cohort consumed per day.
- F_i_k(plant_list: Sequence[Resource], target_plant: Resource) float
Method to determine instantaneous herbivory rate on plant k.
This method integrates the calculated search efficiency, potential consumed biomass of the target plant, and the total handling time for all available plant resources to determine the rate at which the target plant is consumed by the cohort.
- Parameters:
plant_list – A sequence of plant resources available for consumption by the cohort.
target_plant – The specific plant resource being targeted by the herbivore cohort for consumption.
- Returns:
- The instantaneous consumption rate [g/day] of the target plant resource by
the herbivore cohort.
- adult_natural_mortality_prob
The per-day probability of an individual dying to natural causes.
- age
The age of the animal cohort [days].
- calculate_alpha() float
Calculate search efficiency.
This utilizes the alpha_i_k scaling function to determine the effective rate at which an individual herbivore searches its environment, factoring in the herbivore’s current mass.
- Returns:
A float representing the search efficiency rate in [ha/(day*g)].
- calculate_consumed_mass_herbivory(plant_list: Sequence[Resource], target_plant: Resource) float
Calculates the mass to be consumed from a plant resource by the herbivore.
This method utilizes the F_i_k method to determine the rate at which the target plant is consumed, and then calculates the actual mass to be consumed based on this rate and other model parameters.
- Parameters:
plant_list – A sequence of plant resources that can be consumed by the herbivore.
target_plant – The plant resource from which mass will be consumed.
- Returns:
The mass to be consumed from the target plant by the herbivore (in kg).
- calculate_consumed_mass_predation(animal_list: Sequence[AnimalCohort], target_cohort: AnimalCohort) float
Calculates the mass to be consumed from a prey cohort by the predator.
This method utilizes the F_i_j_individual method to determine the rate at which the target cohort is consumed, and then calculates the actual mass to be consumed based on this rate and other model parameters.
- Parameters:
animal_list – A sequence of animal cohorts that can be consumed by the predator.
target_cohort – The prey cohort from which mass will be consumed.
- Returns:
The mass to be consumed from the target cohort by the predator (in kg).
- calculate_potential_consumed_biomass(target_plant: Resource, alpha: float) float
Calculate potential consumed biomass for the target plant.
This method computes the potential consumed biomass based on the search efficiency (alpha),the fraction of the total plant stock available to the cohort (phi), and the biomass of the target plant.
- Parameters:
target_plant – The plant resource being targeted by the herbivore cohort.
alpha – The search efficiency rate of the herbivore cohort.
- Returns:
A float representing the potential consumed biomass of the target plant by the cohort [g/day].
- calculate_potential_prey_consumed(alpha: float, theta_i_j: float) float
Calculate the potential number of prey consumed.
- Parameters:
alpha – the predation search rate
theta_i_j – The cumulative density of organisms with a mass lying within the same predator specific mass bin.
- Returns:
The potential number of prey items consumed.
- calculate_predation_search_rate(w_bar: float) float
Calculate the search rate of the predator.
- Parameters:
w_bar – Probability of successfully capturing prey.
- Returns:
A float value of the search rate in ha/day
- calculate_predation_success_probability(M_target: float) float
Calculate the probability of a successful predation event.
- Parameters:
M_target – the body mass of the animal cohort being targeted for predation.
- Returns:
A float value of the probability that a predation event is successful.
- calculate_theta_opt_i() float
Calculate the optimal predation param based on predator-prey mass ratio.
- Returns:
Float value of the optimal predation parameter for use in calculating the probability of a predation event being successful.
- calculate_total_handling_time_for_herbivory(plant_list: Sequence[Resource], alpha: float) float
Calculate total handling time across all plant resources.
This aggregates the handling times for consuming each plant resource in the list, incorporating the search efficiency and other scaling factors to compute the total handling time required by the cohort.
- Parameters:
plant_list – A sequence of plant resources available for consumption by the
cohort. –
alpha – The search efficiency rate of the herbivore cohort.
- Returns:
A float representing the total handling time in days required by the cohort for all available plant resources.
- calculate_total_handling_time_for_predation() float
Calculate the total handling time for preying on available animal cohorts.
- Returns:
A float value of handling time in days.
- constants
Animal constants.
- decay_fraction_carcasses: float
The fraction of carcass biomass which decays before it gets consumed.
- delta_mass_herbivory(plant_list: Sequence[Resource], excrement_pool: DecayPool) float
This method handles mass assimilation from herbivory.
- Parameters:
plant_list – A sequence of plant resources available for herbivory.
excrement_pool – A pool representing the excrement in the grid cell.
- Returns:
A float of the total plant mass consumed by the animal cohort in g.
- delta_mass_predation(animal_list: Sequence[AnimalCohort], excrement_pool: DecayPool, carcass_pool: CarcassPool) float
This method handles mass assimilation from predation.
This is Madingley’s delta_assimilation_mass_predation
TODO: Replace delta_t values with actual reference TODO: add epsilon conversion efficiency
- Parameters:
animal_list – A sequence of animal cohorts that can be consumed by the predator.
excrement_pool – A pool representing the excrement in the grid cell.
carcass_pool – A pool representing the animal carcasses in the grid cell.
- Returns:
The change in mass experienced by the predator.
- die_individual(number_dead: int, carcass_pool: CarcassPool) None
The function to reduce the number of individuals in the cohort through death.
Currently, all cohorts are crafted as single km2 grid cohorts. This means that very large animals will have one or fewer cohort members per grid. As changes are made to capture large body size and multi-grid occupancy, this will be updated.
Currently, this function is in an inbetween state where mass is removed from the animal cohort but it is recieved by the litter pool as energy. This will be fixed once the litter pools are updated for mass.
TODO: Rework after update litter pools for mass
- Parameters:
number_dead – The number of individuals by which to decrease the population count.
carcass_pool – The resident pool of animal carcasses to which the dead individuals are delivered.
- eat(mass_consumed: float) None
Handles the mass gain from consuming food.
This method updates the consumer’s mass based on the amount of food consumed. It assumes the mass_consumed has already been calculated and processed through get_eaten.
- Parameters:
mass_consumed – The mass consumed by this consumer, calculated externally.
- Returns:
The amount of consumed mass, adjusted for efficiency and used for waste output.
- excrete(excrement_pool: DecayPool, mass_consumed: float) None
Transfer waste mass from an animal cohort to the excrement pool.
Currently, this function is in an inbetween state where mass is removed from the animal cohort but it is recieved by the litter pool as energy. This will be fixed once the litter pools are updated for mass.
TODO: Rework after update litter pools for mass
- Parameters:
excrement_pool – The local ExcrementSoil pool in which waste is deposited.
mass_consumed – The amount of mass flowing through cohort digestion.
- forage_cohort(plant_list: Sequence[Resource], animal_list: Sequence[AnimalCohort], excrement_pool: DecayPool, carcass_pool: CarcassPool) None
This function handles selection of resources from a list for consumption.
- Parameters:
plant_list – A sequence of plant resources available for herbivory.
animal_list – A sequence of animal cohorts available for predation.
excrement_pool – A pool representing the excrement in the grid cell.
carcass_pool – A pool representing the carcasses in the grid cell.
- Returns:
A float value of the net change in consumer mass due to foraging.
- functional_group
The functional group of the animal cohort which holds constants.
- get_eaten(potential_consumed_mass: float, predator: Consumer, carcass_pool: DecayPool) float
Removes individuals according to mass demands of a predation event.
It finds the smallest whole number of prey required to satisfy the predators mass demands and caps at then caps it at the available population.
- Parameters:
potential_consumed_mass – The mass intended to be consumed by the predator.
predator – The predator consuming the cohort.
carcass_pool – The pool to which remains of eaten individuals are delivered.
- Returns:
The actual mass consumed by the predator, closely matching consumed_mass.
- increase_age(dt: timedelta64) None
The function to modify cohort age as time passes.
- Parameters:
dt – The amount of time that should be added to cohort age.
- individuals
The number of individuals in this cohort.
- inflict_natural_mortality(carcass_pool: CarcassPool, number_days: float) None
Inflicts natural mortality in a cohort.
TODO Find a more efficient structure so we aren’t recalculating the time_step_mortality. Probably pass through the initialized timestep size to the scaling function
- Parameters:
carcass_pool – The grid-local carcass pool to which the dead matter is transferred.
number_days – Number of days over which the metabolic costs should be calculated.
- intake_rate: float
The individual rate of plant mass consumption over an 8hr foraging day [kg/day].
- is_below_mass_threshold(mass_threshold: float) bool
Check if cohort’s total mass is below a certain threshold.
Currently used for thesholding: birth, dispersal, trophic flow to reproductive mass.
- Parameters:
mass_threshold – a float value holding a threshold ratio of current total mass to standard adult mass.
- Returns:
A bool of whether the current mass state is above the migration threshold.
- mass_current
The current average body mass of an individual [kg].
- metabolize(temperature: float, dt: timedelta64) float
The function to reduce mass_current through basal metabolism.
TODO: Implement distinction between field and basal rates. TODO: Implement proportion of day active. TODO: clean up units TODO: Distinguish between uric and respiratory metabolic wastes
- Parameters:
temperature – Current air temperature (K)
dt – Number of days over which the metabolic costs should be calculated.
- Returns:
The mass of metabolic waste produced.
- migrate_juvenile_probability() float
The probability that a juvenile cohort will migrate to a new grid cell.
TODO: This does not hold for diagonal moves or non-square grids.
Following Madingley’s assumption that the probability of juvenile dispersal is equal to the proportion of the cohort individuals that would arrive in the neighboring cell after one full timestep’s movement.
Assuming cohort individuals are homogenously distributed within a grid cell and that the move is non-diagonal, the probability is then equal to the ratio of dispersal speed to the side-length of a grid cell.
A homogenously distributed cohort with a partial presence in a grid cell will have a proportion of its individuals in the new grid cell equal to the proportion the new grid cell that it occupies (A_new / A_cell). This proportion will be equal to the cohorts velocity (V) multiplied by the elapsed time (t) multiplied by the length of one side of a grid cell (L) (V*t*L) (t is assumed to be 1 here). The area of the square grid cell is the square of the length of one side. The proportion of individuals in the new cell is then: A_new / A_cell = (V * T * L) / (L * L) = ((L/T) * T * L) / (L * L ) = dimensionless [m2 / m2 = (m/d * d * m) / (m * m) = m / m = dimensionless]
- Returns:
The probability of diffusive natal dispersal to a neighboring grid cell.
- name
The functional type name of the animal cohort.
- prey_groups
The identification of useable food resources.
- theta_i_j(animal_list: Sequence[AnimalCohort]) float
Cumulative density method for delta_mass_predation.
The cumulative density of organisms with a mass lying within the same predator specific mass bin as Mi.
Madingley
TODO: current format makes no sense, dig up the details in the supp TODO: update A_cell with real reference
- Parameters:
animal_list – A sequence of animal cohorts that can be consumed by the predator.
- Returns:
The float value of theta.