Enforce NIPA employment target in calibration (#1020)

MaxGhenis · web-flow · commit 71253abb26df · 2026-05-19T10:05:09.000-04:00
diff --git a/AGENTS.md b/AGENTS.md
@@ -20,6 +20,25 @@ artifacts, or public library functions, read
 When diagnosing a deployed Modal pipeline run or a failed publication pipeline,
 read `docs/engineering/skills/pipeline_operations.md`.
 
+When adding, changing, or reviewing calibration target definitions, read
+`docs/engineering/skills/calibration_targets.md`.
+
+## Calibration targets
+
+Manually sourced national or local-file calibration targets must be registered
+in every active target path before merging:
+
+1. `policyengine_us_data/utils/loss.py` for the ECPS loss matrix.
+2. `policyengine_us_data/db/etl_national_targets.py` for `policy_data.db` and
+   local H5 validation inputs.
+3. `policyengine_us_data/calibration/target_config.yaml` when the default
+   calibration uses an `include:` list; otherwise the target can exist in
+   `policy_data.db` but still be omitted from calibration.
+
+Do not treat a target appearing in `policy_data.db` as proof that published
+datasets were calibrated to it. Add or update tests that fail if a new target is
+present in one path but missing from another.
+
 ## GitHub PRs
 
 Read `docs/engineering/skills/github-prs.md` before opening, replacing, or
diff --git a/changelog.d/1019.fixed b/changelog.d/1019.fixed
@@ -0,0 +1 @@
+Ensure BEA NIPA direct-sum targets are selected by default calibration and fail publication validation when enhanced CPS employment income misses the wages target.
diff --git a/docs/engineering/skills/calibration_targets.md b/docs/engineering/skills/calibration_targets.md
@@ -0,0 +1,32 @@
+# Calibration Target Changes
+
+Use this workflow when adding, changing, or reviewing manually sourced
+calibration targets.
+
+## Dual Registration
+
+New targets must be registered in both active target systems:
+
+- `policyengine_us_data/utils/loss.py` for the ECPS `build_loss_matrix()` path.
+- `policyengine_us_data/db/etl_national_targets.py` for `policy_data.db`, local
+  H5 outputs, and validation inputs.
+
+If the default calibration path uses `policyengine_us_data/calibration/target_config.yaml`
+with an `include:` list, also add the matching include rule there. A target can
+exist in `policy_data.db` and still be ignored by calibration if it is missing
+from `target_config.yaml`.
+
+## Tests
+
+Every target change should add or update tests that prove the target is wired
+through every active path. For manually sourced national targets, cover:
+
+- the ECPS loss matrix registration in `tests/unit/calibration/test_loss_targets.py`;
+- the DB ETL row in `tests/unit/test_etl_national_targets.py`;
+- the default calibration include rule in
+  `tests/unit/calibration/test_target_config.py`;
+- any publication guard in `tests/unit/test_upload_completed_datasets.py` when
+  a missing target would make a released dataset materially wrong.
+
+Do not use a successful DB ETL test as a substitute for a calibration-selection
+test.
diff --git a/policyengine_us_data/calibration/target_config.yaml b/policyengine_us_data/calibration/target_config.yaml
@@ -164,6 +164,14 @@ include:
     geo_level: national
   - variable: childcare_expenses
     geo_level: national
+  - variable: employment_income_before_lsr
+    geo_level: national
+  - variable: nipa_proprietors_income
+    geo_level: national
+  - variable: interest_income
+    geo_level: national
+  - variable: dividend_income
+    geo_level: national
   - variable: long_term_capital_gains
     geo_level: national
   - variable: medicaid
diff --git a/policyengine_us_data/db/etl_national_targets.py b/policyengine_us_data/db/etl_national_targets.py
@@ -30,14 +30,16 @@
     target_variable_components,
 )
 
