Fix EITC calibration bugs: 2-kid bucket, surviving-spouse mask, validation reference, stale SOI targets (#767)

1. EITC by-kids 2-kid bucket

   The EITC-by-kids calibration in `build_loss_matrix` treated IRS SOI
   rows 2 and 3 as nested (`>=`) when the source data is actually
   exclusive per IRS Pub 1304 Table 2.5 (0, 1, 2, "3 or more"). The
   2-kid bucket double-counted with the 3+ bucket, leaving the
   calibrator no pressure on exact-2-kid EITC recipients and causing
   a 27% aggregate undercount ($49B vs $67B Treasury target for TY2024).

   Changing `<2` to `<3` makes rows 0/1/2 exact-match and leaves row 3
   as `>=` (correct, since EITC caps qualifying children at 3).

2. SURVIVING_SPOUSE mask

   The SOI loop masked the IRS "Married Filing Jointly/Surviving Spouse"
   row to only PE's JOINT filing status, orphaning ~1.58M surviving-
   spouse tax units (0.8% of total) from joint-filer AGI-band targets.
   Fix matches both JOINT and SURVIVING_SPOUSE via `np.isin`, consistent
   with `soi.py:302-303` and `ctc_diagnostics.py:19-20`.

3. EITC validation reference

   `validate_national_h5.py` used `~$60B` as the sanity reference for
   EITC, but the 2024 Treasury Tax Expenditure target is $67B.
   Tightened so an underconverged calibration is less likely to
   silently pass validation.

4. Stale SOI filer-count targets

   SOI_FILER_COUNTS_2015 was a hardcoded dict of 7 TY2015 AGI-band
   counts, uprated only by population growth. Replaced with a dynamic
   read from `soi_targets.csv` at the latest SOI year ≤ calibration
   year (currently TY2023, 19 granular bands). Population-only
   uprating missed dramatic 2015→2023 distributional shifts: +64%
   at the $100K+ band and −27% at $0–5K.

Fixes #766, #769.

Author: MaxGhenis

changelog.d/767.fixed.md

@@ -0,0 +1,7 @@
+Fix EITC-by-kids calibration: 2-kid bucket was using `>=2` against an exclusive IRS target, causing a 27% EITC aggregate undercount since October 2024. See #766.
+
+Fix SOI filing-status mask to include SURVIVING_SPOUSE alongside JOINT when matching IRS "Married Filing Jointly/Surviving Spouse" rows, so ~1.58M surviving-spouse tax units are constrained by joint-filer AGI-band targets.
+
+Tighten the EITC validation reference in `validate_national_h5.py` from ~$60B to ~$67B (2024 Treasury Tax Expenditure estimate) so underconverged calibrations no longer pass sanity checks.
+
+Replace hardcoded SOI filer-count targets from TY2015 (uprated only by population growth) with dynamic reads from `soi_targets.csv` at the latest SOI year ≤ calibration year. Uses 19 granular AGI bands instead of 7 coarse bands, correcting dramatic distributional shifts (TY2015→TY2023 showed +64% at $100K+ and −27% at $0–5K AGI that population-only uprating missed). See #769.

policyengine_us_data/calibration/validate_national_h5.py

@@ -56,7 +56,7 @@
     "social_security": (1_200_000_000_000, "~$1.2T"),
     "snap": (110_000_000_000, "~$110B"),
     "ssi": (60_000_000_000, "~$60B"),
-    "eitc": (60_000_000_000, "~$60B"),
+    "eitc": (67_000_000_000, "~$67B"),
     "income_tax_before_credits": (4_000_000_000_000, "~$4T"),
 }
 

policyengine_us_data/utils/loss.py

@@ -428,7 +428,7 @@ def build_loss_matrix(dataset: type, time_period):
         if row["Filing status"] == "Single":
             mask *= df["filing_status"].values == "SINGLE"
         elif row["Filing status"] == "Married Filing Jointly/Surviving Spouse":
