lactationcurve.characteristics.test_interval_method

  1"""
  2ICAR 305-day yield calculation — Test Interval Method.
  3
  4This module implements the **Test Interval Method** described in ICAR guidelines
  5(Procedure 2, Section 2: Computing of Accumulated Lactation Yield) to compute
  6total **305-day milk yield** from test-day data.
  7
  8Approach
  9--------
 10- **Start segment**: Linear projection from calving (DIM=0) to the first test day.
 11- **Intermediate segments**: **Trapezoidal rule** between consecutive test days.
 12- **End segment**: Linear projection from the last test day to DIM=305 (exclusive
 13  upper bound 306 for day counting).
 14
 15Column Flexibility
 16------------------
 17The function can accept various column name aliases (case-insensitive) and
 18optionally create a default `TestId` if missing. Recognized aliases:
 19
 20- Days in Milk: `["daysinmilk", "dim", "testday"]`
 21- Milk Yield: `["milkingyield", "testdaymilkyield", "milkyield", "yield"]`
 22- Test Id: `["animalid", "testid", "id"]`
 23
 24Returns a DataFrame with columns: `["TestId", "Total305Yield"]`.
 25
 26Notes
 27-----
 28- Units: DIM in days, milk yield in kg.
 29- Records with `DIM > 305` are excluded prior to computation.
 30
 31Author: Meike van Leerdam, Date: 07-31-2025
 32"""
 33
 34import pandas as pd
 35
 36
 37def test_interval_method(
 38    df, days_in_milk_col=None, milking_yield_col=None, test_id_col=None, default_test_id=1
 39):
 40    """Compute 305-day total milk yield using the ICAR Test Interval Method.
 41
 42    The method applies:
 43    - Linear projection from calving to the first test day,
 44    - Trapezoidal integration between consecutive test days,
 45    - Linear projection from the last test day to DIM=305.
 46
 47    Args:
 48        df (pd.DataFrame): Input DataFrame with at least DaysInMilk, MilkingYield,
 49            and (optionally) TestId columns (names can be provided via arguments
 50            or matched via known aliases, case-insensitive).
 51        days_in_milk_col (str | None): Optional column name override for DaysInMilk.
 52        milking_yield_col (str | None): Optional column name override for MilkingYield.
 53        test_id_col (str | None): Optional column name override for TestId.
 54        default_test_id (Any): If TestId is missing, a new `TestId` column is created
 55            with this value.
 56
 57    Returns:
 58        pd.DataFrame: Two-column DataFrame with
 59            - "TestId": identifier per lactation,
 60            - "Total305Yield": computed total milk yield over 305 days.
 61
 62    Raises:
 63        ValueError: If required columns (DaysInMilk or MilkingYield) cannot be found.
 64
 65    Notes:
 66        - Records with DIM > 305 are dropped before computation.
 67        - At least two data points per TestId are required for trapezoidal integration;
 68          otherwise the lactation is skipped.
 69    """
 70    result = []
 71
 72    # create a bit more flexibility in naming the columns and
 73    # when only one lactation is put in without a testid
 74
 75    # Define accepted variations for each logical column
 76    # Accepted aliases (case-insensitive)
 77    aliases = {
 78        "DaysInMilk": ["daysinmilk", "dim", "testday"],
 79        "MilkingYield": ["milkingyield", "testdaymilkyield", "milkyield", "yield"],
 80        "TestId": ["animalid", "testid", "id"],
 81    }
 82
 83    # Create a mapping from lowercase to actual column names
 84    col_lookup = {col.lower(): col for col in df.columns}
 85
 86    def get_col_name(override, possible_names):
 87        """Return a matching actual column name from `df`, or `None` if not found.
 88
 89        Args:
 90            override (str | None): Explicit column name provided by the user.
 91            possible_names (list[str]): List of acceptable aliases (lowercase).
 92
 93        Returns:
 94            str | None: The actual column name present in `df`, or `None` if no match.
 95        """
 96        if override:
 97            return col_lookup.get(override.lower())
 98        for name in possible_names:
 99            if name in col_lookup:
100                return col_lookup[name]
101        return None
102
103    # Resolve columns
104    dim_col = get_col_name(days_in_milk_col, aliases["DaysInMilk"])
105    if not dim_col:
106        raise ValueError("No DaysInMilk column found in DataFrame.")
107
108    my_col = get_col_name(milking_yield_col, aliases["MilkingYield"])
109    if not my_col:
110        raise ValueError("No MilkingYield column found in DataFrame.")
111
112    id_col = get_col_name(test_id_col, aliases["TestId"])
113    if not id_col:
114        id_col = "TestId"
115        df[id_col] = default_test_id
116
117    # Filter out records where Day > 305
118    df = df[df[dim_col] <= 305]
119
120    # Iterate over each lactation
121    for lactation in df[id_col].unique():
122        lactation_df = df[df[id_col] == lactation].copy()
123
124        # Sort by DaysInMilk ascending
125        lactation_df.sort_values(by=dim_col, ascending=True, inplace=True)
126
127        if len(lactation_df) < 2:
128            print(f"Skipping TestId {lactation}: not enough data points for interpolation.")
129            continue
130
131        # Start and end points
132        start = lactation_df.iloc[0]
133        end = lactation_df.iloc[-1]
134
135        # Start contribution
136        MY0 = start[dim_col] * start[my_col]
137
138        # End contribution
139        MYend = (306 - end[dim_col]) * end[my_col]
140
141        # Intermediate trapezoidal contributions
142        lactation_df["width"] = lactation_df[dim_col].diff().shift(-1)
143        lactation_df["avg_yield"] = (lactation_df[my_col] + lactation_df[my_col].shift(-1)) / 2
144        lactation_df["trapezoid_area"] = lactation_df["width"] * lactation_df["avg_yield"]
145
146        total_intermediate = lactation_df["trapezoid_area"].sum()
147
148        total_yield = MY0 + total_intermediate + MYend
149        result.append((lactation, total_yield))
150
151    return pd.DataFrame(result, columns=["TestId", "Total305Yield"])