cow_builder.digital_cow module#

module:

digital_cow

module author:

Gabe van den Hoeven

synopsis:

This module contains the DigitalCow class which represents a cow in a dairy herd, as well as some functions that it uses.

How To Use This Module#

(See the individual classes, methods, and attributes for details.)

Values in this HowTo are examples, see documentation of each class or function for details on the default values.

1. Import the classes DigitalCow and DigitalHerd:#

Import the classes from the modules digital_cow and digital_herd.

from cow_builder.digital_cow import DigitalCow
from cow_builder.digital_herd import DigitalHerd

2. Create a DigitalCow and DigitalHerd object:#

A DigitalCow object can be made without a DigitalHerd object, however it won’t have full functionality until a DigitalHerd is added as its herd.

  1. Without a DigitalHerd object:

    1. Without parameters:

      cow = DigitalCow()

    2. With parameters:

      cow = DigitalCow(days_in_milk=245, lactation_number=3,
days_pregnant=165, diet_cp_cu=160, diet_cp_fo=140, age=2079, state='Pregnant')

    These parameters may not be all available parameters. Look at each class’ documentation for details.

  2. With a DigitalHerd object:

    1. Without parameters:

      a_herd = DigitalHerd() cow = DigitalCow(herd=a_herd)

    2. With parameters:

      a_herd = DigitalHerd(vwp=(365, 90, 70), insemination_window=(110, 100, 90),
milk_threshold=12, duration_dry=(70, 50))
cow = DigitalCow(days_in_milk=67, lactation_number=1,
days_pregnant=0, diet_cp_cu=160, diet_cp_fo=140, age=767, herd=a_herd, state='Open')

    These parameters may not be all available parameters. Look at each class’ documentation for details.

  3. Set the herd of the DigitalCow:

    1. Sets the DigitalHerd as the herd of the DigitalCow:

      a_herd = DigitalHerd()
cow = DigitalCow(herd=a_herd)

    2. Overwrites the DigitalHerd as the herd of the DigitalCow:

      a_herd = DigitalHerd()
another_herd = DigitalHerd()
cow = DigitalCow(herd=a_herd)
cow.herd = another_herd

    There are other methods that alter the herd of the cow using functions from the ``DigitalHerd`` class. These are described in the ``digital_herd`` module.

3. Retrieving and altering instance variables:#

There are many variables in the DigitalCow class, all of which can be called.

  1. Retrieving property variables:

all instance variables are properties. They can be called like this:

a_cow = DigitalCow()
dim = a_cow.current_days_in_milk

  1. Altering property variables:

all instance variables can be altered like this:

a_cow = DigitalCow()
dim = 200
a_cow.current_days_in_milk = dim

4. Generate states for the DigitalCow object:#

Generate states for the cow with using the generate_total_states() function. If you use these to make a transition matrix, this will determine the size of the matrix and thus how far you can simulate.

The days_in_milk_limit parameter determines the maximum number of days within one lactation (The actual number can be less depending on the milk threshold). The lactation_number_limit is the maximum number of lactations that can be completed before culling.

  1. without parameters:

    cow.generate_total_state()

Here the days_in_milk_limit and lactation_number_limit variables from the herd are used.

  1. with parameters:

    cow.generate_total_states(dim_limit=750, ln_limit=9)

5. Using the state_probability_generator:#

The state_probability_generator() function takes a DigitalCow as a parameter. It goes through the states that have been generated and returns the probability of the cow moving from one state to another together with the indices of these states. This can be used together with the array_assembler function from the chain_simulator package to create a transition matrix.

::

from chain_simulator.assembly import array_assembler from cow_builder.digital_cow import state_probability_generator

tm = array_assembler(state_count=cow.node_count, probability_calculator=state_probability_generator(cow))

6. Using the vector phenotype functions:#

The vector phenotype functions are used to calculate phenotype values from a given vector of state probabilities. These functions can be passed to the simulation_accumulator function of the chain_simulator package in a dictionary. Parameters should be partially filled to allow the simulation_accumulator to access specific instance variables and functions.

from cow_builder.digital_cow import vector_milk_production, vector_nitrogen_emission
from functools import partial

callbacks = {
    "milk": partial(vector_milk_production, digital_cow=cow),
    "nitrogen": partial(vector_nitrogen_emission, digital_cow=cow)
}
class cow_builder.digital_cow.DigitalCow(days_in_milk=0, lactation_number=0, days_pregnant=0, diet_cp_cu=160, diet_cp_fo=140, milk_cp=3.4, age=0, herd=None, state='Open', age_at_first_heat=None)#

Bases: object

A digital twin representing a dairy cow.

Attributes:
var _herd:

