RUFAS.biophysical.animal.animal module#

RUFAS.biophysical.animal.animal.random() → x in the interval [0, 1).#

Bases: object

This class represents an animal in the RuFaS simulation.

DO NOT USE THE PROPERTIES THAT START WITH ‘_’. INSTEAD, USE THE FUNCTIONS THAT ARE DECORATED WITH @property.

Attributes#

id: int: The unique identifier of the animal, (unitless).
breed: Breed: The breed of the animal.
animal_type: AnimalType: The current life stage of the animal.
days_born: int: The age of the animal, (simulation days).
body_weight: float: The body weight of the animal, (kg).
birth_weight: float: The birth weight of the animal, (kg).
mature_body_weight: float: The mature body weight of the animal, (kg).
wean_weight: float: The body weight of the animal at weaning, (kg).
net_merit: float: The net merit value of the animal, ($USD).
body_condition_score_5: float: The body condition score on a scale of 1 to 5, (unitless).
cull_reason: str: The reason for the animal to leave the herd.
body_weight_history: list[BodyWeightHistory]: The body weight history of the animal.
pen_history: list[PenHistory]: The pen history of the animal.
sold_at_day: int | None: The simulation day in which the animal was sold.
dead_at_day: int | None: The simulation day in which the animal died, (simulation day).
events: AnimalEvents: The AnimalEvents object that records all major events of the animal.
growth: Growth: The animal growth submodule that handles the body weight change of the animal.
digestive_system: DigestiveSystem: The digestive system submodule that handles the daily manure excretion of the animal.
milk_production: MilkProduction: The milk production submodule that handles the daily milk production of the animal.
nutrients: Nutrients: The nutrients submodule that handles the daily phosphorus update of the animal.
_reproduction: Reproduction: The reproduction submodule that handles the daily reproduction update of the animal.
nutrition_requirements: NutrientsRequirements: The nutrition requirement for the animal.
nutrition_supply: NutritionSupply: The supplied nutrition in the current ration interval for the animal.
previous_nutrition_supply: NutritionSupply: The previously supplied nutrition from the las ration interval for the animal.
animal_statistics: AnimalStatistics: The AnimalStatistics object that tracks all major statistics of the animal.
_days_in_milk: int: The number of days that the animal has been in milk production, (days).
_days_in_pregnancy: int: The number of days that the animal has been in pregnancy, (days).
_future_cull_date: int | None: The age of which the animal will be culled, (day).
_future_death_date: int | None: The age of which the animal will die, (day).
_daily_horizontal_distance: float: The daily horizontal distance traveled by the animal, (m).
_daily_vertical_distance: float: The daily vertical distance traveled by the animal, (m).
_daily_distance: float: The total daily distance traveled by the animal, (m).
sex: Sex: The sex of the animal.
nutrient_standard: NutrientStandard: The nutrient standard used to calculate nutrition related values.

nutrient_standard: NutrientStandard#

Initializes an Animal object.

Parameters#

args(: NewBornCalfValuesTypedDict | CalfValuesTypedDict | HeiferIValuesTypedDict | HeiferIIValuesTypedDict | CowValuesTypedDict

)

The dictionary that contains the configuration to initialize an Animal object.

classmethod set_nutrient_standard(nutrient_standard: NutrientStandard) → None#

Set the nutrient standard for the all animals.

Parameters#

nutrient_standardNutrientStandard: An instance of NutrientStandard that defines the standard to set.

static setup_lactation_curve_parameters(time: RufasTime) → None#

Sets up the parameters for the lactation curve model.

Parameters#

timeRufasTime: An RufasTime object representing the time used to set the lactation curve parameters.

property days_in_milk: int#

The number of days the animal has been in milk production.

Returns#

int: The number of days the animal has been in milk production. If the animal is not a cow, returns 0.

property days_in_pregnancy: int#

The total number of days an animal has been in pregnancy.

Returns#

int: The number of days the animal has been in pregnancy.

Notes#

For animals of type CALF or HEIFER_I, the pregnancy duration is always considered to be zero.
For all other types of animals, the value of _days_in_pregnancy is returned.

property is_pregnant: bool#

