Historical PolicyEngine US CTC reform reproduction for Nov 1 2025 package + HF snapshot

README.md

Historical PolicyEngine US CTC Reform Reproduction

This directory contains an executed notebook reproducing the reform run against the historical PolicyEngine US stack current by the end of November 1, 2025 in America/New_York.

It includes both the main credit aggregates and the federal/state/payroll tax decomposition behind the household_net_income change.

Re-execution

Run the notebook from a clean environment with:

uv run \
  --with 'policyengine-us==1.428.0' \
  --with 'policyengine-core==3.20.1' \
  --with 'huggingface_hub' \
  --with 'nbformat' \
  python /Users/maxghenis/tmp/ctc_historical_repro/execute_notebook.py

This rewrites the notebook in place with executed outputs. You can also open the notebook in Jupyter or VS Code after installing the same pinned packages and rerun the cells manually.

To reproduce the aggregates directly without touching the notebook:

uv run \
  --with 'policyengine-us==1.428.0' \
  --with 'policyengine-core==3.20.1' \
  --with 'huggingface_hub' \
  python /Users/maxghenis/tmp/ctc_historical_repro/run_historical_reform.py

The notebook itself asserts the package versions and downloads the exact Hugging Face revision:

• policyengine-us==1.428.0
• policyengine-core==3.20.1
• HF commit 8283acff6cb61f752970c47f66e7e28db762454f
• dataset enhanced_cps_2024.h5

execute_notebook.py

import ast
import io
import warnings
from contextlib import redirect_stderr, redirect_stdout
from pathlib import Path
from pprint import pformat

import nbformat


NOTEBOOK_PATH = Path(
    "/Users/maxghenis/tmp/ctc_historical_repro/policyengine_historical_ctc_reform_2025_11_01.ipynb"
)

warnings.filterwarnings("ignore", category=SyntaxWarning)


def _execute_code(source: str, namespace: dict):
    tree = ast.parse(source)
    body = tree.body
    last_value = None

    stdout_buffer = io.StringIO()
    stderr_buffer = io.StringIO()
    with redirect_stdout(stdout_buffer), redirect_stderr(stderr_buffer):
        if body and isinstance(body[-1], ast.Expr):
            prefix = ast.Module(body=body[:-1], type_ignores=[])
            if body[:-1]:
                exec(compile(prefix, "<notebook-cell>", "exec"), namespace)
            expr = ast.Expression(body[-1].value)
            last_value = eval(compile(expr, "<notebook-cell>", "eval"), namespace)
        else:
            exec(compile(tree, "<notebook-cell>", "exec"), namespace)

    return stdout_buffer.getvalue(), stderr_buffer.getvalue(), last_value


def main() -> None:
    notebook = nbformat.read(NOTEBOOK_PATH.open(encoding="utf-8"), as_version=4)
    namespace: dict = {}
    execution_count = 1

    for cell in notebook.cells:
        if cell.cell_type != "code":
            continue

        stdout_text, stderr_text, result = _execute_code(cell.source, namespace)
        outputs = []

        if stdout_text:
            outputs.append(
                nbformat.v4.new_output(
                    output_type="stream",
                    name="stdout",
                    text=stdout_text,
                )
            )
        if stderr_text:
            outputs.append(
                nbformat.v4.new_output(
                    output_type="stream",
                    name="stderr",
                    text=stderr_text,
                )
            )
        if result is not None:
            outputs.append(
                nbformat.v4.new_output(
                    output_type="execute_result",
                    execution_count=execution_count,
                    data={"text/plain": pformat(result, width=100)},
                    metadata={},
                )
            )

        cell["execution_count"] = execution_count
        cell["outputs"] = outputs
        execution_count += 1

    nbformat.write(notebook, NOTEBOOK_PATH.open("w", encoding="utf-8"))


if __name__ == "__main__":
    main()

policyengine_historical_ctc_reform_2025_11_01.ipynb

run_historical_reform.py

from importlib.metadata import version