The DigitalHerd instance representing the herd that the cow belongs to.

type _herd:

DigitalHerd

var _current_state:

The State instance representing the current state of the cow.

type _current_state:

State

var _age_at_first_heat:

The age in days, at which the cow had her first estrus. Defaults to None if it has not happened yet.

type _age_at_first_heat:

int | None

var __life_states:

A list of all possible life states the cow can be in.

type __life_states:

list[str]

var _total_states:

A tuple of State objects containing all possible states this cow can be in or transition to. Filled by self.generate_total_states().

type _total_states:

tuple[State] | None

var _milkbot_variables:

A tuple of 4 floats used for the self.milk_production function.

  • index = 0: scale

  • index = 1: ramp

  • index = 2: offset

  • index = 3: decay

Filled by self.__set_milkbot_variables().

type _milkbot_variables:

tuple[float]

Methods:

__init__(days_in_milk, lactation_number, days_pregnant, age_at_first_heat, herd, state, precision)

generate_total_states(dim_limit, ln_limit)

probability_state_change(state_from, state_to)

possible_new_states(state_from)

__init__(days_in_milk=0, lactation_number=0, days_pregnant=0, diet_cp_cu=160, diet_cp_fo=140, milk_cp=3.4, age=0, herd=None, state='Open', age_at_first_heat=None)#

Initializes a new instance of a DigitalCow object.

Parameters:

  • days_in_milk (int) – The number of days since the cow’s last calving, or it’s birth if it has not calved yet. Defaults to 0.

  • lactation_number (int) – The number of lactation cycles the cow has completed. Defaults to 0.

  • days_pregnant (int) – The number of days that the cow is pregnant. Defaults to 0.

  • age_at_first_heat (int | None) – The age in days, at which the cow had her first estrus. Defaults to None.

  • age (int) – The age of the cow in days. Defaults to 0.

  • herd (DigitalHerd | None) – The herd to which the cow belongs. Contains variables that apply to all cows in the herd. Defaults to None.

  • state (str) – The life state of the cow. This state should be one of the states defined in self.__life_states. Defaults to ‘Open’.

property age: int#

The age of the cow in days.

property age_at_first_heat: int | None#

The age in days at which the cow experienced its first heat.

property current_days_in_milk: int#

The current number of days since last calving, or the cow’s birth if it has not calved yet.

property current_days_pregnant: int#

The current number of days in pregnancy of the cow.

property current_lactation_number: int#

The current number of lactation cycles the cow has completed.

property current_life_state: str#

The current life_state the cow is in.

property current_milk_output: float#

The current milk output of the cow.

property current_state: State#

The current state of the cow, as a State object.

property diet_cp_cu: float#

The concentration of crude proteins in the diet of the cow in g.

property diet_cp_fo: float#

The concentration of crude proteins in the diet of the cow in g.

property edge_count: int#

The total number of possible transitions.

generate_total_states(dim_limit=None, ln_limit=None) → None#

Generates a tuple of State objects that represent all possible states of the DigitalCow instance.

Parameters:

  • dim_limit (int | None) – The limit of days in milk for which states should be generated. Defaults to the limit of its herd.

  • ln_limit (int | None) – The limit of lactation numbers for which states should be generated. Defaults to the limit of its herd.

property herd: DigitalHerd#

The herd object representing the herd of the cow.

property initial_state_vector: ndarray#

A numpy array indicating which state of all states in total_states the cow is in.

property milk_cp: float#

The concentration of crude proteins in the milk produced by the cow in g.

property milkbot_variables: tuple#

A tuple containing 4 parameters used to calculate milk output.

property node_count: int#

The total number of State objects in total_states.

possible_new_states(state_from: State) → tuple#

Returns a tuple with all states state_from can transition into.

Parameters:

state_from (State) – The state from which to transition.

Returns states_to:

A tuple containing all states that state_from can transition into.

Return type:

tuple[State]

Raises:

ValueError – If the state of state_from is not valid.

probability_state_change(state_from: State, state_to: State) → float#

Calculates the probability of transitioning from state_from to state_to.

Parameters:

  • state_from (State) – The state from which to transition.

  • state_to (State) – The state to transition into.

Returns:

The probability of transitioning from state_from to state_to.

Return type:

float

Raises:

ValueError – If the state is not defined in self.__life_states.

property total_states: tuple#

A generated tuple of State objects that the cow can be in.

cow_builder.digital_cow.calculate_body_weight(state: State, age: int) → float#

Calculates the body weight of a cow for a specific state.

Parameters:

  • state (State) – The State object that represents the specific day for which the body weight must be calculated.

  • age (int) – The age of the cow in days.

Returns:

The body weight of the cow in kg in the state that is given.

Return type:

float

cow_builder.digital_cow.calculate_dmi(state: State, body_weight: float)#

Calculates the dry matter intake of a cow for a specific state.

Parameters:

  • state (State) – The State object that represents the specific day for which the dry matter intake must be calculated.

  • body_weight – The body weight of the cow in kg on the specific day for which the dry matter intake must be calculated.

Returns:

The dry matter intake in kg for the specific state that is given.

Return type:

float

cow_builder.digital_cow.fecal_nitrogen_output(lactating: bool, dmi: float, nitrogen_intake: float)#

Returns the estimated daily nitrogen emission for a cow’s feces based on its nitrogen intake or dmi.

Parameters:

  • lactating (bool) – A boolean deciding which formulas to use based on whether the cow is lactating or not.

  • dmi (float) – The dry matter intake of the cow in kg per day.

  • nitrogen_intake (float) – The amount of nitrogen consumed by the cow in g per day.

Returns:

  • mu_n_output: The mean nitrogen output in g.

  • min_n_output: The minimum nitrogen output in g.

  • max_n_output: The maximum nitrogen output in g.

Return type:

  • mu_n_output: float

  • min_n_output: float

  • max_n_output: float

cow_builder.digital_cow.fecal_phosphor_output(phosphor_intake: float, milk_yield: float)#

Calculates the daily phosphor emission of a cow’s feces based on the cow’s phosphor intake and milk production.

Parameters:

  • phosphor_intake (float) – The amount of phosphor consumed by the cow in g per day.

  • milk_yield (float) – The milk production of the cow in kg per day.

Returns:

  • mu_p_output: The mean phosphor output in g.

  • min_p_output: The minimum phosphor output in g.

  • max_p_output: The maximum phosphor output in g.

Return type:

  • mu_p_output: float

  • min_p_output: float

  • max_p_output: float

cow_builder.digital_cow.manure_nitrogen_output(dmi: float, diet_cp: float, milk_yield: float, milk_cp: float)#

Returns the estimated daily nitrogen emission in manure for lactating cows when dry-matter intake, dietary crude protein concentration, milk yield and milk crude protein concentration are known.

Parameters:

  • dmi (float) – The dry-matter intake of the cow in kg.

  • diet_cp (float) – The dietary crude protein concentration in %.

  • milk_yield (float) – The milk output of the cow in kg.

  • milk_cp (float) – The crude protein concentration in the milk of the cow in %.

Returns:

Manure nitrogen output in g.

Return type:

float

cow_builder.digital_cow.milk_nitrogen_output(dmi: float)#

Returns the estimated daily nitrogen output in a cow’s milk based on its dry matter intake.

Parameters:

dmi (float) – The dry matter intake of the cow in kg per day.

Returns:

  • mu_n_output: The mean nitrogen output in g.

  • min_n_output: The minimum nitrogen output in g.

  • max_n_output: The maximum nitrogen output in g.

Return type:

  • mu_n_output: float

  • min_n_output: float

  • max_n_output: float

cow_builder.digital_cow.milk_production(milkbot_variables: tuple, state: State, dp_limit: int, duration_dry: int) → float#

Calculates milk production for a given state using the MilkBot algorithm.

Parameters:

  • milkbot_variables (tuple) – A tuple containing parameters for the MilkBot algorithm.

  • state (State) – A State object for which milk production must be calculated.

  • dp_limit (int) – The maximum number of days a cow can be pregnant.

  • duration_dry (int) – The number of days before calving when a cow is not being milked, otherwise known as the Dry period.

Returns:

The milk production for the given days in milk in kg.

Return type:

float

cow_builder.digital_cow.set_korver_function_variables(lactation_number: int)#

Returns a set of variables used for a heifer body weight function and the Korver function based on a given lactation number.

Parameters:

lactation_number (int) – The lactation number of a cow.

Returns:

  • birth_weight: The weight of the cow at birth in kg.

  • mature_live_weight: The weight of a mature cow in kg.

  • growth_rate: A variable that describes the speed at which the weight of

    the cow increases.

  • pregnancy_parameter: A variable that describes that decrease in weight of

    the cow after calving.

  • max_decrease_live_weight: The maximum decrease in live weight during a

    lactation cycle in kg.

  • duration_minimum_live_weight: The number of days for which the live weight

    is lowest.

Return type:

  • birth_weight: float

  • mature_live_weight: float | None

  • growth_rate: float

  • pregnancy_parameter: float | None

  • max_decrease_live_weight: float | None

  • duration_minimum_live_weight: float | None

cow_builder.digital_cow.set_milkbot_variables(lactation_number: int) → tuple#