Checks if the animal is pregnant based on its type and pregnancy days.

Returns#

bool: True if the animal is pregnant, otherwise False.

property is_milking: bool#

Check if the animal is milking.

This property determines if the animal is currently milking. It specifically checks if the animal type is a cow and if the cow has been in milk for at least one day.

Returns#

bool: True if the animal is a cow and in milk, False otherwise.

property future_cull_date: int#

Returns the cull death date of the animal.

If the animal is not a cow, the method returns the maximum possible integer value. Otherwise, it returns the pre-calculated future cull date.

Returns#

int: The future cull date or the maximum possible integer value if the animal is not a cow.

property future_death_date: int#

Returns the future death date of the animal.

If the animal is not a cow, the method returns the maximum possible integer value. Otherwise, it returns the pre-calculated future death date.

Returns#

int: The future death date of the animal in integer form (sys.maxsize for non-cow animals).

property daily_horizontal_distance: float#

Returns the daily horizontal distance traveled by the animal.

Returns#

float: The daily horizontal distance traveled.

Raises#

TypeError: If the animal type is not a cow.

property daily_vertical_distance: float#

Returns the daily vertical distance traveled by an animal.

Returns#

float: The daily vertical distance traveled by the cow.

Raises#

TypeError: If the animal type is not a cow.

property daily_distance: float#

Returns the daily distance traveled by the animal.

If the animal is not a cow and is currently milking, the daily distance is considered to be 0.0. Otherwise, it returns the value of the stored daily distance.

Returns#

float: The daily distance traveled by the animal.

property reproduction: Reproduction#

Gets the reproduction property of the object.

Returns#

Reproduction: The reproduction property of the object.

property calves: int#

Fetches the number of calves the animal has given birth to.

Only applicable if the animal type is a cow. If the animal type is not a cow, it will return 0.

Returns#

int: The number of calves if the animal type is a cow, otherwise 0.

property calving_interval: int#

Returns the calving interval for the animal.

If the animal type is not a cow, the calving interval is 0. Otherwise, it retrieves the calving interval from the reproduction information.

Returns#

int: The calving interval in days or 0 if the animal is not a cow.

property conceptus_weight: float#

Returns the conceptus weight of the animal.

Returns#

float: The weight of the conceptus. Returns 0.0 for calf and heiferI; otherwise returns the value from the reproduction attribute.

property gestation_length: int#

Returns the gestation length for the animal.

Returns#

int: The gestation length of the animal in days. Returns 0 if the animal type is CALF or HEIFER_I, otherwise returns the gestation length from the reproduction attribute.

property calf_birth_weight: float#

Getter for the calf birth weight of the animal.

Returns#

float: The weight of the calf at birth. Defaults to 0.0 if the animal type is either CALF or HEIFER_I. Otherwise, it retrieves the value from the reproduction attribute.

property calving_interval_history: list[int]#

Returns the calving interval history for the animal.

Returns#

list of int: A list containing the recorded calving intervals of the cow.

Raises#

TypeError: If the animal is not of type cow.

property heifer_reproduction_program: HeiferReproductionProtocol#

Returns the heifer reproduction program.

Returns#

HeiferReproductionProtocol: The heifer reproduction program from the reproduction data.

Raises#

TypeError: If the animal type is either CALF or HEIFER_I, which are not suitable for this reproduction protocol.

property heifer_reproduction_sub_program: HeiferTAISubProtocol | HeiferSynchEDSubProtocol#

heifer_reproduction_sub_program property.

This property retrieves the heifer reproduction subprogram associated with the current object. If the animal type is not applicable for heifer reproduction subprograms, a TypeError is raised.

Returns#

HeiferTAISubProtocol or HeiferSynchEDSubProtocol: The heifer reproduction subprogram for the given animal type.

Raises#

TypeError: If the animal type is either CALF or HEIFER_I.

property cow_reproduction_program: CowReproductionProtocol#

Cow reproduction program for the specified animal.

This property retrieves the cow reproduction program associated with the current object. It checks whether the animal type is a cow, and raises a TypeError otherwise.

Returns#

CowReproductionProtocol: The cow reproduction program relevant to the current animal.

Raises#

