policyengine
ALWAYS load this skill before writing any Python that computes taxes, benefits, or policy impacts with PolicyEngine — household calculations, microsimulation, reform scoring, poverty or distributional analysis, state/district/constituency breakdowns. Triggers: policyengine, microsimulation, calculate_household, reform impact, budgetary impact, cost of a policy, revenue estimate, poverty rate, child poverty, winners and losers, decile, Gini, inequality, CTC, EITC, SNAP, income tax, universal credit, state-level analysis, congressional district, constituency, Microcosm (formerly Populace) dataset, MicroSeries, ensure_datasets, economic_impact_analysis, managed_microsimulation. NOT for: implementing new variables/parameters inside country models (use policyengine-model-development) or calling the REST API from JS (use policyengine-api).
PolicyEngine · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add PolicyEngine/policyengine-claude --skill policyengine技能说明
name: policyengine description: | ALWAYS load this skill before writing any Python that computes taxes, benefits, or policy impacts with PolicyEngine — household calculations, microsimulation, reform scoring, poverty or distributional analysis, state/district/constituency breakdowns. Triggers: policyengine, microsimulation, calculate_household, reform impact, budgetary impact, cost of a policy, revenue estimate, poverty rate, child poverty, winners and losers, decile, Gini, inequality, CTC, EITC, SNAP, income tax, universal credit, state-level analysis, congressional district, constituency, Microcosm (formerly Populace) dataset, MicroSeries, ensure_datasets, economic_impact_analysis, managed_microsimulation. NOT for: implementing new variables/parameters inside country models (use policyengine-model-development) or calling the REST API from JS (use policyengine-api). metadata: category: analysis
PolicyEngine Python analysis
The policyengine package (repo: PolicyEngine/policyengine.py) is the canonical Python
interface for both single-household calculations and population microsimulation. It pins a
certified model + data bundle, so results are reproducible and the data provenance is known.
Originally verified against policyengine 4.21.0 (2026-07); the marked examples re-run in CI against the latest release (5.0.1 at 2026-08). Re-verify the bundle when precision matters (see "Checking what you're running" below).
Setup
Country models are extras — bare policyengine installs neither:
uv pip install "policyengine[us]" # US model + certified US data bundle
uv pip install "policyengine[uk]" # UK model (population data needs HUGGING_FACE_TOKEN)
uv pip install "policyengine" # both countries
Analysis always runs on the latest released policyengine (>=5.0.1; resolve "latest"
from PyPI as described in "Checking what you're running"). Each release pins exactly-matched
country-model versions and the certified data bundle, which is what makes results
reproducible. Directly-imported country packages (policyengine_us / policyengine_uk) are
for model development and tests, not for analysis compute.
Household calculations (fast, ~2 GB RAM)
calculate_household answers "what does this specific household get/pay?" — no dataset
download, runs in seconds.
import policyengine as pe
result = pe.us.calculate_household(
people=[{"age": 40, "employment_income": 50_000}, {"age": 8}],
tax_unit={"filing_status": "HEAD_OF_HOUSEHOLD"},
household={"state_code": "CA"},
year=2026,
extra_variables=["income_tax"],
)
assert result.tax_unit.ctc == 2_200 # OBBBA CTC, 2026
assert round(result.household.household_net_income) == 46_358
print(result.spm_unit.snap, result.tax_unit.eitc, result.tax_unit.income_tax)
Result access is dot-attribute on singular entities — result.tax_unit.ctc, never
result.tax_unit[0]["ctc"]. Only result.person is a list (result.person[0].age). Entities:
person[i], marital_unit, family, spm_unit, tax_unit, household (US);
person[i], benunit, household (UK).
Each entity exposes a limited default column set — accessing anything else raises
AttributeError listing what's available and telling you the fix: pass
extra_variables=["variable_name"] to materialize it (as with income_tax above; the
default person columns don't include it).
Reforms are a flat dict of {parameter_path: value}:
import policyengine as pe
baseline = pe.us.calculate_household(
people=[{"age": 40, "employment_income": 50_000}, {"age": 8}],
tax_unit={"filing_status": "HEAD_OF_HOUSEHOLD"},
household={"state_code": "CA"},
year=2026,
)
reformed = pe.us.calculate_household(
people=[{"age": 40, "employment_income": 50_000}, {"age": 8}],
tax_unit={"filing_status": "HEAD_OF_HOUSEHOLD"},
household={"state_code": "CA"},
year=2026,
reform={"gov.irs.credits.ctc.amount.base[0].amount": 3_000},
)
assert reformed.tax_unit.ctc == 3_000
assert reformed.household.household_net_income - baseline.household.household_net_income == 800
UK works the same way:
uk = pe.uk.calculate_household(
people=[{"age": 35, "employment_income": 50_000}],
year=2026,
)
uk.person[0].income_tax
uk.household.hbai_household_net_income
To sweep an input (e.g. earnings 0→200k for an MTR curve), pass axes. Every variable on the
result then comes back as a list of values across the sweep instead of a scalar:
import policyengine as pe
result = pe.us.calculate_household(
people=[{"age": 40}],
tax_unit={"filing_status": "SINGLE"},
household={"state_code": "TX"},
year=2026,
axes=[[{"name": "employment_income", "min": 0, "max": 200_000, "count": 401}]],
)
earnings = result.person[0].employment_income # [0.0, 500.0, ..., 200000.0]
net = result.household.household_net_income # list of 401 values
assert len(earnings) == len(net) == 401
assert earnings[1] == 500.0
Population analysis (heavy: tens of GB RAM, minutes per simulation)
The canonical population flow builds year-specific datasets from the certified bundle, then
runs baseline and reform Simulations:
import policyengine as pe
from policyengine.core import Simulation
datasets = pe.us.ensure_datasets(years=[2026], data_folder="./data")
dataset = next(iter(datasets.values()))
baseline = Simulation(dataset=dataset, tax_benefit_model_version=pe.us.model)
reform = Simulation(
dataset=dataset,
tax_benefit_model_version=pe.us.model,
policy={"gov.irs.credits.ctc.amount.base[0].amount": 3_000},
)
analysis = pe.us.economic_impact_analysis(baseline, reform)
budget = pe.us.calculate_budgetary_impact(baseline, reform)
print(f"Total budgetary impact: ${budget.total / 1e9:,.1f}B "
f"(federal ${budget.federal / 1e9:,.1f}B, state ${budget.sta
阅读完整来源 ↗