| name | policyengine-user-guide |
| description | Using PolicyEngine web apps to analyze tax and benefit policy impacts - for users of policyengine.org.
Triggers: "how to use PolicyEngine", "household calculator", "policy reform on website", "policyengine.org walkthrough", "web app 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:
- Your household - Calculate your taxes and benefits
- Policy - Design custom reforms and see impacts
- 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
- Navigate to gov.irs.credits.ctc.amount.base_amount
- Change from $2,000 to $5,000
- 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®ion=enhanced_us&timePeriod=2025
Parameters in URL:
reform=12345 - Your custom reform IDregion=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?
- Go to household calculator
- Enter your information
- Select "Reform" and choose the policy
- Compare baseline vs reform results
Use Case 2: How Much Would Policy X Cost?
- Go to policy page
- Create or select the reform
- View "Budgetary impact" section
- See total cost and breakdown
Use Case 3: Would Policy X Reduce Poverty?
- Go to policy page
- Create or select the reform
- View "Poverty impact" section
- See change in poverty rate by age group
Use Case 4: Who Benefits from Policy X?
- Go to policy page
- Create or select the reform
- View "Distributional impact" section
- See winners and losers by income decile
Use Case 5: Compare Two Policy Proposals
- Create Reform A (e.g., expand EITC)
- Note the URL or reform ID
- Create Reform B (e.g., expand CTC)
- 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:
How do I report a bug?
If you find incorrect calculations:
- Go to the household calculator
- Note your inputs and the incorrect result
- File an issue: https://github.com/PolicyEngine/policyengine-us/issues (or appropriate country repo)
- Include the household URL
If you find app bugs:
- Note what you were doing
- File an issue: https://github.com/PolicyEngine/policyengine-app/issues
Resources
Related Skills
- policyengine-python-client-skill - Using PolicyEngine programmatically
- policyengine-us-skill - Understanding US tax/benefit calculations
- policyengine-analysis-skill - Creating custom policy analyses