-            mask *= df["filing_status"].values == "JOINT"
+            mask *= np.isin(df["filing_status"].values, ["JOINT", "SURVIVING_SPOUSE"])
         elif row["Filing status"] == "Head of Household":
             mask *= df["filing_status"].values == "HEAD_OF_HOUSEHOLD"
         elif row["Filing status"] == "Married Filing Separately":
@@ -599,7 +599,10 @@ def build_loss_matrix(dataset: type, time_period):
         )
         eitc_eligible_children = sim.calculate("eitc_child_count").values
         eitc = sim.calculate("eitc").values
-        if row["count_children"] < 2:
+        # IRS Pub 1304 Table 2.5 reports EITC returns by exclusive
+        # qualifying-child categories: 0, 1, 2, and "3 or more". Row 3
+        # represents 3+ since EITC caps qualifying children at 3.
+        if row["count_children"] < 3:
             meets_child_criteria = eitc_eligible_children == row["count_children"]
         else:
             meets_child_criteria = eitc_eligible_children >= row["count_children"]
@@ -627,38 +630,39 @@ def build_loss_matrix(dataset: type, time_period):
         time_period,
     )
 
-    # Tax filer counts by AGI band (SOI Table 1.1)
-    # This calibrates total filers (not just taxable returns) including
-    # low-AGI filers who are important for income distribution accuracy
-    SOI_FILER_COUNTS_2015 = {
-        # (agi_lower, agi_upper): total_returns
-        (-np.inf, 0): 2_072_066,
-        (0, 5_000): 10_134_703,
-        (5_000, 10_000): 11_398_595,
-        (10_000, 25_000): 23_447_927,
-        (25_000, 50_000): 23_727_745,
-        (50_000, 100_000): 32_801_908,
-        (100_000, np.inf): 25_120_985,
-    }
+    # Tax filer counts by AGI band (SOI Table 1.1). Calibrates total
+    # filers (not just taxable returns), with granular bands sourced
+    # from the latest SOI year <= calibration year to avoid hardcoding
+    # stale 2015 values.
+    soi_all = pd.read_csv(CALIBRATION_FOLDER / "soi_targets.csv")
+    soi_count_rows = soi_all[
+        (soi_all["Variable"] == "count")
+        & (soi_all["Filing status"] == "All")
+        & (~soi_all["Full population"])
+        & (~soi_all["Taxable only"])
+        & (soi_all["Year"] <= time_period)
+    ]
+    soi_latest_year = int(soi_count_rows["Year"].max())
+    soi_filer_bands = (
+        soi_count_rows[soi_count_rows["Year"] == soi_latest_year]
+        .sort_values("AGI lower bound")
+        .reset_index(drop=True)
+    )
 
-    # Get AGI and filer status at tax unit level, mapped to household
     agi_tu = sim.calculate("adjusted_gross_income").values
     is_filer_tu = sim.calculate("tax_unit_is_filer").values > 0
 
-    for (
-        agi_lower,
-        agi_upper,
-    ), filer_count_2015 in SOI_FILER_COUNTS_2015.items():
+    for _, row in soi_filer_bands.iterrows():
+        agi_lower = row["AGI lower bound"]
+        agi_upper = row["AGI upper bound"]
         in_band = (agi_tu >= agi_lower) & (agi_tu < agi_upper)
         label = f"nation/soi/filer_count/agi_{fmt(agi_lower)}_{fmt(agi_upper)}"
         loss_matrix[label] = sim.map_result(
             (is_filer_tu & in_band).astype(float),
             "tax_unit",
             "household",
         )
-        # Uprate from 2015 to current year using population growth
-        uprated_target = filer_count_2015 * population_uprating
-        targets_array.append(uprated_target)
+        targets_array.append(row["Value"])
 
     # Hard-coded totals
     for variable_name, target in HARD_CODED_TOTALS.items():