Support lagged years in the shared federal poverty guideline helper

changelog.d/liheap-fpg-helper.changed.md

@@ -0,0 +1 @@
+Extend the federal poverty guideline helper to support lagged guideline years and reuse it for Massachusetts LIHEAP without changing its October lookup date.

policyengine_us/tests/policy/baseline/gov/states/ma/doer/liheap/ma_liheap_fpg.yaml

@@ -21,3 +21,15 @@
     state_code: MA
   output:
     ma_liheap_fpg: 30_000
+
+- name: Case 4, LIHEAP uses the prior guideline and SPM size while tax units use the current guideline.
+  period: 2026
+  input:
+    state_code: [MA, MA, MA]
+    spm_unit_size: [1, 4, 9]
+    tax_unit_size: [2, 3, 1]
+  output:
+    # LIHEAP uses the 2025 guideline, including its additional-person amount.
+    ma_liheap_fpg: [15_650, 32_150, 59_650]
+    # The existing helper default continues using the 2026 guideline.
+    tax_unit_fpg: [21_640, 27_320, 15_960]

policyengine_us/variables/gov/hhs/tax_unit_fpg.py

@@ -1,8 +1,15 @@
 from policyengine_us.model_api import *
+from policyengine_core.periods import instant
 
 
-def fpg(unit_size, state_group, period, parameters):
-    p_fpg = parameters(period).gov.hhs.fpg
+def fpg(unit_size, state_group, period, parameters, year_lag=0):
+    """Return the annual guideline for the supplied size and guideline year.
+
+    Lag only the parameter date, preserving its month and day. Callers supply
+    the current household size and apply any caps, policy rates, or rounding.
+    """
+    guideline_date = instant(period).offset(-int(year_lag), "year")
+    p_fpg = parameters(guideline_date).gov.hhs.fpg
     p1 = p_fpg.first_person[state_group]
     pn = p_fpg.additional_person[state_group]
     return p1 + pn * (unit_size - 1)

policyengine_us/variables/gov/states/ma/doer/liheap/ma_liheap_fpg.py

@@ -1,9 +1,11 @@
 from policyengine_us.model_api import *
+from policyengine_us.variables.gov.hhs.tax_unit_fpg import fpg
 
 
 class ma_liheap_fpg(Variable):
     value_type = float
     entity = SPMUnit
+    unit = USD
     label = "Massachusetts LIHEAP federal poverty guideline"
     definition_period = YEAR
     defined_for = StateCode.MA
@@ -12,9 +14,6 @@ class ma_liheap_fpg(Variable):
     def formula(spm_unit, period, parameters):
         n = spm_unit("spm_unit_size", period.this_year)
         state_group = spm_unit.household("state_group_str", period.this_year)
-        year = period.start.year
-        instant_str = f"{year - 1}-10-01"
-        p_fpg = parameters(instant_str).gov.hhs.fpg
-        p1 = p_fpg.first_person[state_group]
-        pn = p_fpg.additional_person[state_group]
-        return p1 + pn * (n - 1)
+        # Preserve the October guideline date for the preceding heating season.
+        guideline_date = f"{period.start.year}-10-01"
+        return fpg(n, state_group, guideline_date, parameters, year_lag=1)