Returns MilkBot variables for a DigitalCow, based on its lactation number.

Parameters:

lactation_number (int) – The number of lactation cycles the cow has completed.

Returns:

A tuple of parameters for the MilkBot function.

  • index = 1: scale

  • index = 2: ramp

  • index = 3: offset

  • index= 4: decay

Return type:

tuple[float]

Raises:

ValueError – If the lactation number is larger than the lactation number limit.

cow_builder.digital_cow.state_probability_generator(digital_cow: DigitalCow) → Generator[tuple[int, int, float], None, None]#

A generator that iterates over a tuple of states. It determines the states each state can transition into, and calculates the probability of the state change for each pair. It returns the indexes of the state pair in the tuple of states and their probability.

Parameters:

digital_cow (DigitalCow) – A DigitalCow object for which the states are generated and transition probabilities must be calculated.

Returns:

  • state_index[state_from]: The index of the state_from state in the

    tuple of states.

  • state_index[state_to]: The index of the state_to state in the tuple of

    states.

  • probability: The probability of moving from state_from to state_to.

Return type:

  • state_index[state_from]: int

  • state_index[state_to]: int

  • probability: float

cow_builder.digital_cow.total_manure_nitrogen_output(lactating: bool, nitrogen_intake: float)#

Returns estimated daily nitrogen emission of a cow’s manure (urine and feces) based on its nitrogen intake.

Parameters:

  • lactating (bool) – A boolean deciding which formulas to use based on whether the cow is lactating or not.

  • nitrogen_intake (float) – The amount of nitrogen consumed by the cow in g per day.

Returns:

  • mu_n_output: The mean nitrogen output in g.

  • min_n_output: The minimum nitrogen output in g.

  • max_n_output: The maximum nitrogen output in g.

Return type:

  • mu_n_output: float

  • min_n_output: float

  • max_n_output: float

cow_builder.digital_cow.urine_nitrogen_output(lactating: bool, nitrogen_intake: float)#

Returns the estimated daily nitrogen emission for a cow’s urine based on its nitrogen intake.

Parameters:

  • lactating (bool) – A boolean deciding which formulas to use based on whether the cow is lactating or not.

  • nitrogen_intake (float) – The amount of nitrogen consumed by the cow in g per day.

Returns:

  • mu_n_output: The mean nitrogen output in g.

  • min_n_output: The minimum nitrogen output in g.

  • max_n_output: The maximum nitrogen output in g.

Return type:

  • mu_n_output: float

  • min_n_output: float

  • max_n_output: float

cow_builder.digital_cow.vector_milk_production(vector: ndarray, step_in_time: int, step_size: int, digital_cow: DigitalCow, intermediate_accumulator: dict[int, float] | None)#

A function that calculates the milk production of a cow digital_cow, on a given day in simulation step_in_time, using a vector of state probabilities. The milk production is multiplied with step_size to extrapolate the milk production until the next step_in_time. If an intermediate_accumulator is given, milk production is also saved in that dictionary.

Parameters:

  • vector (np.ndarray) – A vector of state probabilities that represents the probability of the cow being in each state at the current time in the simulation.

  • step_in_time (int) – The current day in the simulation.

  • step_size (int) – The interval in days for which phenotype values are calculated during the simulation.

  • digital_cow (DigitalCow) – The representation of the cow that is being simulated.

  • intermediate_accumulator (dict[int, float] | None) – A dictionary that stores the milk production of each day in the simulation for which phenotype values are calculated.

:return The milk production of the current day in simulation extrapolated until the next step_in_time. :rtype: float

cow_builder.digital_cow.vector_nitrogen_emission(vector: ndarray, step_in_time: int, step_size: int, digital_cow: DigitalCow, intermediate_accumulator: dict[int, float] | None)#

A function that calculates the nitrogen emission of a cow digital_cow, on a given day in simulation step_in_time, using a vector of state probabilities. The nitrogen emission is multiplied with step_size to extrapolate the nitrogen emission until the next step_in_time. If an intermediate_accumulator is given, nitrogen emission is also saved in that dictionary.

Parameters:

  • vector (np.ndarray) – A vector of state probabilities that represents the probability of the cow being in each state at the current time in the simulation.

  • step_in_time (int) – The current day in the simulation.

  • step_size (int) – The interval in days for which phenotype values are calculated during the simulation.

  • digital_cow (DigitalCow) – The representation of the cow that is being simulated.

  • intermediate_accumulator (dict[int, float] | None) – A dictionary that stores the nitrogen emission of each day in the simulation for which phenotype values are calculated.

Returns:

The nitrogen emission of the current day in simulation extrapolated until the next step_in_time.

Return type:

float