TypeError: If the animal type is not a cow.

property cow_presynch_program: CowPreSynchSubProtocol#

Returns the cow PreSynch protocol associated with the animal.

Returns#

CowPreSynchSubProtocol: The PreSynch protocol specific to cows.

Raises#

TypeError: If the associated animal type is not a cow.

property cow_ovsynch_program: CowTAISubProtocol#

Retrieve the CowTAISubProtocol associated with the cow’s ovsynch program if the animal type is a cow.

Returns#

CowTAISubProtocol: The cow’s ovsynch program information.

Raises#

TypeError: If the animal type is not a cow.

property cow_resynch_program: CowReSynchSubProtocol#

Returns the cow ReSynch program specific to the cow species.

Returns#

CowReSynchSubProtocol: The cow’s ReSynch program information.

Raises#

TypeError: If the animal type is not a cow.

property sold: bool#

Checks if the object is sold based on the presence and value of sold_at_day.

Returns#

bool: True if sold_at_day is not None and greater than or equal to 0, otherwise False.

property dead: bool#

Check if the object is considered dead based on its dead_at_day attribute.

Returns#

bool: True if dead_at_day is not None and greater than or equal to 0, indicating the object is no longer alive. False otherwise.

_assign_sex_to_newborn_calf() → None#

Assign a sex to a newborn calf based on the semen type and male calf rate.

Determines the sex of the calf by evaluating the type of semen used (conventional or sexed) and the corresponding male calf rate. Raises a ValueError if an unexpected semen type is encountered.

Raises#

ValueError: If AnimalConfig.semen_type is not “conventional” or “sexed”.

_initialize_newborn_calf(args: NewBornCalfValuesTypedDict, simulation_day: int) → None#

Initialize a newborn calf with specific attributes and simulation variables.

Parameters#

argsNewBornCalfValuesTypedDict: A dictionary containing values related to the newborn calf. Expected keys include ‘birth_weight’ and ‘initial_phosphorus’.
simulation_dayint: The current day in the simulation, used for event logging and status evaluation.

_initialize_calf_or_heiferI(args: CalfValuesTypedDict | HeiferIValuesTypedDict) → None#

Initializes the attributes of a calf or heifer.

Parameters#

argsCalfValuesTypedDict or HeiferIValuesTypedDict: A dictionary containing initial values for the calf or heifer instance.

_determine_heifer_reproduction_programs(args: HeiferIIValuesTypedDict | HeiferIIIValuesTypedDict) → tuple[HeiferReproductionProtocol, HeiferTAISubProtocol | HeiferSynchEDSubProtocol]#

Determines the reproduction program and sub-program for a heifer.

Parameters#

argsHeiferIIValuesTypedDict or HeiferIIIValuesTypedDict: A dictionary containing information about the heifer reproduction program and sub-program.

Returns#

tuple (HeiferReproductionProtocol, HeiferTAISubProtocol | HeiferSynchEDSubProtocol): A tuple where the first element is the determined heifer reproduction program and the second element is the corresponding sub-program for the specified reproduction program.

_initialize_heiferII_or_heiferIII(args: HeiferIIValuesTypedDict | HeiferIIIValuesTypedDict) → None#

Initializes the attributes specific to a heifer in the HeiferII or HeiferIII stage.

Parameters#

argsHeiferIIValuesTypedDict or HeiferIIIValuesTypedDict: A dictionary-like object containing the attributes and values required for setting up the HeiferII or HeiferIII stage, including reproduction details and nutrient requirements.

Returns#

None

_initialize_cow(args: CowValuesTypedDict) → None#

Initializes the attributes of a cow object using the provided arguments.

Parameters#

argsCowValuesTypedDict: A dictionary containing values used for initializing the cow’s attributes.

Returns#

None

reduce_milk_production() → bool#

Attempts reduction of milk production.

Returns#

bool: True if the reduction was successful, False otherwise.

_daily_nutrients_update() → None#

Updates the daily nutrients requirements and performs phosphorus update.

This method compiles the daily nutrient inputs required for the animal based on its type, weight, growth, pregnancy stages, milk production, and other factors. It then triggers the process to update the animal’s phosphorus requirements.

