Raise if bin index is out of range (#540)

Author: stevebachmeier

CHANGELOG.rst

@@ -1,3 +1,7 @@
+**4.3.7 - 09/10/25**
+
+  - Bugfix: raise an error if simulation start year is earlier than population data.
+
 **4.3.6 - 08/28/25**
 
   - Feature: ScaledPopulation can handle multiple year data inputs.

src/vivarium_public_health/population/base_population.py

@@ -166,7 +166,7 @@ def get_demographic_proportions_for_creation_time(
         demographic_proportions, year: int
     ) -> pd.DataFrame:
         reference_years = sorted(set(demographic_proportions.year_start))
-        ref_year_index = np.digitize(year, reference_years).item() - 1
+        ref_year_index = _find_bin_start_index(year, reference_years)
         return demographic_proportions[
             demographic_proportions.year_start == reference_years[ref_year_index]
         ]
@@ -257,22 +257,22 @@ def _format_data_inputs(
         if "year_start" not in scaling_factor.index.names:
             return population_structure, scaling_factor
 
-        # Subset to start year of simulation or closest year
+        # Subset the population structure and scaling factors to the simulation
+        # start year. If the data does not contain the exact simulation start
+        # year, subset to the closest year less than the simulation start year.
         pop_reference_years = sorted(
             set(population_structure.index.get_level_values("year_start"))
         )
-        pop_year_index = np.digitize(year, pop_reference_years).item() - 1
-        scale_reference_years = sorted(
-            set(scaling_factor.index.get_level_values("year_start"))
-        )
-        scale_year_index = np.digitize(year, scale_reference_years).item() - 1
-        # Subset to start year of simulation or earliest year. E.g. if start year = 2021 and pop
-        # structure has 2021, we will subset to 2021. If pop structure minimum year is 2025, we
-        # will subset to 2025.
+        pop_year_index = _find_bin_start_index(year, pop_reference_years)
         population_structure = population_structure.loc[
             population_structure.index.get_level_values("year_start")
             == pop_reference_years[pop_year_index]
         ]
+
+        scale_reference_years = sorted(
+            set(scaling_factor.index.get_level_values("year_start"))
+        )
+        scale_year_index = _find_bin_start_index(year, scale_reference_years)
         scaling_factor = scaling_factor.loc[
             scaling_factor.index.get_level_values("year_start")
             == scale_reference_years[scale_year_index]
@@ -527,3 +527,31 @@ def _assign_demography_with_age_bounds(
     )
     register_simulants(simulants[list(key_columns)])
     return simulants
+
+
+def _find_bin_start_index(value: int, sorted_reference_values: list[int]) -> int:
+    """Finds the index of the closest reference value less than or equal to the provided value.
+
+    Parameters
+    ----------
+    value
+        The value for which to find the closest reference value.
+    sorted_reference_values
+        A sorted list of reference values.
+
+    Returns
+    -------
+        The index of the closest reference value less than or equal to the provided value.
+
+    Raises
+    ------
+        ValueError
+            If the provided value is less than the minimum reference value.
+    """
+    ref_value_index = np.digitize(value, sorted_reference_values).item() - 1
+    if ref_value_index < 0:
+        raise ValueError(
+            f"The provided value {value} is less than the minimum reference value "
+            f"{min(sorted_reference_values)}."
+        )
+    return ref_value_index

tests/population/test_base_population.py

@@ -4,7 +4,6 @@
 import numpy as np
 import pandas as pd
 import pytest
-from layered_config_tree import LayeredConfigTree
 from vivarium import InteractiveContext
 from vivarium.testing_utilities import get_randomness
 from vivarium_testing_utils import FuzzyChecker
@@ -296,7 +295,11 @@ def test_scaled_population(
                 "population_size": 1_000_000,
                 "include_sex": "Both",
             },
-            "time": {"step_size": 1},
+            "time": {
+                "step_size": 1,
+                # Update the start year to fall within the population structure data.
+                "start": {"year": 2021},
+            },
         },
         layer="override",
     )
@@ -470,6 +473,22 @@ def test_scaled_population__format_data_inputs(
         pd.testing.assert_frame_equal(data, expected)
 
 
+def test__find_bin_start_index():
+    sorted_values = [10, 20, 30]
+    assert bp._find_bin_start_index(10, sorted_values) == 0
+    assert bp._find_bin_start_index(19, sorted_values) == 0
+    assert bp._find_bin_start_index(20, sorted_values) == 1
+    assert bp._find_bin_start_index(29, sorted_values) == 1
+    assert bp._find_bin_start_index(30, sorted_values) == 2
+    assert bp._find_bin_start_index(99999, sorted_values) == 2
+
+    # Edge case
+    with pytest.raises(
+        ValueError, match="The provided value 9 is less than the minimum reference value 10."
+    ):
+        bp._find_bin_start_index(9, sorted_values)
+
+
 def _check_population(simulants, initial_age, step_size, include_sex):
     assert len(simulants) == len(simulants.age.unique())
     assert simulants.age.min() > initial_age