[Animal] Adds farm-specific genetic distribution inputs to herd_information

RUFAS/biophysical/animal/animal_config.py

@@ -192,6 +192,33 @@ class AnimalConfig:
         Semen sire information used for genetic simulations and breeding selection.
     simulate_genetics : bool
         Whether genetic simulation functionality is enabled.
+    tbv_fat_std : float
+        Standard deviation of the true breeding value (TBV) for fat yield in the herd, (kg). Defaults to the
+        CDCB national average.
+    tbv_protein_std : float
+        Standard deviation of the true breeding value (TBV) for protein yield in the herd, (kg). Defaults to
+        the CDCB national average.
+    tbv_correlation : float
+        Correlation between the fat and protein true breeding values, (unitless). Defaults to the CDCB
+        national average.
+    permanent_environment_fat_std : float
+        Standard deviation of the permanent environmental effect on fat yield in the herd, (kg). Defaults to
+        the CDCB national average.
+    permanent_environment_protein_std : float
+        Standard deviation of the permanent environmental effect on protein yield in the herd, (kg). Defaults
+        to the CDCB national average.
+    permanent_environment_correlation : float
+        Correlation between the fat and protein permanent environmental effects, (unitless). Defaults to the
+        CDCB national average.
+    temporary_environment_fat_std : float
+        Standard deviation of the temporary environmental effect on fat yield in the herd, (kg). Defaults to
+        the CDCB national average.
+    temporary_environment_protein_std : float
+        Standard deviation of the temporary environmental effect on protein yield in the herd, (kg). Defaults
+        to the CDCB national average.
+    temporary_environment_correlation : float
+        Correlation between the fat and protein temporary environmental effects, (unitless). Defaults to the
+        CDCB national average.
 
     """
 
@@ -399,6 +426,15 @@ class AnimalConfig:
     average_phenotype: dict[str, dict[int, float]] = {}
     top_listing_semen: dict[str, dict[str, float]] = {}
     simulate_genetics: bool = False
+    tbv_fat_std: float = 25.8
+    tbv_protein_std: float = 13.4
+    tbv_correlation: float = 0.59
+    permanent_environment_fat_std: float = 38.8
+    permanent_environment_protein_std: float = 20.1
+    permanent_environment_correlation: float = 0.95
+    temporary_environment_fat_std: float = 64.5
+    temporary_environment_protein_std: float = 33.4
+    temporary_environment_correlation: float = 0.78
 
     @classmethod
     def initialize_animal_config(cls) -> None:
@@ -588,3 +624,14 @@ def initialize_animal_config(cls) -> None:
             if trait != "year_month"
         }
         cls.simulate_genetics = animal_data["herd_information"]["simulate_genetics"]
+
+        genetics_data = animal_data["genetics"]
+        cls.tbv_fat_std = genetics_data["tbv_fat_std"]
+        cls.tbv_protein_std = genetics_data["tbv_protein_std"]
+        cls.tbv_correlation = genetics_data["tbv_correlation"]
+        cls.permanent_environment_fat_std = genetics_data["permanent_environment_fat_std"]
+        cls.permanent_environment_protein_std = genetics_data["permanent_environment_protein_std"]
+        cls.permanent_environment_correlation = genetics_data["permanent_environment_correlation"]
+        cls.temporary_environment_fat_std = genetics_data["temporary_environment_fat_std"]
+        cls.temporary_environment_protein_std = genetics_data["temporary_environment_protein_std"]
+        cls.temporary_environment_correlation = genetics_data["temporary_environment_correlation"]

RUFAS/biophysical/animal/animal_genetics/animal_genetics.py

@@ -7,15 +7,6 @@
 from RUFAS.biophysical.animal.data_types.animal_types import AnimalType
 from RUFAS.util import Utility
 
-TBV_FAT_STD = 25.8
-TBV_PROTEIN_STD = 13.4
-TBV_CORRELATION = 0.59
-E_PERMANENT_FAT_STD = 38.8
-E_PERMANENT_PROTEIN_STD = 20.1
-E_PERMANENT_CORRELATION = 0.95
-E_TEMPORARY_FAT_STD = 64.5
-E_TEMPORARY_PROTEIN_STD = 33.4
-E_TEMPORARY_CORRELATION = 0.78
 FAT_ACCURACY_BY_PARITY = {0: 0.75, 1: 0.80, 2: 0.85, 3: 0.90}
 PROTEIN_ACCURACY_BY_PARITY = {0: 0.75, 1: 0.80, 2: 0.85, 3: 0.90}
 
@@ -38,6 +29,10 @@ class Genetics:
     """
     Genetic attributes of an animal.
 
