Cover wealth and Part B Arch targets

Author: MaxGhenis

docs/arch-target-gap-queue.md

@@ -53,8 +53,9 @@ It excludes only cells with explicit reasons in
 - SOI multi-domain cells that would require joint AGI, filing status, and
   positive income-tax-before-credits facts not currently published by the loaded
   SOI packages
-- survey-heavy or model-input cells such as rent, net worth, child support,
-  medical-premium subcomponents, SPM capped expenses, and `ssn_card_type`
+- survey-heavy or model-input cells such as rent, child support,
+  non-Part-B medical premium/expense components, SPM capped expenses, and
+  `ssn_card_type`
 - source-near but non-equivalent rows such as `childcare_expenses`, where IRS
   credit expenses and W-2 dependent-care benefits are narrower tax concepts
 - pregnancy stock by state, where live births are a flow rather than a direct
@@ -74,11 +75,13 @@ Inputs:
 - `/tmp/arch-suite-soi-historic-table-2-state-agi-2022/consumer_facts.jsonl`
 - `/tmp/arch-suite-soi-w2-statistics-2020/consumer_facts.jsonl`
 - `/tmp/arch-suite-soi-table-1-4-2023/consumer_facts.jsonl`
+- `/tmp/arch-suite-federal-reserve-z1-household-net-worth/consumer_facts.jsonl`
+- `/tmp/arch-suite-cms-medicare-trustees-report-2025-part-b-premium-income/consumer_facts.jsonl`
 
 Command:
 
 ```bash
-uv run microplex-us-arch-target-refresh \
+uv run --extra policyengine microplex-us-arch-target-refresh \
   --arch-targets-db /Users/maxghenis/CosilicoAI/arch/arch/fixtures/consumer_facts.jsonl \
   --arch-targets-db /Users/maxghenis/CosilicoAI/arch/macro/targets.db \
   --arch-targets-db /tmp/arch-suite-hhs-acf-tanf-caseload-2024/consumer_facts.jsonl \
@@ -87,38 +90,46 @@ uv run microplex-us-arch-target-refresh \
   --arch-targets-db /tmp/arch-suite-soi-historic-table-2-state-agi-2022/consumer_facts.jsonl \
   --arch-targets-db /tmp/arch-suite-soi-w2-statistics-2020/consumer_facts.jsonl \
   --arch-targets-db /tmp/arch-suite-soi-table-1-4-2023/consumer_facts.jsonl \
+  --arch-targets-db /tmp/arch-suite-federal-reserve-z1-household-net-worth/consumer_facts.jsonl \
+  --arch-targets-db /tmp/arch-suite-cms-medicare-trustees-report-2025-part-b-premium-income/consumer_facts.jsonl \
   --period 2024 \
   --profile pe_native_broad_source_backed \
-  --output-dir artifacts/arch-target-coverage
+  --output-dir artifacts/arch-target-coverage-source-backed
 ```
 
 Coverage:
 
-- 172 target cells in `pe_native_broad_source_backed`
-- 172 covered
+- 174 target cells in `pe_native_broad_source_backed`
+- 174 covered
 - 0 uncovered
 - 100.0% coverage
 
-The raw `pe_native_broad` profile remains at 172 of 189 covered with 17
-explicitly reviewed rows outside the source-backed boundary:
+The raw `pe_native_broad` profile is at 174 of 189 covered with 15 explicitly
+reviewed rows outside the source-backed boundary. Federal Reserve Z.1 household
+net worth and CMS Medicare Trustees Report Part B premium income are now
+source-backed.
 
 | Category | Rows |
 | --- | ---: |
-| `survey_or_model_input_deprioritized` | 12 |
 | `adapter_or_constraint_review` | 3 |
 | `source_mapping_review` | 2 |
+| `survey_or_model_input_deprioritized` | 10 |
 
 Generated outputs:
 