from huggingface_hub import hf_hub_download
from policyengine_core.reforms import Reform
from policyengine_us import Microsimulation


EXPECTED_POLICYENGINE_US = "1.428.0"
EXPECTED_POLICYENGINE_CORE = "3.20.1"
HF_COMMIT = "8283acff6cb61f752970c47f66e7e28db762454f"
FILENAME = "enhanced_cps_2024.h5"
LOCAL_DIR = "/tmp/peus-historical-0fYXlB"


assert version("policyengine-us") == EXPECTED_POLICYENGINE_US
assert version("policyengine-core") == EXPECTED_POLICYENGINE_CORE

dataset_path = hf_hub_download(
    repo_id="policyengine/policyengine-us-data",
    repo_type="model",
    filename=FILENAME,
    revision=HF_COMMIT,
    local_dir=LOCAL_DIR,
)

reform = Reform.from_dict(
    {
        "gov.irs.credits.eitc.max[0].amount": {"2025-01-01.2100-12-31": 2000},
        "gov.irs.credits.eitc.max[1].amount": {"2025-01-01.2100-12-31": 2000},
        "gov.irs.credits.eitc.max[2].amount": {"2025-01-01.2100-12-31": 2000},
        "gov.irs.credits.eitc.max[3].amount": {"2025-01-01.2100-12-31": 2000},
        "gov.irs.credits.ctc.phase_out.amount": {"2025-01-01.2100-12-31": 25},
        "gov.irs.credits.ctc.amount.arpa[0].amount": {"2025-01-01.2100-12-31": 4800},
        "gov.irs.credits.ctc.amount.arpa[1].amount": {"2025-01-01.2100-12-31": 4800},
        "gov.irs.credits.ctc.phase_out.arpa.amount": {"2025-01-01.2100-12-31": 25},
        "gov.contrib.ctc.minimum_refundable.in_effect": {"2025-01-01.2100-12-31": True},
        "gov.contrib.ctc.per_child_phase_in.in_effect": {"2025-01-01.2100-12-31": True},
        "gov.irs.credits.ctc.phase_out.arpa.in_effect": {"2025-01-01.2100-12-31": True},
        "gov.irs.credits.ctc.refundable.phase_in.rate": {"2025-01-01.2100-12-31": 0.2},
        "gov.irs.credits.eitc.phase_in_rate[0].amount": {"2025-01-01.2100-12-31": 0.2},
        "gov.irs.credits.eitc.phase_in_rate[1].amount": {"2025-01-01.2100-12-31": 0.2},
        "gov.irs.credits.eitc.phase_in_rate[2].amount": {"2025-01-01.2100-12-31": 0.2},
        "gov.irs.credits.eitc.phase_in_rate[3].amount": {"2025-01-01.2100-12-31": 0.2},
        "gov.contrib.ctc.per_child_phase_out.in_effect": {"2025-01-01.2100-12-31": True},
        "gov.irs.credits.ctc.phase_out.threshold.JOINT": {"2025-01-01.2100-12-31": 200000},
        "gov.irs.credits.ctc.refundable.individual_max": {"2025-01-01.2100-12-31": 4800},
        "gov.irs.credits.eitc.phase_out.rate[0].amount": {"2025-01-01.2100-12-31": 0.1},
        "gov.irs.credits.eitc.phase_out.rate[1].amount": {"2025-01-01.2100-12-31": 0.1},
        "gov.irs.credits.eitc.phase_out.rate[2].amount": {"2025-01-01.2100-12-31": 0.1},
        "gov.irs.credits.eitc.phase_out.rate[3].amount": {"2025-01-01.2100-12-31": 0.1},
        "gov.irs.credits.ctc.phase_out.threshold.SINGLE": {"2025-01-01.2100-12-31": 100000},
        "gov.irs.credits.eitc.phase_out.start[0].amount": {"2025-01-01.2100-12-31": 20000},
        "gov.irs.credits.eitc.phase_out.start[1].amount": {"2025-01-01.2100-12-31": 20000},
        "gov.irs.credits.eitc.phase_out.start[2].amount": {"2025-01-01.2100-12-31": 20000},
        "gov.irs.credits.eitc.phase_out.start[3].amount": {"2025-01-01.2100-12-31": 20000},
        "gov.irs.credits.ctc.phase_out.threshold.SEPARATE": {"2025-01-01.2100-12-31": 100000},
        "gov.contrib.ctc.per_child_phase_out.avoid_overlap": {"2025-01-01.2100-12-31": True},
        "gov.irs.credits.ctc.refundable.phase_in.threshold": {"2025-01-01.2100-12-31": 0},
        "gov.irs.credits.ctc.phase_out.arpa.threshold.JOINT": {"2025-01-01.2100-12-31": 35000},
        "gov.contrib.ctc.minimum_refundable.amount[0].amount": {"2025-01-01.2100-12-31": 2400},
        "gov.contrib.ctc.minimum_refundable.amount[1].amount": {"2025-01-01.2100-12-31": 2400},
        "gov.irs.credits.ctc.phase_out.arpa.threshold.SINGLE": {"2025-01-01.2100-12-31": 25000},
        "gov.irs.credits.eitc.phase_out.joint_bonus[0].amount": {"2025-01-01.2100-12-31": 7000},
        "gov.irs.credits.eitc.phase_out.joint_bonus[1].amount": {"2025-01-01.2100-12-31": 7000},
        "gov.irs.credits.ctc.phase_out.arpa.threshold.SEPARATE": {"2025-01-01.2100-12-31": 25000},
        "gov.irs.credits.ctc.phase_out.threshold.SURVIVING_SPOUSE": {"2025-01-01.2100-12-31": 100000},
        "gov.irs.credits.ctc.phase_out.threshold.HEAD_OF_HOUSEHOLD": {"2025-01-01.2100-12-31": 100000},
        "gov.irs.credits.ctc.phase_out.arpa.threshold.SURVIVING_SPOUSE": {"2025-01-01.2100-12-31": 25000},
        "gov.irs.credits.ctc.phase_out.arpa.threshold.HEAD_OF_HOUSEHOLD": {"2025-01-01.2100-12-31": 25000},
    },
    country_id="us",
)