+    The standard deviations and correlations of the true breeding value, permanent environmental effect, and
+    temporary environmental effect distributions are read from ``AnimalConfig``, where they are user inputs in
+    the ``genetics`` section of the animal input that default to the CDCB national averages.
+
     Attributes
     ----------
     TBV_fat : float
@@ -157,9 +152,9 @@ def recalculate_values_at_lactation_start(
         self.ranking_index = self._calculate_ranking_index()
 
     def _calculate_tbv_values(self) -> tuple[float, float]:
-        """Calculate TBV values for an animal entering the herd."""
+        """Calculate TBV values for an animal entering the herd using the herd-level TBV distribution."""
         tbv_fat, tbv_protein = Utility.generate_bivariate_random_numbers(
-            0.0, 0.0, TBV_FAT_STD, TBV_PROTEIN_STD, TBV_CORRELATION
+            0.0, 0.0, AnimalConfig.tbv_fat_std, AnimalConfig.tbv_protein_std, AnimalConfig.tbv_correlation
         )
         return tbv_fat, tbv_protein
 
@@ -205,31 +200,37 @@ def _calculate_newborn_calf_tbv_values(
             else:
                 self.om.add_error("Newborn calf tbv calculation key error.", str(key_error), info_map)
                 raise key_error
-        std_tbv_fat_national_average, std_tbv_protein_national_average = TBV_FAT_STD, TBV_PROTEIN_STD
-
         mean_tbv_fat = (tbv_fat_top_semen + dam_tbv_fat) / 2
         mean_tbv_protein = (tbv_protein_top_semen + dam_tbv_protein) / 2
 
-        std_tbv_fat = np.sqrt(std_tbv_fat_national_average**2 / 2)
-        std_tbv_protein = np.sqrt(std_tbv_protein_national_average**2 / 2)
+        std_tbv_fat = np.sqrt(AnimalConfig.tbv_fat_std**2 / 2)
+        std_tbv_protein = np.sqrt(AnimalConfig.tbv_protein_std**2 / 2)
 
         tbv_fat, tbv_protein = Utility.generate_bivariate_random_numbers(
-            mean_tbv_fat, mean_tbv_protein, std_tbv_fat, std_tbv_protein, TBV_CORRELATION
+            mean_tbv_fat, mean_tbv_protein, std_tbv_fat, std_tbv_protein, AnimalConfig.tbv_correlation
         )
 
         return tbv_fat, tbv_protein
 
     def _calculate_ep_values(self) -> tuple[float, float]:
-        """Calculate Permanent Environment Effect (E_permanent) values."""
+        """Calculate Permanent Environment Effect (E_permanent) values using the herd-level distribution."""
         ep_fat, ep_protein = Utility.generate_bivariate_random_numbers(
-            0.0, 0.0, E_PERMANENT_FAT_STD, E_PERMANENT_PROTEIN_STD, E_PERMANENT_CORRELATION
+            0.0,
+            0.0,
+            AnimalConfig.permanent_environment_fat_std,
+            AnimalConfig.permanent_environment_protein_std,
+            AnimalConfig.permanent_environment_correlation,
         )
         return ep_fat, ep_protein
 
     def _calculate_et_values(self) -> tuple[float, float]:
-        """Calculate Temporary Environment Effect (E_temporary) values."""
+        """Calculate Temporary Environment Effect (E_temporary) values using the herd-level distribution."""
         et_fat, et_protein = Utility.generate_bivariate_random_numbers(
-            0.0, 0.0, E_TEMPORARY_FAT_STD, E_TEMPORARY_PROTEIN_STD, E_TEMPORARY_CORRELATION
+            0.0,
+            0.0,
+            AnimalConfig.temporary_environment_fat_std,
+            AnimalConfig.temporary_environment_protein_std,
+            AnimalConfig.temporary_environment_correlation,
         )
         return et_fat, et_protein
 
@@ -319,8 +320,8 @@ def _calculate_ebv_values(
             protein_accuracy**2
         )
 
-        std_ebv_fat = np.sqrt((1 - fat_accuracy**2) * (fat_accuracy**2) * TBV_FAT_STD)
-        std_ebv_protein = np.sqrt((1 - protein_accuracy**2) * (protein_accuracy**2) * TBV_PROTEIN_STD)
+        std_ebv_fat = np.sqrt((1 - fat_accuracy**2) * (fat_accuracy**2) * AnimalConfig.tbv_fat_std)
+        std_ebv_protein = np.sqrt((1 - protein_accuracy**2) * (protein_accuracy**2) * AnimalConfig.tbv_protein_std)
 
         noise_ebv_fat = np.random.normal(0.0, std_ebv_fat)
         noise_ebv_protein = np.random.normal(0.0, std_ebv_protein)

RUFAS/input/metadata/properties/default.json

@@ -160,6 +160,67 @@
         "default": false
       }
     },