_daily_digestive_system_update() → None#

Performs the daily digestive system updates for the animal.

This method gathers all relevant inputs related to the animal’s digestive system, including nutritional supply, metabolic energy intake, and milk production factors, into a DigestiveSystemInputs instance. It then passes these inputs to the process_digestion method of the digestive_system object, which simulates and calculates digestion-related processes for the day.

daily_milking_update(time: RufasTime) → None#

Performs the daily milk production update.

If the animal type is not a cow, the method exits without performing any operation. For cows, the method calculates the milking updates using the animal’s daily metrics and adjusts the milking-related data accordingly.

Parameters#

timeRufasTime: The current time context for the daily milking update.

daily_milking_update_without_history() → None#

Performs the daily milk production update without updating the milk production history attributes. Intended for use prior to first ration formulation interval, since that process requires the milk production to be set for proper estimation of animal requirements.

daily_growth_update(time: RufasTime) → None#

Updates the daily growth parameters of the animal based on the provided time input.

This method gathers the necessary animal attributes and performs the daily body weight update. It then updates attributes such as body weight, conceptual weight, and events of the animal accordingly.

Parameters#

timeRufasTime: The RufasTime instance used for updating growth and body weight changes.

_determine_days_in_milk(reproduction_output_days_in_milk: int) → int#

Determines the days in milk based on the values of the initial days_in_milk, milk production output days_in_milk and the reproduction output days_in_milk.

Parameters#

reproduction_output_days_in_milkint: The days_in_milk value from the reproduction update result.

Returns#

int: The determined days_in_milk.

Raises#

ValueError: If the days_in_milk attribute has an negative or invalid value.

Notes#

This method determines the days_in_milk value based on the following conditions:

If the animal is not lactating at the start of the day (`self.days_in_milk == 0`): - The method uses the days_in_milk value from the reproduction update. - This is because a dry cow (not lactating) always has days_in_milk = 0 in the milk production update. - However, if the animal gives birth that day, the reproduction update will set days_in_milk = 1.

If the animal is lactating at the start of the day (`self.days_in_milk > 0`): - In most cases, the method uses the days_in_milk value from the milk production update. - This is because the reproduction update does not change the days_in_milk for lactating cows. - The milk production update may either:

Increment days_in_milk by 1 (normal lactation progression).

Set days_in_milk to 0 if the animal is scheduled to dry off.

Edge case: If the animal dries off and gives birth on the same day: - The lactation cycle restarts, and days_in_milk is set to 1. - This occurs when:

The milk production update sets days_in_milk = 0 (indicating drying off).

The reproduction update sets days_in_milk = 1 (due to giving birth).

daily_reproduction_update(time: RufasTime) → tuple[NewBornCalfValuesTypedDict | None, HerdReproductionStatistics]#

Handles the daily reproduction state update for an animal.

Parameters#

timeRufasTime: The RufasTime instance for updating reproduction-related dynamics.

Returns#

NewBornCalfValuesTypedDict or None: A dictionary containing details related to a newly born calf if a calf is born during this update; otherwise, None.
HerdReproductionStatistics: A collection of statistical properties related to the animal’s reproduction lifecycle.

daily_routines(time: RufasTime) → DailyRoutinesOutput#

Perform daily routines for the animal, updating its status and outputs.

Parameters#

timeRufasTime: The RufasTime instance.

Returns#

DailyRoutinesOutput: An object containing the updated animal status and any newborn calf configuration.

_calf_life_stage_update(_: RufasTime) → tuple[AnimalStatus, None]#

Determines and updates the life stage of a calf based on specific evaluation criteria. Transitions the calf to the ‘HeiferI’ stage if the criteria are met, otherwise retains the current life stage.

Parameters#

_RufasTime: The RufasTime instance.

Returns#

tuple[AnimalStatus, None]: A tuple where the first value indicates whether the life stage was changed (AnimalStatus.LIFE_STAGE_CHANGED) or remains the same (AnimalStatus.REMAIN). The second value is always None.

_heiferI_life_stage_update(time: RufasTime) → tuple[AnimalStatus, None]#