+# Manually sourced national targets must be registered in both active target
+# systems: policyengine_us_data/utils/loss.py for ECPS calibration and this
+# file for policy_data.db/local H5 targets. If the default calibration include
+# list should train on the target, add it to calibration/target_config.yaml too.
 BEA_NIPA_WAGES_AND_SALARIES_2024 = 12_387_929_000_000
 BEA_NIPA_PROPRIETORS_INCOME_2024 = 2_023_080_000_000
 BEA_NIPA_PERSONAL_INTEREST_INCOME_2024 = 1_926_644_000_000
 BEA_NIPA_PERSONAL_DIVIDEND_INCOME_2024 = 2_218_700_000_000
 
-NIPA_PROPRIETORS_INCOME_VARIABLE = (
-    "total_self_employment_income+farm_operations_income+partnership_s_corp_income"
-)
+NIPA_PROPRIETORS_INCOME_VARIABLE = "nipa_proprietors_income"
 NIPA_PERSONAL_INTEREST_INCOME_VARIABLE = "interest_income"
 TAXABLE_INTEREST_AND_ORDINARY_DIVIDENDS_VARIABLE = (
     "taxable_interest_income+dividend_income"
@@ -453,9 +455,8 @@ def extract_national_targets(year: int = DEFAULT_YEAR):
             "notes": (
                 "Proprietors' income with IVA and CCAdj for all persons, "
                 "including nonfilers; FRED/BEA series A041RC1A027NBEA. "
-                "Mapped to the closest additive PolicyEngine aggregate: "
-                "total self-employment, farm operations, and "
-                "partnership/S-corp income."
+                "Mapped to the PolicyEngine-US NIPA proprietors' income "
+                "aggregate."
             ),
             "year": 2024,
         },
diff --git a/policyengine_us_data/storage/upload_completed_datasets.py b/policyengine_us_data/storage/upload_completed_datasets.py
@@ -8,6 +8,9 @@
 from policyengine_core.data import Dataset
 
 from policyengine_us_data.__version__ import __version__ as DATA_PACKAGE_VERSION
+from policyengine_us_data.db.etl_national_targets import (
+    BEA_NIPA_WAGES_AND_SALARIES_2024,
+)
 from policyengine_us_data.datasets import EnhancedCPS_2024
 from policyengine_us_data.datasets.cps.cps import CPS_2024
 from policyengine_us_data.datasets.cps.enhanced_cps import clone_diagnostics_path
@@ -125,7 +128,14 @@ class MicrosimulationAggregateCheck:
 ]
 
 # Aggregate thresholds for broad sanity checks (year 2024).
-MIN_EMPLOYMENT_INCOME_SUM = 5e12  # $5 trillion
+MIN_PLAUSIBLE_EMPLOYMENT_INCOME_SUM = 5e12  # $5 trillion
+NIPA_EMPLOYMENT_INCOME_TOLERANCE = 0.10
+MIN_ENHANCED_CPS_EMPLOYMENT_INCOME_SUM = BEA_NIPA_WAGES_AND_SALARIES_2024 * (
+    1 - NIPA_EMPLOYMENT_INCOME_TOLERANCE
+)
+MAX_ENHANCED_CPS_EMPLOYMENT_INCOME_SUM = BEA_NIPA_WAGES_AND_SALARIES_2024 * (
+    1 + NIPA_EMPLOYMENT_INCOME_TOLERANCE
+)
 MIN_HOUSEHOLD_WEIGHT_SUM = 100e6  # 100 million
 MAX_HOUSEHOLD_WEIGHT_SUM = 200e6  # 200 million
 
@@ -152,9 +162,10 @@ class MicrosimulationAggregateCheck:
     "enhanced_cps_2024.h5": (
         MicrosimulationAggregateCheck(
             variable="employment_income",
-            label="employment_income sum",
+            label="employment_income sum vs NIPA wages target",
             statistic="sum",
-            min_value=MIN_EMPLOYMENT_INCOME_SUM,
+            min_value=MIN_ENHANCED_CPS_EMPLOYMENT_INCOME_SUM,
+            max_value=MAX_ENHANCED_CPS_EMPLOYMENT_INCOME_SUM,
         ),
         MicrosimulationAggregateCheck(
             variable="social_security_retirement",
@@ -188,7 +199,7 @@ class MicrosimulationAggregateCheck:
             variable="employment_income",
             label="employment_income sum",
             statistic="sum",
-            min_value=MIN_EMPLOYMENT_INCOME_SUM,
+            min_value=MIN_PLAUSIBLE_EMPLOYMENT_INCOME_SUM,
         ),
     ),
 }
