Add SPM geographic adjustment input (#8246)

Author: MaxGhenis

changelog.d/spm-geographic-adjustment.added.md

@@ -0,0 +1 @@
+Add an SPM unit geographic adjustment input and use it to calculate SPM thresholds.

policyengine_us/tests/policy/baseline/household/income/spm_unit/test_spm_unit_spm_threshold.py

@@ -6,8 +6,7 @@
 2. Post-published years uprate via PolicyEngine's ``gov.bls.cpi.cpi_u``
    parameter.
 3. Composition and tenure changes between periods flow through to the
-   threshold while preserving the unit-specific geographic adjustment
-   implied by the prior-year stored threshold.
+   threshold while applying the unit-specific geographic adjustment.
 4. The Betson three-parameter equivalence scale is applied (a 2A2C
    reference family at the renter national base equals 39430 in 2024).
 """
@@ -170,3 +169,130 @@ def test_formula_preserves_implied_geographic_adjustment():
     got = float(sim.calculate("spm_unit_spm_threshold", YEAR)[0])
     expected = current_base * equiv * GEOADJ
     assert got == pytest.approx(expected, rel=1e-5)
+
+
+def test_formula_uses_current_geographic_adjustment_input():
+    """A dataset can provide the geographic adjustment directly without
+    materializing an SPM threshold input."""
+    YEAR = 2023
+    GEOADJ = 1.25
+
+    cpi_u = _cpi_u()
+    base = _reference_threshold_array(
+        np.array([SPMUnitTenureType.RENTER]),
+        YEAR,
+        cpi_u,
+    )[0]
+    equiv = spm_equivalence_scale(2, 2)
+
+    situation = {
+        "people": {
+            "a1": {"age": {YEAR: 40}},
+            "a2": {"age": {YEAR: 40}},
+            "k1": {"age": {YEAR: 5}},
+            "k2": {"age": {YEAR: 3}},
+        },
+        "spm_units": {
+            "spm_unit": {
+                "members": ["a1", "a2", "k1", "k2"],
+                "spm_unit_geographic_adjustment": {
+                    YEAR: GEOADJ,
+                },
+                "spm_unit_tenure_type": {
+                    YEAR: "RENTER",
+                },
+            }
+        },
+    }
+
+    sim = Simulation(situation=situation)
+    got = float(sim.calculate("spm_unit_spm_threshold", YEAR)[0])
+    expected = base * equiv * GEOADJ
+    assert got == pytest.approx(expected, rel=1e-5)
+
+
+def test_geographic_adjustment_defaults_to_one_without_prior_threshold():
+    """With no direct or implied geographic adjustment, the threshold uses
+    the national reference threshold."""
+    YEAR = 2024
+
+    cpi_u = _cpi_u()
+    base = _reference_threshold_array(
+        np.array([SPMUnitTenureType.RENTER]),
+        YEAR,
+        cpi_u,
+    )[0]
+    equiv = spm_equivalence_scale(2, 2)
+
+    situation = {
+        "people": {
+            "a1": {"age": {YEAR: 40}},
+            "a2": {"age": {YEAR: 40}},
+            "k1": {"age": {YEAR: 5}},
+            "k2": {"age": {YEAR: 3}},
+        },
+        "spm_units": {
+            "spm_unit": {
+                "members": ["a1", "a2", "k1", "k2"],
+                "spm_unit_tenure_type": {
+                    YEAR: "RENTER",
+                },
+            }
+        },
+    }
+
+    sim = Simulation(situation=situation)
+    got = float(sim.calculate("spm_unit_spm_threshold", YEAR)[0])
+    expected = base * equiv
+    assert got == pytest.approx(expected, rel=1e-5)
+
+
+def test_current_geographic_adjustment_input_overrides_prior_implied_value():
+    """Current-period geographic adjustment inputs should take precedence
+    over a prior-year threshold used for backward compatibility."""
+    YEAR = 2026
+    PRIOR = 2025
+    PRIOR_GEOADJ = 1.5
+    CURRENT_GEOADJ = 1.1
+
+    cpi_u = _cpi_u()
+    prior_base = _reference_threshold_array(
+        np.array([SPMUnitTenureType.RENTER]),
+        PRIOR,
+        cpi_u,
+    )[0]
+    current_base = _reference_threshold_array(
+        np.array([SPMUnitTenureType.RENTER]),
+        YEAR,
+        cpi_u,
+    )[0]
+    equiv = spm_equivalence_scale(2, 2)
+
+    situation = {
+        "people": {
+            "a1": {"age": {PRIOR: 40, YEAR: 41}},
+            "a2": {"age": {PRIOR: 40, YEAR: 41}},
+            "k1": {"age": {PRIOR: 5, YEAR: 6}},
+            "k2": {"age": {PRIOR: 3, YEAR: 4}},
+        },
+        "spm_units": {
+            "spm_unit": {
+                "members": ["a1", "a2", "k1", "k2"],
+                "spm_unit_spm_threshold": {
+                    PRIOR: float(prior_base * equiv * PRIOR_GEOADJ),
+                },
+                "spm_unit_geographic_adjustment": {
+                    YEAR: CURRENT_GEOADJ,
+                },
+                "spm_unit_tenure_type": {
+                    PRIOR: "RENTER",
+                    YEAR: "RENTER",
+                },
+            }
+        },
+    }
+
+    sim = Simulation(situation=situation)
+    got = float(sim.calculate("spm_unit_spm_threshold", YEAR)[0])
+    expected = current_base * equiv * CURRENT_GEOADJ
+    assert got == pytest.approx(expected, rel=1e-5)

policyengine_us/variables/household/income/spm_unit/spm_unit_geographic_adjustment.py

@@ -0,0 +1,47 @@
+import numpy as np
+
+from policyengine_us.model_api import *
+from policyengine_us.variables.household.income.spm_unit.spm_unit_spm_threshold import (
+    _reference_threshold_array,
+)
+from spm_calculator.equivalence_scale import spm_equivalence_scale
+
+
+class spm_unit_geographic_adjustment(Variable):
+    value_type = float
+    entity = SPMUnit
+    label = "SPM unit geographic adjustment"
+    documentation = "Geographic adjustment applied to the SPM reference threshold."
+    definition_period = YEAR
+    default_value = 1.0
+
+    def formula_2016(spm_unit, period, parameters):
+        """Infer the location adjustment from prior-year threshold inputs.
+
+        Datasets can provide this directly. For older datasets that only
+        contain stored SPM thresholds, this preserves the implied adjustment.
+        """
+        prior_period = period.last_year
+        cpi_u = parameters.gov.bls.cpi.cpi_u
+
+        prior_threshold = spm_unit("spm_unit_spm_threshold", prior_period)
+        prior_adults = spm_unit("spm_unit_count_adults", prior_period)
+        prior_children = spm_unit("spm_unit_count_children", prior_period)
+        prior_tenure = spm_unit("spm_unit_tenure_type", prior_period)
+
+        prior_base = _reference_threshold_array(
+            prior_tenure,
+            prior_period.start.year,
+            cpi_u,
+        )
+        prior_equiv_scale = spm_equivalence_scale(
+            prior_adults,
+            prior_children,
+        )
+        denominator = prior_base * prior_equiv_scale
+        return np.divide(
+            prior_threshold,
+            denominator,
+            out=np.ones_like(prior_threshold, dtype=float),
+            where=(prior_threshold > 0) & (denominator > 0),
+        )

policyengine_us/variables/household/income/spm_unit/spm_unit_spm_threshold.py

@@ -56,54 +56,28 @@ class spm_unit_spm_threshold(Variable):
     definition_period = YEAR
     unit = USD
 
-    def formula_2024(spm_unit, period, parameters):
+    def formula_2015(spm_unit, period, parameters):
         """Rebuild the SPM threshold from current composition, current
-        tenure, and the unit-specific geographic adjustment implied by
-        the prior-year stored threshold.
-
-        The implied geographic adjustment is
-        ``prior_threshold / (prior_base * prior_equiv_scale)``. Carrying
-        it forward this way preserves the location-specific SPM
-        adjustment baked into the input data while letting composition
-        and tenure changes flow through.
+        tenure, and the unit-specific geographic adjustment.
 
         Base reference thresholds and the Betson three-parameter
         equivalence scale come from ``spm-calculator``.
         """
-        prior_period = period.last_year
         cpi_u = parameters.gov.bls.cpi.cpi_u
 
-        prior_threshold = spm_unit("spm_unit_spm_threshold", prior_period)
-        prior_adults = spm_unit("spm_unit_count_adults", prior_period)
-        prior_children = spm_unit("spm_unit_count_children", prior_period)
-        prior_tenure = spm_unit("spm_unit_tenure_type", prior_period)
-
         current_adults = spm_unit("spm_unit_count_adults", period)
         current_children = spm_unit("spm_unit_count_children", period)
         current_tenure = spm_unit("spm_unit_tenure_type", period)
-
-        prior_base = _reference_threshold_array(
-            prior_tenure,
-            prior_period.start.year,
-            cpi_u,
-        )
+        geoadj = spm_unit("spm_unit_geographic_adjustment", period)
         current_base = _reference_threshold_array(
             current_tenure,
             period.start.year,
             cpi_u,
         )
 
-        prior_equiv_scale = spm_equivalence_scale(prior_adults, prior_children)
         current_equiv_scale = spm_equivalence_scale(
             current_adults,
             current_children,
         )
 
-        denominator = prior_base * prior_equiv_scale
-        geoadj = np.divide(
-            prior_threshold,
-            denominator,
-            out=np.ones_like(prior_threshold, dtype=float),
-            where=denominator > 0,
-        )
         return current_base * current_equiv_scale * geoadj