Updates the life stage of a heiferI animal based on specific evaluation criteria. If the evaluation determines that the heiferI should transition to heiferII, the necessary transition is performed. Otherwise, the animal remains in its current life stage.

Parameters#

timeRufasTime: The RufasTime instance used for evaluation and transition.

Returns#

tuple[AnimalStatus, None]: AnimalStatus.LIFE_STAGE_CHANGED, None: If the heiferI transitions to the heifer II life stage. AnimalStatus.REMAIN, None: If the heiferI remains in the current life stage.

_heiferII_life_stage_update(time: RufasTime) → tuple[AnimalStatus, None]#

Updates the life stage of a heiferII based on evaluation criteria such as culling or transitioning to heiferIII. If the evaluation determines that the heiferII should transition to heiferIII, the necessary transition is performed. Otherwise, the animal remains in its current life stage.

Parameters#

timeRufasTime: The RufasTime object, used to determine the current simulation day.

Returns#

tuple[AnimalStatus, None]: A tuple containing the status of the animal (whether it is sold, its life stage has changed, or it remains in the current state) and None.

_heiferIII_life_stage_update(time: RufasTime) → tuple[AnimalStatus, NewBornCalfValuesTypedDict | None]#

Updates the life stage of a HeiferIII animal.

This function evaluates whether a HeiferIII animal should transition to the Cow life stage. If the animal transitions, configuration data for a newborn calf is returned. If the transition does not occur, the animal remains in the HeiferIII life stage, and no newborn calf data is provided.

Parameters#

timeRufasTime: The RufasTime instance used to evaluate the life stage transition.

Returns#

tuple[AnimalStatus, NewBornCalfValuesTypedDict | None]

A tuple containing the animal’s status: - AnimalStatus.LIFE_STAGE_CHANGED along with the newborn calf

configuration if the life stage transitions to Cow.

AnimalStatus.REMAIN and None if the animal stays in the HeiferIII stage.

_cow_life_stage_update(_: RufasTime) → tuple[AnimalStatus, None]#

Updates the life stage of a cow based on its milking status and current animal type.

Parameters#

_RufasTime: The RufasTime instance.

Returns#

tuple[AnimalStatus, None]: A tuple where the first element indicates whether the life stage has changed or remains the same, and the second element is always None.

animal_life_stage_update(time: RufasTime) → tuple[AnimalStatus, NewBornCalfValuesTypedDict | None]#

Updates the life stage of an animal based on its type and current simulation time.

Parameters#

timeRufasTime: The RufasTime instance used to determine life stage updates for the animal.

Returns#

tuple[AnimalStatus, NewBornCalfValuesTypedDict | None]: A tuple containing the updated animal status and, if applicable, configuration for a newborn calf.

_evaluate_calf_for_heiferI() → bool#

Evaluates if the calf qualifies as a heiferI based on its weaning day.

Returns#

bool: True if the calf has reached the weaning day as defined in AnimalConfig, False otherwise.

_evaluate_heiferI_for_heiferII() → bool#

Checks if heiferI is ready for heiferII stage based on the breeding start day.

Returns#

bool: True if the heiferI’s days born is equal to the configured heifer breed start day, False otherwise.

_evaluate_heiferII_for_heiferIII() → bool#

Evaluate if a heiferII can transition to heiferIII stage.

Returns#

bool: True if the heifer meets all the conditions to transition to heifer III, False otherwise.

_evaluate_heiferII_for_culling() → bool#

Determines whether a heiferII should be culled based on pregnancy status and age.

Returns#

bool: True if the heiferII is not pregnant and its age in days exceeds the culling threshold, False otherwise.

evaluate_heiferIII_for_cow() → bool#

Checks if a heiferIII has reached the expected gestation period, indicating it ready to become a cow.

Returns#

bool: True if the heiferIII is ready to become a cow; False otherwise.

_transition_calf_to_heiferI() → None#: Handles the transition of an animal from CALF to HEIFER_I stage.

_transition_heiferI_to_heiferII(time: RufasTime) → None#

Handles the transition of an animal from HEIFER_I to HEIFER_II stage.

Parameters#

timeRufasTime: The RufasTime object used to update reproduction information.