baseline = Microsimulation(dataset=dataset_path)
reformed = Microsimulation(dataset=dataset_path, reform=reform)


def total(simulation, variable, period=2025):
    return float(simulation.calculate(variable, period=period).sum())


results = {
    "package_version": version("policyengine-us"),
    "core_version": version("policyengine-core"),
    "hf_commit": HF_COMMIT,
    "dataset_path": dataset_path,
    "household_net_income_baseline": total(baseline, "household_net_income"),
    "household_net_income_reformed": total(reformed, "household_net_income"),
}
results["household_net_income_delta"] = (
    results["household_net_income_reformed"] - results["household_net_income_baseline"]
)

for variable in ["ctc", "refundable_ctc", "non_refundable_ctc", "eitc"]:
    baseline_total = total(baseline, variable)
    reformed_total = total(reformed, variable)
    results[f"{variable}_baseline"] = baseline_total
    results[f"{variable}_reformed"] = reformed_total
    results[f"{variable}_delta"] = reformed_total - baseline_total

for variable in [
    "income_tax_before_refundable_credits",
    "income_tax",
    "household_state_tax_before_refundable_credits",
    "state_income_tax_before_refundable_credits",
    "state_income_tax",
    "household_tax_before_refundable_credits",
    "household_tax",
    "employee_payroll_tax",
    "self_employment_tax",
    "household_refundable_tax_credits",
]:
    baseline_total = total(baseline, variable)
    reformed_total = total(reformed, variable)
    results[f"{variable}_baseline"] = baseline_total
    results[f"{variable}_reformed"] = reformed_total
    results[f"{variable}_delta"] = reformed_total - baseline_total

for key, value in results.items():
    print(f"{key}={value}")