-- `artifacts/arch-target-coverage/pe_native_broad_source_backed_2024_coverage.json`
-- `artifacts/arch-target-coverage/pe_native_broad_source_backed_2024_gaps.json`
-- `artifacts/arch-target-coverage/pe_native_broad_source_backed_2024_gaps.csv`
-- `artifacts/arch-target-coverage/pe_native_broad_source_backed_2024_summary.md`
+- `artifacts/arch-target-coverage-source-backed/pe_native_broad_source_backed_2024_coverage.json`
+- `artifacts/arch-target-coverage-source-backed/pe_native_broad_source_backed_2024_gaps.json`
+- `artifacts/arch-target-coverage-source-backed/pe_native_broad_source_backed_2024_gaps.csv`
+- `artifacts/arch-target-coverage-source-backed/pe_native_broad_source_backed_2024_summary.md`
+- `artifacts/arch-target-coverage-broad-plus/pe_native_broad_2024_coverage.json`
+- `artifacts/arch-target-coverage-broad-plus/pe_native_broad_2024_gaps.json`
+- `artifacts/arch-target-coverage-broad-plus/pe_native_broad_2024_gaps.csv`
+- `artifacts/arch-target-coverage-broad-plus/pe_native_broad_2024_summary.md`
 
 Remaining work is concentrated in:
 
 - the raw `pe_native_broad` cells excluded from the source-backed profile, if a
   future primary publisher source can support them without changing semantics
-- UK profile parity, which should follow the same pattern: keep the raw PE
-  target surface intact and expose a source-backed profile with explicit
-  exclusions where source equivalence is not defensible
+- keeping the UK source-backed/raw boundary aligned with the same rule: leave
+  raw PE target rows visible, and exclude only rows where source equivalence is
+  not defensible

src/microplex_us/pipelines/us.py

@@ -83,6 +83,7 @@
 from microplex_us.policyengine.us import (
     subset_policyengine_tables_by_households as _subset_policyengine_tables_by_households,
 )