diff --git a/policyengine_us_data/utils/loss.py b/policyengine_us_data/utils/loss.py
@@ -34,24 +34,47 @@
 
 # National calibration targets consumed by build_loss_matrix().
 # These values are specific to 2024 — they should NOT be applied to
-# other years without re-sourcing.  They are duplicated in
-# db/etl_national_targets.py which loads them into policy_data.db.
-# A future PR should wire build_loss_matrix() to read from the
-# database so this dict can be deleted.  See PR #488.
+# other years without re-sourcing. They must stay registered here for
+# ECPS calibration, in db/etl_national_targets.py for policy_data.db,
+# and in calibration/target_config.yaml when the default calibration
+# include list should train on them. A future PR should wire
+# build_loss_matrix() to read from the database so this duplication can
+# be deleted. See PR #488.
 
 BEA_NIPA_WAGES_AND_SALARIES_2024 = 12_387_929_000_000
 BEA_NIPA_PROPRIETORS_INCOME_2024 = 2_023_080_000_000
 BEA_NIPA_PERSONAL_INTEREST_INCOME_2024 = 1_926_644_000_000
 BEA_NIPA_PERSONAL_DIVIDEND_INCOME_2024 = 2_218_700_000_000
 
-NIPA_PROPRIETORS_INCOME_VARIABLE = (
-    "total_self_employment_income+farm_operations_income+partnership_s_corp_income"
-)
+NIPA_PROPRIETORS_INCOME_VARIABLE = "nipa_proprietors_income"
 NIPA_PERSONAL_INTEREST_INCOME_VARIABLE = "interest_income"
 TAXABLE_INTEREST_AND_ORDINARY_DIVIDENDS_VARIABLE = (
     "taxable_interest_income+dividend_income"
 )
 
+BEA_NIPA_DIRECT_SUM_TARGETS = (
+    (
+        "nation/bea/nipa_wages_and_salaries",
+        "employment_income_before_lsr",
+        BEA_NIPA_WAGES_AND_SALARIES_2024,
+    ),
+    (
+        "nation/bea/nipa_proprietors_income",
+        NIPA_PROPRIETORS_INCOME_VARIABLE,
+        BEA_NIPA_PROPRIETORS_INCOME_2024,
+    ),
+    (
+        "nation/bea/nipa_personal_interest_income",
+        NIPA_PERSONAL_INTEREST_INCOME_VARIABLE,
+        BEA_NIPA_PERSONAL_INTEREST_INCOME_2024,
+    ),
+    (
+        "nation/bea/nipa_personal_dividend_income",
+        "dividend_income",
+        BEA_NIPA_PERSONAL_DIVIDEND_INCOME_2024,
+    ),
+)
+
 CBO_INCOME_BY_SOURCE_TARGETS = [
     ("irs_employment_income", "employment_income"),
     ("self_employment_income", "self_employment_income"),
@@ -1249,29 +1272,7 @@ def build_loss_matrix(dataset: type, time_period):
         )
         targets_array.append(income_by_source._children[parameter])
 
