cow_builder.digital_herd module#

module:: digital_herd
module author:: Gabe van den Hoeven
synopsis:: This module contains the DigitalHerd class representing a dairy herd.

How To Use This Module#

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

This module is to be used in conjunction with the DigitalCow class. The DigitalHerd contains certain variables used by the DigitalCow class for simulation purposes. These variables are the same for all DigitalCow instances in the herd.

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

1. Import the class DigitalHerd:#

Import the class with:

from cow_builder.digital_herd import DigitalHerd

2. Create a DigitalHerd instance:#

Since default values are provided for the DigitalHerd class, it can be created as follows:

without parameters:
```
new_herd = DigitalHerd()
```

with parameters:

new_herd = DigitalHerd(milk_threshold=5)

For details about the parameters, look at the __init__ method.

3. Retrieve instance variables:#

There are many variables in the DigitalHerd class, all of which can be called. A few use a different method of calling the variable.

Normal property variables:

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

a_herd = DigitalHerd()
milk_threshold = a_herd.milk_threshold

Variables using getters and setters:

Some variables use custom getters and setters because the property decoration does not allow parameters in getters. These can be called like this:

a_herd = DigitalHerd()
lactation_number = 1
vwp = a_herd.get_voluntary_waiting_period(lactation_number)

The special getters and setters can be found in the Methods section of the DigitalHerd class documentation.

4. Alter the herd:#

There are a few different methods that can be used to alter the herd list of a DigitalHerd instance. These alterations will also affect the DigitalCow objects that are added or removed from the herd.

1) Adds the DigitalCow objects to the DigitalHerd and sets the DigitalHerd as the herd of each DigitalCow:

a_herd = DigitalHerd()
cow = DigitalCow()
cow2 = DigitalCow()
a_herd.add_to_herd(cows=[cow, cow2])

Removes the DigitalCow objects from the DigitalHerd and sets the herd of each DigitalCow to None:

a_herd = DigitalHerd()
cow = DigitalCow(herd=a_herd)
cow2 = DigitalCow(herd=a_herd)
a_herd.remove_from_herd(cows=[cow, cow2])

3) Overwrites the list of DigitalCow objects as the herd of the DigitalHerd and the DigitalHerd as the herd of each DigitalCow in the list:

a_herd = DigitalHerd()
cow = DigitalCow()
cow2 = DigitalCow()
a_herd.herd = [cow, cow2]

5. Alter other instance variables:#

There are many variables in the DigitalHerd class, all of which can be altered. A few use a different method of alteration.

1) Normal property variables: Most instance variables are properties. They can be changed like this:

a_herd = DigitalHerd()
milk_threshold = 15
a_herd.milk_threshold = milk_threshold

2) Variables using getters and setters: Some variables use custom getters and setters because the property decoration does not allow parameters in getters. These can be changed like this:

a_herd = DigitalHerd()
vwp = (370, 90, 50)
a_herd.set_voluntary_waiting_period(vwp)

The special getters and setters can be found in the Methods section of the DigitalHerd class documentation.

class cow_builder.digital_herd.DigitalHerd(vwp=(365, 80, 60), insemination_window=(100, 100, 100), milk_threshold=10, days_in_milk_limit=1000, lactation_number_limit=9, days_pregnant_limit=(279, 280, 282), duration_dry=(60, 60), mu_age_at_first_heat=365, sigma_age_at_first_heat=0)#

Bases: object

A class to represent a herd of cows and manage their properties.

Attributes:

var _mu_age_at_first_heat:: The mean age in days at which a cow will experience its first estrus.
type _mu_age_at_first_heat:: int
var _sigma_age_at_first_heat:: The standard deviation in days to generate an age at which a cow will experience its first estrus.
type _sigma_age_at_first_heat:: int
var _voluntary_waiting_period:: The voluntary waiting period in days before a cow can be inseminated. Values in the tuple are for lactation 0, 1, and 2+.
type _voluntary_waiting_period:: tuple[int]
var _milk_threshold:: The minimum milk production in kg to be considered as a productive cow.
type _milk_threshold:: float
var _insemination_window:: The number of days in milk since the voluntary waiting period after which a cow is no longer eligible for insemination. Values in the tuple are for lactation 0, 1, and 2+.
type _insemination_window:: tuple[int]
var _herd:: A list of DigitalCow objects representing the cows in the herd.
type _herd:: list[DigitalCow]
var _days_in_milk_limit:: The maximum number of days since calving or birth a cow can have before being culled.
type _days_in_milk_limit:: int
var _lactation_number_limit:: The maximum number of lactation cycles a cow can have completed before being culled.
type _lactation_number_limit:: int
var _days_pregnant_limit:: The maximum number of days a cow can be pregnant. Values in the tuple are for lactation 0, 1, and 2+.
type _days_pregnant_limit:: tuple[int]
var _duration_dry:: The number of days before calving, when a cow is not being milked. Values in the tuple are for lactation 1 and 2+.
type _duration_dry:: tuple[int]

Methods:

__init__(mu_age_at_first_heat, sigma_age_at_first_heat, vwp, insemination_window, milk_threshold, days_in_milk_limit, lactation_number_limit, days_pregnant_limit, duration_dry)

add_to_herd(cows)

remove_from_herd(cows)

calculate_mu_age_at_first_heat()

generate_age_at_first_heat()

get_voluntary_waiting_period(lactation_number)

set_voluntary_waiting_period(vwp)

get_insemination_window(lactation_number)

set_insemination_window(dim_window)

get_days_pregnant_limit(lactation_number)