+    "genetics": {
+      "type": "object",
+      "description": "Genetics -- Farm-specific standard deviations and correlations of the genetic distributions used when simulate_genetics is true. Omitted values default to the CDCB national averages",
+      "tbv_fat_std": {
+        "type": "number",
+        "description": "True Breeding Value Fat Standard Deviation (kg) -- The standard deviation of the true breeding value (TBV) for fat yield in the herd. Defaults to the CDCB national average",
+        "default": 25.8,
+        "minimum": 0
+      },
+      "tbv_protein_std": {
+        "type": "number",
+        "description": "True Breeding Value Protein Standard Deviation (kg) -- The standard deviation of the true breeding value (TBV) for protein yield in the herd. Defaults to the CDCB national average",
+        "default": 13.4,
+        "minimum": 0
+      },
+      "tbv_correlation": {
+        "type": "number",
+        "description": "True Breeding Value Correlation (unitless) -- The correlation between the fat and protein true breeding values (TBV). Defaults to the CDCB national average",
+        "default": 0.59,
+        "minimum": -1,
+        "maximum": 1
+      },
+      "permanent_environment_fat_std": {
+        "type": "number",
+        "description": "Permanent Environmental Effect Fat Standard Deviation (kg) -- The standard deviation of the permanent environmental effect on fat yield in the herd. Defaults to the CDCB national average",
+        "default": 38.8,
+        "minimum": 0
+      },
+      "permanent_environment_protein_std": {
+        "type": "number",
+        "description": "Permanent Environmental Effect Protein Standard Deviation (kg) -- The standard deviation of the permanent environmental effect on protein yield in the herd. Defaults to the CDCB national average",
+        "default": 20.1,
+        "minimum": 0
+      },
+      "permanent_environment_correlation": {
+        "type": "number",
+        "description": "Permanent Environmental Effect Correlation (unitless) -- The correlation between the fat and protein permanent environmental effects. Defaults to the CDCB national average",
+        "default": 0.95,
+        "minimum": -1,
+        "maximum": 1
+      },
+      "temporary_environment_fat_std": {
+        "type": "number",
+        "description": "Temporary Environmental Effect Fat Standard Deviation (kg) -- The standard deviation of the temporary environmental effect on fat yield in the herd. Defaults to the CDCB national average",
+        "default": 64.5,
+        "minimum": 0
+      },
+      "temporary_environment_protein_std": {
+        "type": "number",
+        "description": "Temporary Environmental Effect Protein Standard Deviation (kg) -- The standard deviation of the temporary environmental effect on protein yield in the herd. Defaults to the CDCB national average",
+        "default": 33.4,
+        "minimum": 0
+      },
+      "temporary_environment_correlation": {
+        "type": "number",
+        "description": "Temporary Environmental Effect Correlation (unitless) -- The correlation between the fat and protein temporary environmental effects. Defaults to the CDCB national average",
+        "default": 0.78,
+        "minimum": -1,
+        "maximum": 1
+      }
+    },
     "herd_initialization": {
       "type": "object",
       "description": "Animal generation related inputs",

changelog_WIP.md

@@ -121,6 +121,7 @@ This **WIP Changelog** records development changes in progress and not yet inclu
 - [3237](https://github.com/RuminantFarmSystems/RuFaS/pull/3237) - [minor change] [EEE] [NoInputChange] [NoOutputChange] Extracts repetitive logic from the farmgrown feed emissions calculation and reporting functions.
 - [3223](https://github.com/RuminantFarmSystems/RuFaS/pull/3223) - [minor change] [PostProcessing] [OutputManager] [NoInputChange] [NoOutputChange] Establishes new overhauled version of OutputManager and the subclasses it oversees.
 - [3235](https://github.com/RuminantFarmSystems/RuFaS/pull/3235) - [minor change] [Dependabot] [NoInputChange] [NoOutputChange] Updates file-target of dependabot-change PRs for tagging dev-team members for review.
+- [3257](https://github.com/RuminantFarmSystems/RuFaS/pull/3257) - [minor change] [Animal] [InputChange] [NoOutputChange] Adds optional farm-specific standard deviation and correlation inputs for the TBV, permanent, and temporary environmental effect genetic distributions to `herd_information`, defaulting to the CDCB national averages.
 - [3256](https://github.com/RuminantFarmSystems/RuFaS/pull/3256) - [minor change] [Branch Alignment] [NoInputChange] [NoOutputChange] Aligning `dev` branch with bug-fixing code from PR 3214 that was merged into `test`.
 - [3260](https://github.com/RuminantFarmSystems/RuFaS/pull/3260) - [minor change] [OutputManager] [NoInputChange] [NoOutputChange] Removes duplicative `report` naming mechanism in `OutputManager`.
 - [3275](https://github.com/RuminantFarmSystems/RuFaS/pull/3260) - [minor change] [E2E Testing] [NoInputChange] [NoOutputChange] Removes `deepdiff` check from the process to update e2e expected results.

input/data/animal/example_freestall_animal.json

@@ -22,6 +22,17 @@
     "annual_milk_yield": null,
     "simulate_genetics": false
   },
+  "genetics": {
+    "tbv_fat_std": 25.8,
+    "tbv_protein_std": 13.4,
+    "tbv_correlation": 0.59,
+    "permanent_environment_fat_std": 38.8,
+    "permanent_environment_protein_std": 20.1,
+    "permanent_environment_correlation": 0.95,
+    "temporary_environment_fat_std": 64.5,
+    "temporary_environment_protein_std": 33.4,
+    "temporary_environment_correlation": 0.78
+  },
   "herd_initialization": {
     "initial_animal_num": 10000,
     "simulation_days": 5000

input/data/animal/example_open_lot_animal.json

@@ -22,6 +22,17 @@
     "annual_milk_yield": 9928000,
     "simulate_genetics": false
   },
+  "genetics": {
+    "tbv_fat_std": 25.8,
+    "tbv_protein_std": 13.4,
+    "tbv_correlation": 0.59,
+    "permanent_environment_fat_std": 38.8,
+    "permanent_environment_protein_std": 20.1,
+    "permanent_environment_correlation": 0.95,
+    "temporary_environment_fat_std": 64.5,
+    "temporary_environment_protein_std": 33.4,
+    "temporary_environment_correlation": 0.78
+  },
   "herd_initialization": {
     "initial_animal_num": 10000,
     "simulation_days": 5000