_transition_heiferII_to_heiferIII() → None#: Transitions the animal state from HEIFER II to HEIFER III.

transition_heiferIII_to_cow(time: RufasTime) → NewBornCalfValuesTypedDict#

Handles the transition of a HeiferIII to a Cow and initializes the necessary parameters for the cow.

Parameters#

timeRufasTime: The RufasTime object at which the transition occurs.

Returns#

NewBornCalfValuesTypedDict: A dictionary containing the configuration for the newly born calf.

Raises#

ValueError: Raised if the HeiferIII does not give birth to a calf during the transition to a cow.

get_animal_values() → CalfValuesTypedDict | HeiferIValuesTypedDict | HeiferIIValuesTypedDict | HeiferIIIValuesTypedDict | CowValuesTypedDict#

Get the attribute values of the animal.

Returns#

(CalfValuesTypedDict | HeiferIValuesTypedDict | HeiferIIValuesTypedDict | HeiferIIIValuesTypedDict |

CowValuesTypedDict): A dictionary containing key-value pairs specific to the current animal.

Raises#

KeyError: If the animal_type is not present in the mapping dictionary.

_get_calf_values() → CalfValuesTypedDict#

Get the attribute values for calf.

Returns#

CalfValuesTypedDict: A dictionary containing key-value pairs specific to the current animal.

_get_heiferI_values() → HeiferIValuesTypedDict#

Get the attribute values for heiferI.

Returns#

HeiferIValuesTypedDict: A dictionary containing key-value pairs specific to the current animal.

_get_heiferII_values() → HeiferIIValuesTypedDict#

Get the attribute values for heiferII.

Returns#

HeiferIIValuesTypedDict: A dictionary containing key-value pairs specific to the current animal.

_get_heiferIII_values() → HeiferIIIValuesTypedDict#

Get the attribute values for heiferIII.

Returns#

HeiferIIIValuesTypedDict: A dictionary containing key-value pairs specific to the current animal.

_get_cow_values() → CowValuesTypedDict#

Get the attribute values for cow.

Returns#

CowValuesTypedDict: A dictionary containing key-value pairs specific to the current animal.

determine_future_death_date() → int#

Determine the future death date of the animal based on its parity.

Returns#

int: Calculated future death date in simulation days.

Notes#

[AN.ANM.1]

determine_future_cull_date() → tuple[int, str]#

Determine the future cull date and reason for the animal based on parity-specific probabilities.

Returns#

tuple[int, str]: Future cull date in simulation days and reason for culling.

Notes#

[AN.ANM.2]

update_pen_history(current_pen: int, current_day: int, animal_types_in_pen: set[AnimalType]) → None#

Updates the animal’s pen history by either appending to the existing history if the animal is in a different pen than it was the last time this method is called or modifying the last element in the pen_history list to reflect the current simulation day.

Parameters#

current_pen: int: The id of the new pen that the animal is assigned to.
current_day: int: The current simulation day.
animal_types_in_pen: set[AnimalType]: The animal types in the new pen that the animal is assigned to.

set_daily_walking_distance(vertical_dist_to_parlor: float, horizontal_dist_to_parlor: float) → None#

Calculates and sets the animal’s daily vertical and horizontal walking distance (DVD and DHD).

Parameters#

vertical_dist_to_parlorfloat: Vertical distance to milking parlor (km).
horizontal_dist_to_parlorfloat: Horizontal distance to milking parlor (km).

set_nutrition_requirements(housing: str, walking_distance: float, previous_temperature: float, available_feeds: list[Feed]) → None#: Sets the nutrition requirements for an animal.

calculate_nutrition_requirements(housing: str, walking_distance: float, previous_temperature: float, available_feeds: list[Feed]) → NutritionRequirements#

Gets the nutrition requirements for an animal.

Parameters#

housingstr: The housing type of the animal, either “barn” or “grazing”.
walking_distancefloat: The walking distance to the milking parlor (m).
previous_temperaturefloat: The previous day’s temperature (C).
available_feedslist[Feed]: List of feeds available for ration formulation. Only needed for calf nutrition calculation.

Returns#

NutritionRequirements: The nutrition requirements for the animal.