set_days_pregnant_limit(limit)

get_duration_dry(lactation_number)

set_duration_dry(duration_dry)

__init__(vwp=(365, 80, 60), insemination_window=(100, 100, 100), milk_threshold=10, days_in_milk_limit=1000, lactation_number_limit=9, days_pregnant_limit=(279, 280, 282), duration_dry=(60, 60), mu_age_at_first_heat=365, sigma_age_at_first_heat=0)#

Initializes an instance of a DigitalHerd object.

Parameters:

vwp (tuple[int]) – The voluntary waiting period in days before a cow can be inseminated. Values in the tuple are for lactation 0, 1, and 2+.
insemination_window (tuple[int]) – The insemination window in days after which a cow is no longer eligible for insemination. Values in the tuple are for lactation 0, 1, and 2+.
milk_threshold (float) – The minimum milk production in kg to be considered as a productive cow. Default is 10.
days_in_milk_limit (int) – The maximum number of days a cow can be in milk before being culled. Default is 1000.
lactation_number_limit (int) – The maximum number of lactation cycles a cow can have completed before being culled. Default is 9.
days_pregnant_limit (tuple[int]) – The maximum number of days a cow can be pregnant. Values in the tuple are for lactation 0, 1, and 2+.
duration_dry (tuple[int]) – The number of days before calving, when a cow is not being milked. Values in the tuple are for lactation 1 and 2+.
mu_age_at_first_heat (int) – The mean age in days at which a cow will experience its first estrus.
sigma_age_at_first_heat (int) – The standard deviation used to generate an age at which a cow will experience its first estrus.

add_to_herd(cows: list) → None#

Takes a list of DigitalCow objects and adds each cow to the herd if they are not in the herd already.

Parameters:: cows (list[DigitalCow]) – A list of DigitalCow objects which are to be added to the herd.
Raises:: TypeError – If the list given does not solely consist of DigitalCow objects.

calculate_mu_age_at_first_heat()#: Calculates the mean age in days at which a cow in the herd will experience its first estrus.

property days_in_milk_limit: int#: The maximum number of days after calving or birth before being culled.

generate_age_at_first_heat() → int#

Returns a random age at first heat based on the mean age at first heat and its standard deviation.

Returns:: A random age the cow will have her first heat, based on the mean age at first heat and its standard deviation.
Return type:: int

get_days_pregnant_limit(lactation_number: int) → int#

Returns the number of days a cow can be pregnant for a given lactation number.

Parameters:: lactation_number (int) – The number of lactation cycles the cow has completed.
Returns:: The number of days a cow can be pregnant for the given lactation number.
Return type:: int

get_duration_dry(lactation_number) → int#

Returns the dry period for a cow in the herd based on a given lactation number.

Parameters:: lactation_number (int) – The number of lactation cycles the cow has completed.
Returns:: The dry period in days for a cow in the given lactation cycle.
Return type:: int

get_insemination_window(lactation_number: int) → int#

Returns the insemination window of a cow in the herd for a given lactation number.

Parameters:: lactation_number (int) – The number of lactation cycles the cow has completed.
Returns:: The insemination window in days.
Return type:: int

get_voluntary_waiting_period(lactation_number: int) → int#

Returns the voluntary waiting period of a cow in the herd for a given lactation number.

Parameters:: lactation_number (int) – The number of lactation cycles the cow has completed.
Returns:: The voluntary waiting period in days.
Return type:: int

property herd: list#: A list of DigitalCow objects that represents all the cows in the herd.

property lactation_number_limit: int#: The maximum number of lactation cycles a cow can complete before being culled.

property milk_threshold: float#: The milk threshold for all cows in the herd. If the milk production falls below this threshold, they will be culled.

property mu_age_at_first_heat#: The mean age in days at which a cow in the herd will experience its first estrus.

remove_from_herd(cows: list) → None#

Takes a list of DigitalCow objects and removes each cow from the herd if they are present in the herd.

Parameters:: cows (list[DigitalCow]) – A list of DigitalCow objects which are to be removed from the herd.
Raises:: TypeError – If the list given does not solely consist of DigitalCow objects.

set_days_pregnant_limit(limit: tuple[int])#

Sets the maximum number of days a cow in the herd can be pregnant.

Parameters:: limit (tuple[int]) – A tuple containing limits for number of days a cow can be pregnant. Values in the tuple are for lactation 0, 1, and 2+.
Raises:: TypeError – If not all items in the limit parameter are of type int.

set_duration_dry(duration_dry: tuple[int])#

Sets the dry periods for all cows in the herd.

Parameters:: duration_dry (tuple[int]) – A tuple containing the length of dry periods for cow with a specific lactation number. Values in the tuple are for lactation 1 and 2+.
Raises:: TypeError – If not all items in the duration_dry parameter are of type int.

set_insemination_window(dim_window: tuple[int])#

Sets the insemination windows for cows in the herd.

Parameters:: dim_window (tuple[int]) – A tuple with insemination windows in days when a cow can be inseminated. Values in the tuple are for lactation 0, 1, and 2+.
Raises:: TypeError – If not all items in the dim_window parameter are of type int.

set_voluntary_waiting_period(vwp: tuple[int])#

Sets the voluntary waiting periods for cows in the herd.

Parameters:: vwp (tuple[int]) – A tuple with the voluntary waiting periods in days before a cow can be inseminated. Values in the tuple are for lactation 0, 1, and 2+.
Raises:: TypeError – If not all items in the vwp parameter are of type int.

property sigma_age_at_first_heat#: The standard deviation of the age at which a cow will experience its first estrus.