Policyengine Us

PolicyEngine-US

IMPORTANT: Always use the current year (2026) in calculations, not 2024 or 2025.

PolicyEngine-US models the US federal and state tax and benefit system.

For Users

What is PolicyEngine-US?

PolicyEngine-US is the "calculator" for US taxes and benefits. When you use policyengine.org/us, PolicyEngine-US runs behind the scenes.

What it models:

Federal taxes:

• Income tax (with standard/itemized deductions)
• Payroll tax (Social Security, Medicare)
• Capital gains tax

Federal benefits:

• Earned Income Tax Credit (EITC)
• Child Tax Credit (CTC)
• SNAP (food stamps)
• WIC, ACA premium tax credits
• Social Security, SSI, TANF

State programs (varies by state):

• State income tax (all 50 states + DC)
• State EITC, CTC
• State-specific benefits

See full list: https://policyengine.org/us/parameters

Understanding Variables

Income variables:

• employment_income - W-2 wages
• self_employment_income - 1099 income
• qualified_dividend_income - Dividends
• capital_gains - Capital gains

Tax variables:

• income_tax - Federal income tax
• state_income_tax - State income tax
• payroll_tax - FICA taxes

Benefit variables:

• eitc - Earned Income Tax Credit
• ctc - Child Tax Credit
• snap - SNAP benefits

Summary variables:

• household_net_income - Income after taxes and benefits
• household_tax - Total taxes
• household_benefits - Total benefits

For Analysts

Installation

pip install policyengine

Two Modes of Analysis

1. Household Calculations - Single household, quick answers
2. Population Simulations - Microsimulation, policy analysis at scale

1. Household Calculations

Use calculate_household_impact() with USHouseholdInput for quick calculations.

Basic Pattern

from policyengine.tax_benefit_models.us import (
    USHouseholdInput,
    calculate_household_impact,
)

household = USHouseholdInput(
    people=[
        {"age": 35, "employment_income": 50_000, "is_tax_unit_head": True},
    ],
    household={"state_code_str": "CA"},
    year=2026,
)
result = calculate_household_impact(household)

print(f"Income tax: ${result.tax_unit[0]['income_tax']:,.0f}")
print(f"Net income: ${result.household['household_net_income']:,.0f}")

US Entity Structure (6 entities)

The US has more entities than the UK due to different program structures:

• person - Individual people
• marital_unit - Married couples
• family - Family unit
• spm_unit - SPM unit (for SNAP, TANF, poverty measures)
• tax_unit - Tax filing unit (for income tax, EITC, CTC)
• household - Physical household

Single Filer

household = USHouseholdInput(
    people=[
        {"age": 30, "employment_income": 60_000, "is_tax_unit_head": True},
    ],
    household={"state_code_str": "CA"},
    year=2026,
)
result = calculate_household_impact(household)

Married Couple with Children

household = USHouseholdInput(
    people=[
        {"age": 35, "employment_income": 80_000, "is_tax_unit_head": True},
        {"age": 33, "employment_income": 40_000, "is_tax_unit_spouse": True},
        {"age": 8, "is_tax_unit_dependent": True},
        {"age": 5, "is_tax_unit_dependent": True},
    ],
    tax_unit={"filing_status": "JOINT"},
    household={"state_code_str": "NY"},
    year=2026,
)
result = calculate_household_impact(household)

print(f"EITC: ${result.tax_unit[0]['eitc']:,.0f}")
print(f"CTC: ${result.tax_unit[0]['ctc']:,.0f}")
print(f"SNAP: ${result.spm_unit[0]['snap']:,.0f}")

Accessing Results

# Person-level
employment_income = result.person[0]['employment_income']

# Tax unit level (income tax, credits)
income_tax = result.tax_unit[0]['income_tax']
eitc = result.tax_unit[0]['eitc']
ctc = result.tax_unit[0]['ctc']

# SPM unit level (means-tested benefits)
snap = result.spm_unit[0]['snap']
tanf = result.spm_unit[0]['tanf']

# Household level
net_income = result.household['household_net_income']

2. Population Simulations

Use Simulation with datasets for population-level analysis.

Loading Data

from policyengine.tax_benefit_models.us import (
    us_latest,
    ensure_datasets,
)

datasets = ensure_datasets(
    data_folder="./data",
    years=[2026],
)
dataset = datasets["enhanced_cps_2024_2026"]

Running Simulations

from policyengine.core import Simulation

simulation = Simulation(
    dataset=dataset,
    tax_benefit_model_version=us_latest,
)
simulation.ensure()

output = simulation.output_dataset.data
total_eitc = output.tax_unit['eitc'].sum()
total_snap = output.spm_unit['snap'].sum()

Policy Reforms

Parametric Reforms

from policyengine.core import Policy, ParameterValue
from datetime import datetime

param = us_latest.get_parameter("gov.irs.credits.ctc.amount.base_amount")

policy = Policy(
    name="CTC $5000",
    parameter_values=[
        ParameterValue(
            parameter=param,
            value=5000,
            start_date=datetime(2026, 1, 1),
        )
    ],
)

reform_sim = Simulation(
    dataset=dataset,
    tax_benefit_model_version=us_latest,
    policy=policy,
)
reform_sim.ensure()

Simulation Modifier Reforms

def expand_eitc(sim):
    """Expand EITC phase-out threshold."""
    sim.tax_benefit_system.parameters.get_child(
        "gov.irs.credits.eitc.phase_out.start"
    ).update(period="year:2026:10", value=25000)
    sim.tax_benefit_system.reset_parameter_caches()

policy = Policy(
    name="Expand EITC",
    simulation_modifier=expand_eitc,
)

Parameter Lookup

For quick parameter lookups:

from policyengine_us import CountryTaxBenefitSystem

params = CountryTaxBenefitSystem().parameters

# CTC amount
ctc = params.gov.irs.credits.ctc.amount.base_amount("2026-01-01")

# SNAP max (use .children["N"] for indexed params)
snap_max = params.gov.usda.snap.income.max_allotment.children["4"]("2026-01-01")

# State TANF
dc_tanf = params.gov.states.dc.dhs.tanf.standard_payment.amount.children["3"]("2026-01-01")

Common Pitfalls

1. Don't Strip Weights

# WRONG
mean = output.tax_unit['eitc'].values.mean()

# CORRECT
mean = output.tax_unit['eitc'].mean()

2. Tax Unit Roles Required

# People need tax unit roles
{"age": 35, "is_tax_unit_head": True}
{"age": 33, "is_tax_unit_spouse": True}
{"age": 8, "is_tax_unit_dependent": True}

3. Filing Status for Couples

tax_unit={"filing_status": "JOINT"}  # or "SEPARATE", "HEAD_OF_HOUSEHOLD"

State-Specific Variables

State variables use {state_code}_{program} naming:

• ca_tanf, ny_tanf, dc_tanf - State TANF
• ca_eitc, ny_eitc - State EITC
• state_income_tax - Aggregate state tax

from policyengine_us import CountryTaxBenefitSystem
system = CountryTaxBenefitSystem()

# Find state variables
ca_vars = [v for v in system.variables if v.startswith("ca_")]

Additional Resources

• Documentation: https://policyengine.org/us/docs
• Variable Explorer: https://policyengine.org/us/variables
• Parameter Explorer: https://policyengine.org/us/parameters