-    bea_nipa_targets = [
-        (
-            "nation/bea/nipa_wages_and_salaries",
-            "employment_income_before_lsr",
-            BEA_NIPA_WAGES_AND_SALARIES_2024,
-        ),
-        (
-            "nation/bea/nipa_proprietors_income",
-            NIPA_PROPRIETORS_INCOME_VARIABLE,
-            BEA_NIPA_PROPRIETORS_INCOME_2024,
-        ),
-        (
-            "nation/bea/nipa_personal_interest_income",
-            NIPA_PERSONAL_INTEREST_INCOME_VARIABLE,
-            BEA_NIPA_PERSONAL_INTEREST_INCOME_2024,
-        ),
-        (
-            "nation/bea/nipa_personal_dividend_income",
-            "dividend_income",
-            BEA_NIPA_PERSONAL_DIVIDEND_INCOME_2024,
-        ),
-    ]
-    for label, variable, target in bea_nipa_targets:
+    for label, variable, target in BEA_NIPA_DIRECT_SUM_TARGETS:
         loss_matrix[label] = _calculate_household_target_values(
             sim,
             variable,
diff --git a/tests/unit/calibration/test_loss_targets.py b/tests/unit/calibration/test_loss_targets.py
@@ -10,6 +10,7 @@
     AGE_BUCKETED_HEALTH_TARGETS,
     AGGREGATE_LEVEL_TARGETED_VARIABLES,
     AGI_LEVEL_TARGETED_VARIABLES,
+    BEA_NIPA_DIRECT_SUM_TARGETS,
     BLS_CE_TOTALS,
     HARD_CODED_TOTALS,
     TRANSFER_BALANCE_TARGETS,
@@ -32,13 +33,35 @@
     build_loss_matrix,
     get_target_error_normalisation,
 )
+from policyengine_us_data.db import etl_national_targets
 
 
 def test_legacy_loss_targets_include_aggregate_qbi_deduction():
     assert "qualified_business_income_deduction" in AGGREGATE_LEVEL_TARGETED_VARIABLES
     assert "qualified_business_income_deduction" not in AGI_LEVEL_TARGETED_VARIABLES
 
 
+def test_bea_nipa_direct_sum_targets_match_targets_db():
+    loss_targets_by_variable = {
+        variable: target for _, variable, target in BEA_NIPA_DIRECT_SUM_TARGETS
+    }
+
+    assert loss_targets_by_variable == {
+        "employment_income_before_lsr": (
+            etl_national_targets.BEA_NIPA_WAGES_AND_SALARIES_2024
+        ),
+        etl_national_targets.NIPA_PROPRIETORS_INCOME_VARIABLE: (
+            etl_national_targets.BEA_NIPA_PROPRIETORS_INCOME_2024
+        ),
+        etl_national_targets.NIPA_PERSONAL_INTEREST_INCOME_VARIABLE: (
+            etl_national_targets.BEA_NIPA_PERSONAL_INTEREST_INCOME_2024
+        ),
+        "dividend_income": (
+            etl_national_targets.BEA_NIPA_PERSONAL_DIVIDEND_INCOME_2024
+        ),
+    }
+
+
 def test_aca_targets_roll_forward_to_2025():
     targets, data_year = _load_aca_spending_and_enrollment_targets(2025)
 
diff --git a/tests/unit/calibration/test_target_config.py b/tests/unit/calibration/test_target_config.py
@@ -14,6 +14,7 @@
     save_calibration_package,
     load_calibration_package,
 )
+from policyengine_us_data.db import etl_national_targets
 
 
 @pytest.fixture
@@ -345,6 +346,25 @@ def test_training_config_includes_medicare_part_b_target(self):
             "geo_level": "national",
         } in config["include"]
 
+    def test_training_config_includes_bea_nipa_direct_sum_targets(self):
+        config = load_target_config(
+            str(
+                Path(__file__).resolve().parents[3]
+                / "policyengine_us_data"
+                / "calibration"
+                / "target_config.yaml"
+            )
+        )
+
+        include_rules = config["include"]
+        for variable in [
+            "employment_income_before_lsr",
+            etl_national_targets.NIPA_PROPRIETORS_INCOME_VARIABLE,
+            etl_national_targets.NIPA_PERSONAL_INTEREST_INCOME_VARIABLE,
+            "dividend_income",
+        ]:
+            assert {"variable": variable, "geo_level": "national"} in include_rules
+
     def test_training_config_includes_soi_ltcg_target(self):
         config = load_target_config(
             str(
diff --git a/tests/unit/test_etl_national_targets.py b/tests/unit/test_etl_national_targets.py
diff --git a/tests/unit/test_upload_completed_datasets.py b/tests/unit/test_upload_completed_datasets.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+Ensure BEA NIPA direct-sum targets are selected by default calibration and fail publication validation when enhanced CPS employment income misses the wages target.`