+from microplex_us.targets.arch import resolve_arch_sqlite_target_provider
 from microplex_us.variables import (
     PE_STYLE_PUF_IRS_DEMOGRAPHIC_PREDICTORS,
     DonorMatchStrategy,
@@ -1407,6 +1408,8 @@ class USMicroplexBuildConfig:
     policyengine_prefer_existing_tax_unit_ids: bool = False
     policyengine_quantity_targets: tuple[PolicyEngineUSQuantityTarget, ...] = ()
     policyengine_targets_db: str | None = None
+    arch_targets_db: str | tuple[str, ...] | None = None
+    calibration_target_source: Literal["policyengine", "arch"] = "policyengine"
     policyengine_target_period: int | None = None
     policyengine_target_variables: tuple[str, ...] = ()
     policyengine_target_domains: tuple[str, ...] = ()
@@ -1786,7 +1789,7 @@ def build_from_frames(
             rows=int(len(synthetic_data)),
             columns=int(len(synthetic_data.columns)),
         )
-        if self.config.policyengine_targets_db is not None:
+        if self._has_policyengine_calibration_targets():
             _emit_us_pipeline_progress(
                 "US microplex build: policyengine tables start",
                 rows=int(len(synthetic_data)),
@@ -2816,10 +2819,7 @@ def calibrate_policyengine_tables(
         tables: PolicyEngineUSEntityTableBundle,
     ) -> tuple[PolicyEngineUSEntityTableBundle, pd.DataFrame, dict[str, Any]]:
         """Calibrate household weights using PolicyEngine US target DB constraints."""
-        if self.config.policyengine_targets_db is None:
-            raise ValueError("policyengine_targets_db is required for DB calibration")
-
-        provider = PolicyEngineUSDBTargetProvider(self.config.policyengine_targets_db)
+        provider, _source = self._resolve_calibration_target_provider()
         target_period = (
             self.config.policyengine_target_period
             or self.config.policyengine_dataset_year
@@ -3629,9 +3629,33 @@ def _resolve_policyengine_calibration_targets(
             materialization_failures,
         )
 
+    def _has_policyengine_calibration_targets(self) -> bool:
+        if self.config.calibration_target_source == "arch":
+            return self.config.arch_targets_db is not None
+        return self.config.policyengine_targets_db is not None
+
+    def _resolve_calibration_target_provider(self):
+        if self.config.calibration_target_source == "arch":
+            if self.config.arch_targets_db is None:
+                raise ValueError(
+                    "arch_targets_db is required when calibration_target_source='arch'"
+                )
+            return (
+                resolve_arch_sqlite_target_provider(self.config.arch_targets_db),
+                "arch",
+            )
+        if self.config.policyengine_targets_db is None:
+            raise ValueError(
+                "policyengine_targets_db is required for PolicyEngine DB calibration"
+            )
+        return (
+            PolicyEngineUSDBTargetProvider(self.config.policyengine_targets_db),
+            "policyengine",
+        )
+
     def _load_policyengine_target_set(
         self,
-        provider: PolicyEngineUSDBTargetProvider,
+        provider: Any,
         *,
         bindings: dict[str, PolicyEngineUSVariableBinding],
         period: int,

src/microplex_us/policyengine/target_profiles.py

@@ -807,25 +807,6 @@ def _target_cell_key(cell: PolicyEngineUSTargetCell) -> PolicyEngineUSTargetCell
         "This premium component is a modeled/survey input; no accepted primary "
         "aggregate source mapping is encoded for Arch."
     ),
-    (
-        "medicare_part_b_premiums",
-        "national",
-        None,
-        None,
-    ): (
-        "PolicyEngine Medicare Part B premiums depend on person-level "
-        "enrollment and IRMAA status; no accepted aggregate source fact is "
-        "encoded for this modeled input."
-    ),
-    (
-        "net_worth",
-        "national",
-        None,
-        None,
-    ): (
-        "Net worth is a wealth survey/model input; no accepted primary "
-        "administrative aggregate source mapping is encoded for Arch."
-    ),
     (
         "other_medical_expenses",
         "national",

src/microplex_us/targets/arch.py

@@ -48,7 +48,9 @@
     "census-stc": "CENSUS_STC",
     "usda-snap": "USDA_SNAP",
     "cms-aca": "CMS_ACA",
+    "cms-medicare": "CMS_MEDICARE",
     "cms-medicaid": "CMS_MEDICAID",
+    "federal-reserve": "FEDERAL_RESERVE",
     "hhs-acf-liheap": "HHS_ACF_LIHEAP",
     "hhs-acf-tanf": "HHS_ACF_TANF",
 }
@@ -134,6 +136,8 @@
     "ssi_payments": "ssi",
     "ssi_total_payments": "ssi",
     "tanf_cash_assistance": "tanf",
+    "medicare_part_b_premiums": "medicare_part_b_premiums",
+    "net_worth": "net_worth",
 }
 
 ARCH_SELF_DOMAIN_AMOUNT_VARIABLES = frozenset(
@@ -408,6 +412,14 @@
         "self_employed_pension_contribution_ald",
         "AMOUNT",
     ),
+    "federal_reserve.z1.households_nonprofits_net_worth": (
+        "net_worth",
+        "AMOUNT",
+    ),
+    "cms_medicare.part_b_premium_income": (
+        "medicare_part_b_premiums",
+        "AMOUNT",
+    ),
     "census_decennial.resident_population": ("population", "COUNT"),
     "census_decennial.occupied_housing_units": ("household_count", "COUNT"),
     "census_pep.resident_population": ("population", "COUNT"),
@@ -570,6 +582,7 @@
 ARCH_FACT_DOMAIN_CONSTRAINTS = {
     "all_individual_income_tax_returns": (("is_tax_filer", "==", "1"),),
     "form_w2_items": (),
+    "household_balance_sheet": (),
     "individual_income_tax_returns": (("is_tax_filer", "==", "1"),),
     "individual_income_tax_returns_excluding_dependents": (
         ("is_dependent", "==", "0"),
@@ -584,6 +597,7 @@
     "aca_marketplace_effectuated_enrollment": (),
     "aca_marketplace_qhp_selections": (),
     "medicaid_chip_enrollment": (),
+    "medicare_financing": (),
     "national_health_expenditures": (),
     "personal_current_transfer_receipts": (),
     "personal_income": (),
@@ -607,10 +621,13 @@
 ARCH_IGNORED_FACT_CONSTRAINT_VARIABLES = frozenset(
     {
         "administering_entity",
+        "amount_basis",
         "bea_nipa.series_code",
         "bea_regional.geo_name",
         "bea_regional.line_code",
         "bea_regional.table_name",
+        "medicare.financing_component",
+        "medicare.part",
         "program",
     }
 )
@@ -655,7 +672,9 @@
     "tip_income": EntityType.PERSON,
     "traditional_401k_contributions": EntityType.PERSON,
     "unemployment_compensation": EntityType.PERSON,
+    "medicare_part_b_premiums": EntityType.PERSON,
     "medicaid": EntityType.PERSON,
+    "net_worth": EntityType.HOUSEHOLD,
     "social_security": EntityType.PERSON,
     "social_security_dependents": EntityType.PERSON,
     "social_security_disability": EntityType.PERSON,
@@ -809,7 +828,9 @@
     "income_tax_positive": "income_tax_liability",
     "income_tax_before_credits": "income_tax_before_credits_amount",
     "interest_deduction": "interest_paid_deduction_amount",
+    "medicare_part_b_premiums": "medicare_part_b_premiums",
     "net_capital_gains": "net_capital_gains_amount",
+    "net_worth": "net_worth",
     "real_estate_taxes": "real_estate_taxes_amount",
     "roth_401k_contributions": "roth_401k_contributions",
     "self_employed_pension_contribution_ald": (
@@ -886,8 +907,6 @@
         "child_support_expense",
         "child_support_received",
         "health_insurance_premiums_without_medicare_part_b",
-        "medicare_part_b_premiums",
-        "net_worth",
         "other_medical_expenses",
         "over_the_counter_health_expenses",
         "rent",
@@ -5189,10 +5208,12 @@ def _arch_gap_queue_sort_key(row: ArchTargetGapQueueRow) -> tuple[Any, ...]:
         "CENSUS_ACS": 2,
         "CMS_ACA": 3,
         "CMS_MEDICAID": 4,
-        "USDA_SNAP": 5,
-        "SSA": 6,
-        "HHS_ACF_TANF": 7,
-        "HHS_ACF_LIHEAP": 8,
+        "CMS_MEDICARE": 5,
+        "USDA_SNAP": 6,
+        "SSA": 7,
+        "HHS_ACF_TANF": 8,
+        "HHS_ACF_LIHEAP": 9,
+        "FEDERAL_RESERVE": 10,
     }.get(str(row.expected_source), 99)
     return (
         row.covered,
@@ -5238,6 +5259,10 @@ def _arch_gap_expected_source(cell: dict[str, Any]) -> str | None:
         return "SSA"
     if variable == "state_income_tax":
         return "CENSUS_STC"
+    if variable == "medicare_part_b_premiums":
+        return "CMS_MEDICARE"
+    if variable == "net_worth":
+        return "FEDERAL_RESERVE"
     if variable == "person_count":
         if _normalize_geo_level(cell.get("geo_level")) in {"sldu", "sldl"}:
             return "CENSUS_DECENNIAL"
@@ -5483,6 +5508,10 @@ def _arch_gap_expected_source_table(
         return "CMS Marketplace Open Enrollment public-use files"
     if expected_source == "CMS_MEDICAID":
         return "CMS Medicaid enrollment and expenditure reports"
+    if expected_source == "CMS_MEDICARE":
+        return "CMS Medicare Trustees Report Part B premium income"
+    if expected_source == "FEDERAL_RESERVE":
+        return "Federal Reserve Financial Accounts Z.1 household net worth"
     if expected_source == "SSA":
         return "SSA Annual Statistical Supplement"
     if expected_source == "HHS_ACF_TANF":

tests/policyengine/test_target_profiles.py

@@ -370,10 +370,10 @@ def test_source_backed_profile_excludes_only_documented_non_source_cells() -> No
     }
 
     assert len(broad_cells) == 189
-    assert len(exclusion_reasons) == 17
+    assert len(exclusion_reasons) == 15
     assert all(reason for reason in exclusion_reasons.values())
     assert set(exclusion_reasons) <= broad_cells
-    assert len(source_backed_cells) == 172
+    assert len(source_backed_cells) == 174
     assert source_backed_cells == broad_cells - set(exclusion_reasons)
     assert (
         "childcare_expenses",
@@ -393,3 +393,15 @@ def test_source_backed_profile_excludes_only_documented_non_source_cells() -> No
         None,
         None,
     ) in source_backed_cells
+    assert (
+        "medicare_part_b_premiums",
+        "national",
+        None,
+        None,
+    ) in source_backed_cells
+    assert (
+        "net_worth",
+        "national",
+        None,
+        None,
+    ) in source_backed_cells