From d24ea7b11963f04001180c43c609ba1a662660dc Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Wed, 17 Jun 2026 09:43:49 -0400 Subject: [PATCH 1/2] Prioritize CTC fiscal target calibration --- .../src/populace/build/us/fiscal_targets.py | 6 ++ .../tests/test_us_fiscal_refresh_builder.py | 75 +++++++++++++++++++ .../tests/test_us_fiscal_targets.py | 2 + .../src/populace/data/contract.py | 8 ++ packages/populace-data/tests/test_contract.py | 40 +++++++++- tools/build_us_fiscal_refresh_release.py | 22 +++++- 6 files changed, 150 insertions(+), 3 deletions(-) diff --git a/packages/populace-build/src/populace/build/us/fiscal_targets.py b/packages/populace-build/src/populace/build/us/fiscal_targets.py index e1705fa..499fbbd 100644 --- a/packages/populace-build/src/populace/build/us/fiscal_targets.py +++ b/packages/populace-build/src/populace/build/us/fiscal_targets.py @@ -1213,6 +1213,12 @@ def _str_at(obj: object, *path: str) -> str: accepted_families=("irs_soi",), required_metadata=(("target_role", "refundable_ctc_total"),), ), + TargetCoverageRequirement( + requirement_id="ctc_total", + label="Child Tax Credit total", + accepted_families=("irs_soi",), + required_metadata=(("target_role", "ctc_total"),), + ), TargetCoverageRequirement( requirement_id="aca_marketplace", label="ACA marketplace spending and enrollment", diff --git a/packages/populace-build/tests/test_us_fiscal_refresh_builder.py b/packages/populace-build/tests/test_us_fiscal_refresh_builder.py index 34322bc..84d21de 100644 --- a/packages/populace-build/tests/test_us_fiscal_refresh_builder.py +++ b/packages/populace-build/tests/test_us_fiscal_refresh_builder.py @@ -24,6 +24,8 @@ def _load_builder_module(): def _passing_critical_diagnostics(builder) -> tuple[SimpleNamespace, ...]: + ctc_target = 82_863_353_000.0 + ctc_final = 92_000_000_000.0 return ( SimpleNamespace( name=( @@ -55,6 +57,15 @@ def _passing_critical_diagnostics(builder) -> tuple[SimpleNamespace, ...]: final_estimate=1_541_540_768_722.367, relative_error=0.047815394099604024, ), + SimpleNamespace( + name=( + f"irs_soi.ty2022.historic_table_2.us.all.ctc_amount@{builder.PERIOD}" + ), + target=ctc_target, + initial_estimate=132_000_000_000.0, + final_estimate=ctc_final, + relative_error=(ctc_final - ctc_target) / ctc_target, + ), ) @@ -419,6 +430,70 @@ def test_target_value_loss_weights_prioritize_large_targets() -> None: assert weights[1] > weights[0] * 10_000 +def test_target_value_loss_weights_boost_ctc_total_role() -> None: + builder = _load_builder_module() + registry = TargetRegistry( + ( + TargetSpec( + name="ctc_total", + entity="tax_unit", + value=100.0, + source="fixture", + metadata={"target_role": "ctc_total"}, + ), + TargetSpec( + name="other_same_value", + entity="tax_unit", + value=100.0, + source="fixture", + metadata={"target_role": "eitc_total"}, + ), + TargetSpec( + name="legacy_named_ctc_without_role", + entity="tax_unit", + value=100.0, + source="fixture", + ), + ), + country="us", + ) + + weights = builder._target_value_loss_weights(registry) + + assert weights.mean() == 1.0 + assert weights[0] == weights[1] * builder.US_CTC_TARGET_LOSS_WEIGHT_MULTIPLIER + assert weights[2] == weights[1] + + +def test_release_gate_failures_reject_bad_ctc_fit() -> None: + builder = _load_builder_module() + ctc_target = 82_863_353_000.0 + ctc_final = 132_511_000_000.0 + diagnostics = list(_passing_critical_diagnostics(builder)) + diagnostics[-1] = SimpleNamespace( + name=(f"irs_soi.ty2022.historic_table_2.us.all.ctc_amount@{builder.PERIOD}"), + target=ctc_target, + initial_estimate=132_000_000_000.0, + final_estimate=ctc_final, + relative_error=(ctc_final - ctc_target) / ctc_target, + ) + result = SimpleNamespace( + skipped=(), + diagnostics=tuple(diagnostics), + initial_loss=10.0, + final_loss=5.0, + ) + + failures = builder._release_gate_failures( + result, + {"dropped_target_names": []}, + ) + + assert len(failures) == 1 + assert "Child Tax Credit amount" in failures[0] + assert "relative_error=0.599151" in failures[0] + + def test_health_input_signal_gate_rejects_degenerate_aca_inputs() -> None: builder = _load_builder_module() diff --git a/packages/populace-build/tests/test_us_fiscal_targets.py b/packages/populace-build/tests/test_us_fiscal_targets.py index b18a6a6..93d23b6 100644 --- a/packages/populace-build/tests/test_us_fiscal_targets.py +++ b/packages/populace-build/tests/test_us_fiscal_targets.py @@ -45,6 +45,7 @@ "ssa_dependents_total", "eitc_total", "refundable_ctc_total", + "ctc_total", "aca_spending", "aca_enrollment", "medicaid_enrollment", @@ -587,6 +588,7 @@ def test_us_fiscal_requirements_include_reference_program_and_tax_controls() -> assert "ssa_social_security_components" in ids assert "eitc_total" in ids assert "refundable_ctc_total" in ids + assert "ctc_total" in ids assert "aca_marketplace" in ids assert "medicaid_spending" not in ids assert "medicaid_enrollment" in ids diff --git a/packages/populace-data/src/populace/data/contract.py b/packages/populace-data/src/populace/data/contract.py index bf68a0e..7e77bf2 100644 --- a/packages/populace-data/src/populace/data/contract.py +++ b/packages/populace-data/src/populace/data/contract.py @@ -88,6 +88,14 @@ "families": ("ssa",), "target_roles": ("social_security_total",), }, + { + "requirement_id": "ctc_amount", + "label": "Child Tax Credit amount", + "max_abs_relative_error": 0.20, + "names": ("irs_soi.ty2022.historic_table_2.us.all.ctc_amount@2024",), + "families": ("irs_soi",), + "target_roles": ("ctc_total",), + }, ) diff --git a/packages/populace-data/tests/test_contract.py b/packages/populace-data/tests/test_contract.py index 58844ec..7d5b564 100644 --- a/packages/populace-data/tests/test_contract.py +++ b/packages/populace-data/tests/test_contract.py @@ -30,7 +30,7 @@ SOURCE_COVERAGE_SHA = "9" * 64 TARGET_SURFACE_SHA = "e" * 64 REGISTRY_VERSION = "registryabc123" -TARGET_COUNT = 4 +TARGET_COUNT = 5 def _model_package(release_id: str) -> tuple[str, str]: @@ -201,6 +201,16 @@ def _calibration_diagnostics() -> dict: family="ssa", target_role="social_security_total", ), + _target_row( + "irs_soi.ty2022.historic_table_2.us.all.ctc_amount@2024", + target_name="irs_soi.ty2022.historic_table_2.us.all.ctc_amount", + target=82_863_353_000.0, + initial_estimate=132_000_000_000.0, + final_estimate=92_000_000_000.0, + relative_error=(92_000_000_000.0 - 82_863_353_000.0) / 82_863_353_000.0, + family="irs_soi", + target_role="ctc_total", + ), ], } @@ -278,7 +288,7 @@ def _source_coverage_diagnostics() -> dict: }, "irs_soi": { "label": "IRS Statistics of Income", - "target_count": 2, + "target_count": 3, "sources": ["IRS SOI Historic Table 2"], "reference_urls": ["https://example.test/soi"], }, @@ -389,6 +399,32 @@ def test_us_release_recomputes_critical_target_fit(release_dir: Path) -> None: assert "relative_error=-0.650806" in failures +def test_us_release_rejects_bad_ctc_fit(release_dir: Path) -> None: + diagnostics = _calibration_diagnostics() + target = next( + row + for row in diagnostics["targets"] + if row["name"] == "irs_soi.ty2022.historic_table_2.us.all.ctc_amount@2024" + ) + ctc_target = 82_863_353_000.0 + ctc_final = 132_511_000_000.0 + target["final_estimate"] = ctc_final + target["relative_error"] = (ctc_final - ctc_target) / ctc_target + _write_json_and_refresh_manifest_hash( + release_dir, + filename="calibration_diagnostics.json", + artifact_key="calibration_diagnostics", + payload=diagnostics, + ) + + with pytest.raises(ReleaseContractError) as excinfo: + validate_release_dir(release_dir) + + failures = "\n".join(excinfo.value.failures) + assert "Child Tax Credit amount" in failures + assert "relative_error=0.599151" in failures + + def test_us_release_requires_critical_targets(release_dir: Path) -> None: diagnostics = _calibration_diagnostics() diagnostics["targets"] = [ diff --git a/tools/build_us_fiscal_refresh_release.py b/tools/build_us_fiscal_refresh_release.py index 8ee2b06..440c0c1 100644 --- a/tools/build_us_fiscal_refresh_release.py +++ b/tools/build_us_fiscal_refresh_release.py @@ -68,7 +68,11 @@ CALIBRATION_FILENAME = "populace_us_2024_calibration.npz" POST_EXPORT_ABSOLUTE_TOLERANCE = 1_000_000.0 POST_EXPORT_RELATIVE_TOLERANCE = 5e-4 -US_FISCAL_TARGET_LOSS_WEIGHTING = "absolute_target_value" +US_FISCAL_TARGET_LOSS_WEIGHTING = "absolute_target_value_with_ctc_priority" +US_CTC_TARGET_LOSS_WEIGHT_MULTIPLIER = 10.0 +US_FISCAL_TARGET_ROLE_LOSS_MULTIPLIERS = { + "ctc_total": US_CTC_TARGET_LOSS_WEIGHT_MULTIPLIER, +} US_CRITICAL_TARGET_FIT_REQUIREMENTS = ( { "name": ( @@ -94,6 +98,11 @@ "label": "Social Security benefits", "max_abs_relative_error": 0.05, }, + { + "name": (f"irs_soi.ty2022.historic_table_2.us.all.ctc_amount@{PERIOD}"), + "label": "Child Tax Credit amount", + "max_abs_relative_error": 0.20, + }, ) DIRECT_ACTIVE_ALIASES = ( @@ -1279,6 +1288,17 @@ def _write_npz(path: Path, *, result, registry: TargetRegistry) -> None: def _target_value_loss_weights(registry: TargetRegistry) -> np.ndarray: values = np.asarray([abs(spec.value) for spec in registry.specs], dtype=np.float64) weights = np.maximum(values, 1.0) + multipliers = np.asarray( + [ + US_FISCAL_TARGET_ROLE_LOSS_MULTIPLIERS.get( + spec.metadata.get("target_role", ""), + 1.0, + ) + for spec in registry.specs + ], + dtype=np.float64, + ) + weights *= multipliers return weights / weights.mean() From fe1472c932d823678187d122817d5c758636373a Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Wed, 17 Jun 2026 09:57:32 -0400 Subject: [PATCH 2/2] Update release fixtures for CTC critical target --- packages/populace-data/tests/test_release.py | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/packages/populace-data/tests/test_release.py b/packages/populace-data/tests/test_release.py index e62f989..3e79d01 100644 --- a/packages/populace-data/tests/test_release.py +++ b/packages/populace-data/tests/test_release.py @@ -33,7 +33,7 @@ CALIBRATION_SHA = "ac31f2be76a0f8dc4da89b6935aa4b8b1b2e1bd4eb3d03b809333084f25b376e" TARGET_SURFACE_SHA = "e" * 64 REGISTRY_VERSION = "registryabc123" -TARGET_COUNT = 4 +TARGET_COUNT = 5 def _calibration_diagnostics() -> dict: @@ -108,6 +108,16 @@ def _calibration_diagnostics() -> dict: family="ssa", target_role="social_security_total", ), + _target_row( + "irs_soi.ty2022.historic_table_2.us.all.ctc_amount@2024", + target_name="irs_soi.ty2022.historic_table_2.us.all.ctc_amount", + target=82_863_353_000.0, + initial_estimate=132_000_000_000.0, + final_estimate=92_000_000_000.0, + relative_error=(92_000_000_000.0 - 82_863_353_000.0) / 82_863_353_000.0, + family="irs_soi", + target_role="ctc_total", + ), ], } @@ -185,7 +195,7 @@ def _source_coverage_diagnostics() -> dict: }, "irs_soi": { "label": "IRS Statistics of Income", - "target_count": 2, + "target_count": 3, "sources": ["IRS SOI Historic Table 2"], "reference_urls": ["https://example.test/soi"], },