Finding parameters¶

PolicyEngine US contains over 1,000 parameters representing tax rates, benefit amounts, income thresholds, and other policy values. This guide explains how to discover and understand these parameters when creating reforms.

Parameter tree structure¶

Parameters are organized hierarchically under policyengine_us/parameters/gov/. The directory path maps directly to the parameter path you use in code.

Federal agencies¶

Directory	Agency	Examples
`gov/irs/`	Internal Revenue Service	Income tax brackets, deductions, credits (CTC, EITC, CDCC)
`gov/hhs/`	Health and Human Services	Federal poverty guidelines, Medicaid, TANF, CHIP
`gov/usda/`	Dept. of Agriculture	SNAP (food stamps), school meals, WIC
`gov/ssa/`	Social Security Administration	SSI, Social Security
`gov/hud/`	Housing and Urban Development	Section 8, housing assistance
`gov/ed/`	Dept. of Education	Pell grants, student aid
`gov/dol/`	Dept. of Labor	Unemployment insurance
`gov/fcc/`	Federal Communications Commission	Lifeline, ACP
`gov/doe/`	Dept. of Energy	Energy assistance programs
`gov/aca/`	Affordable Care Act	Premium tax credits, marketplace

IRS parameters (federal taxes)¶

The IRS section is the most detailed, covering the federal income tax code:

gov/irs/
├── income/           # Tax brackets and rates
│   └── bracket.yaml  # Marginal rates by filing status
├── deductions/       # Above and below-the-line deductions
│   ├── standard/     # Standard deduction amounts
│   └── itemized/     # SALT, mortgage interest, charitable
├── credits/          # Tax credits
│   ├── ctc/          # Child Tax Credit
│   ├── eitc/         # Earned Income Tax Credit
│   ├── cdcc/         # Child and Dependent Care Credit
│   └── ...
├── capital_gains/    # Long-term capital gains rates
├── payroll/          # Social Security and Medicare taxes
└── ald/              # Above-the-line deductions

State parameters¶

State-specific parameters follow a consistent structure:

gov/states/{state_code}/
├── tax/
│   └── income/
│       ├── rates.yaml      # State income tax rates
│       ├── credits/        # State tax credits
│       └── deductions/     # State deductions
└── {agency}/               # State benefit programs

For example, California parameters are at gov/states/ca/, New York at gov/states/ny/.

Searching for parameters¶

Using grep to find parameters¶

Search for parameters by keyword:

# Find SALT-related parameters
grep -r "salt" policyengine_us/parameters/gov/irs/ --include="*.yaml"

# Find all EITC parameters
grep -r "eitc" policyengine_us/parameters/gov/ --include="*.yaml" -l

# Find parameters mentioning a specific dollar amount
grep -r "15_000" policyengine_us/parameters/ --include="*.yaml"

Browsing the directory structure¶

List parameters in a specific area:

# See all CTC-related parameters
ls policyengine_us/parameters/gov/irs/credits/ctc/

# See all California parameters
ls -R policyengine_us/parameters/gov/states/ca/

# Find all parameter files for a program
find policyengine_us/parameters/gov/irs/credits/eitc -name "*.yaml"

Converting paths to parameter names¶

The file path becomes the parameter path by:

Removing the policyengine_us/parameters/ prefix
Removing the .yaml extension
Replacing / with .

Example:

File: policyengine_us/parameters/gov/irs/deductions/standard/amount.yaml
Parameter: gov.irs.deductions.standard.amount

Reading YAML parameter files¶

Simple parameters¶

A basic parameter file with values over time:

description: Federal deduction from AGI if not itemizing.

SINGLE:
  2018-01-01: 12_000
  2019-01-01: 12_200
  2024-01-01: 14_600
JOINT:
  2018-01-01: 24_000
  2024-01-01: 29_200
# ... other filing statuses

metadata:
  unit: currency-USD
  period: year
  label: Standard deduction

Filing status variants¶

Many IRS parameters vary by filing status. The five statuses are:

SINGLE - Unmarried individuals
JOINT - Married filing jointly
SEPARATE - Married filing separately
HEAD_OF_HOUSEHOLD - Unmarried with dependents
SURVIVING_SPOUSE - Qualifying surviving spouse

Bracket syntax¶

Tax brackets and phase-outs use a bracket structure:

brackets:
  - threshold:
      values:
        2018-01-01: 0
    amount:
      values:
        2018-01-01: 2_000
  - threshold:
      values:
        2018-01-01: 17
    amount:
      values:
        2018-01-01: 0

This defines an amount of \(2,000 when the threshold variable is 0-16, and \)0 when 17+.

Date format¶

All dates use ISO format: YYYY-MM-DD. The value applies from that date until the next specified date.

# $12,000 from 2018-01-01 through 2018-12-31
# $12,200 from 2019-01-01 through 2019-12-31
SINGLE:
  2018-01-01: 12_000
  2019-01-01: 12_200

Metadata fields¶

Common metadata fields you’ll encounter:

Field	Description
`unit`	Value type: `currency-USD`, `/1` (percentage), `year`, etc.
`period`	Time period: `year`, `month`, `eternity`
`label`	Human-readable name
`reference`	Legal citations with title and href
`breakdown`	Categories the parameter varies by
`uprating`	Inflation adjustment parameter

Common parameter patterns¶

Federal poverty guidelines¶

HHS poverty guidelines are at gov/hhs/fpg.yaml and vary by household size and state group:

first_person:
  CONTIGUOUS_US:
    2024-01-01: 15_060
  AK:
    2024-01-01: 18_810
  HI:
    2024-01-01: 17_310
additional_person:
  CONTIGUOUS_US:
    2024-01-01: 5_380

State-specific overrides¶

Some programs have federal defaults with state-specific values:

# Federal default in gov/program/threshold.yaml
threshold:
  2024-01-01: 100

# State override in gov/states/ca/program/threshold.yaml
threshold:
  2024-01-01: 150  # California has higher threshold

Indexed parameters¶

Parameters with inflation adjustment include uprating metadata:

values:
  2024-01-01: 14_600
metadata:
  uprating:
    parameter: gov.irs.uprating
    rounding:
      type: downwards
      interval: 50

Using parameters in reforms¶

Once you find a parameter, use it in a reform:

from policyengine_us import Simulation

# Create reform modifying the standard deduction
reform = {"gov.irs.deductions.standard.amount.SINGLE": {"2024-01-01": 20_000}}

sim = Simulation(situation=household, reform=reform)