policyengine/policyengine-user-guide

PolicyEngine User Guide

This skill helps you use PolicyEngine to analyze how tax and benefit policies affect households and populations.

For Users: Getting Started

What is PolicyEngine?

PolicyEngine computes the impact of public policy on households and society. You can:

• Calculate how policies affect your household
• Analyze population-wide impacts of reforms
• Create and share custom policy proposals
• Compare different policy options

Web App: policyengine.org

Main features:

1. Your household - Calculate your taxes and benefits
2. Policy - Design custom reforms and see impacts
3. Research - Read policy analysis and blog posts

Available Countries

• United States - policyengine.org/us
• United Kingdom - policyengine.org/uk
• Canada - policyengine.org/ca (beta)

Using the Household Calculator

Step 1: Navigate to Household Page

US: https://policyengine.org/us/household UK: https://policyengine.org/uk/household

Step 2: Enter Your Information

Income:

• Employment income (W-2 wages)
• Self-employment income
• Capital gains and dividends
• Social Security, pensions, etc.

Household composition:

• Adults and dependents
• Ages
• Marital status

Location:

• State (US) or region (UK)
• NYC checkbox for New York City residents

Deductions (US):

• Charitable donations
• Mortgage interest
• State and local taxes (SALT)
• Medical expenses

Step 3: View Results

Net income - Your income after taxes and benefits

Breakdown:

• Total taxes (federal + state + local)
• Total benefits (EITC, CTC, SNAP, etc.)
• Effective tax rate
• Marginal tax rate

Charts:

• Net income by earnings
• Marginal tax rate by earnings

Creating a Policy Reform

Step 1: Navigate to Policy Page

US: https://policyengine.org/us/policy UK: https://policyengine.org/uk/policy

Step 2: Select Parameters to Change

Browse parameters by:

• Government department (IRS, SSA, etc.)
• Program (EITC, CTC, SNAP)
• Type (tax rates, benefit amounts, thresholds)

Example: Increase Child Tax Credit

1. Navigate to gov.irs.credits.ctc.amount.base_amount
2. Change from $2,000 to $5,000
3. Click "Calculate economic impact"

Step 3: View Population Impacts

Budgetary impact:

• Total cost or revenue raised
• Breakdown by program

Poverty impact:

• Change in poverty rates
• By age group (children, adults, seniors)
• Deep poverty (income < 50% of threshold)

Distributional impact:

• Average impact by income decile
• Winners and losers by decile
• Relative vs absolute changes

Inequality impact:

• Gini index change
• Top 10% and top 1% income share

Step 4: Share Your Reform

Share URL: Every reform has a unique URL you can share:

policyengine.org/us/policy?reform=12345&region=enhanced_us&timePeriod=2025

Parameters in URL:

• reform=12345 - Your custom reform ID
• region=enhanced_us - Geography (US, state, or congressional district)
• timePeriod=2025 - Year of analysis

Understanding Results

Metrics Explained

Supplemental Poverty Measure (SPM):

• Accounts for taxes, benefits, and living costs
• US Census Bureau's official alternative poverty measure
• More comprehensive than Official Poverty Measure

Gini coefficient:

• Measures income inequality (0 = perfect equality, 1 = perfect inequality)
• US Gini is typically around 0.48
• Lower values = more equal income distribution

Income deciles:

• Population divided into 10 equal groups by income
• Decile 1 = bottom 10% of earners
• Decile 10 = top 10% of earners

Winners and losers:

• Winners: Net income increases by 5% or more
• Losers: Net income decreases by 5% or more
• Neutral: Net income change less than 5%

Reading Charts

Household impact charts:

• X-axis: Usually income or earnings
• Y-axis: Net income, taxes, or benefits
• Hover to see exact values

Population impact charts:

• Bar charts: Compare across groups (deciles, states)
• Line charts: Show relationships (income vs impact)
• Waterfall charts: Show components of budgetary impact

Common Use Cases

Use Case 1: How Does Policy X Affect My Household?

1. Go to household calculator
2. Enter your information
3. Select "Reform" and choose the policy
4. Compare baseline vs reform results

Use Case 2: How Much Would Policy X Cost?

1. Go to policy page
2. Create or select the reform
3. View "Budgetary impact" section
4. See total cost and breakdown

Use Case 3: Would Policy X Reduce Poverty?

1. Go to policy page
2. Create or select the reform
3. View "Poverty impact" section
4. See change in poverty rate by age group

Use Case 4: Who Benefits from Policy X?

1. Go to policy page
2. Create or select the reform
3. View "Distributional impact" section
4. See winners and losers by income decile

Use Case 5: Compare Two Policy Proposals

1. Create Reform A (e.g., expand EITC)
2. Note the URL or reform ID
3. Create Reform B (e.g., expand CTC)
4. Compare budgetary, poverty, and distributional impacts

For Analysts: Moving Beyond the Web App

Once you understand the web app, you can:

Use the Python client:

• See policyengine-python-client-skill for programmatic access
• See policyengine-us-skill for detailed simulation patterns

Create custom analyses:

• See policyengine-analysis-skill for analysis patterns
• See microdf-skill for data analysis utilities

Access the API directly:

• See policyengine-api-skill for API documentation
• REST endpoints for integration

For Contributors: Building PolicyEngine

To contribute to PolicyEngine development:

Understanding the stack:

• See policyengine-core-skill for engine architecture
• See policyengine-us-skill for country model patterns
• See policyengine-api-skill for API development
• See policyengine-app-skill for app development

Development standards:

• See policyengine-standards-skill for code quality requirements
• See policyengine-writing-skill for documentation style

Frequently Asked Questions

How accurate is PolicyEngine?

PolicyEngine uses official tax and benefit rules from legislation and regulations. Calculations match official calculators (IRS, SSA, etc.) for individual households.

Population-level estimates use microsimulation with survey data (Current Population Survey for US, Family Resources Survey for UK).

Can I use PolicyEngine for my taxes?

PolicyEngine is for policy analysis, not tax filing. Results are estimates based on the information you provide. For filing taxes, use IRS.gov or professional tax software.

How is PolicyEngine funded?

PolicyEngine is a nonprofit funded by grants and donations. The platform is free to use.

Can I export results?

Yes! Charts can be downloaded as PNG or HTML. You can also share reform URLs with others.

What programs does PolicyEngine model?

US (federal):

• Income tax, payroll tax, capital gains tax
• EITC, CTC, ACTC
• SNAP, WIC, ACA premium tax credits
• Social Security, SSI, TANF
• State income taxes (varies by state)

UK:

• Income tax, National Insurance
• Universal Credit, Child Benefit
• State Pension, Pension Credit
• Council Tax, Council Tax Support

For complete lists, see:

• US: https://policyengine.org/us/parameters
• UK: https://policyengine.org/uk/parameters

How do I report a bug?

If you find incorrect calculations:

1. Go to the household calculator
2. Note your inputs and the incorrect result
3. File an issue: https://github.com/PolicyEngine/policyengine-us/issues (or appropriate country repo)
4. Include the household URL

If you find app bugs:

1. Note what you were doing
2. File an issue: https://github.com/PolicyEngine/policyengine-app/issues

Resources

• Website: https://policyengine.org
• Documentation: https://policyengine.org/us/docs
• Blog: https://policyengine.org/us/research
• GitHub: https://github.com/PolicyEngine
• Contact: [email protected]

Related Skills

• policyengine-python-client-skill - Using PolicyEngine programmatically
• policyengine-us-skill - Understanding US tax/benefit calculations
• policyengine-analysis-skill - Creating custom policy analyses