Registry / data / policyengine-us

policyengine-us

JSON →
library1.729.0pypypiunverified

PolicyEngine US is an open-source Python library that provides a comprehensive microsimulation model of the United States tax and benefit system. Built upon the PolicyEngine Core framework (a fork of OpenFisca), it accurately models federal individual income taxes, major federal benefit programs, and state income taxes for all 50 states and D.C. The library enables researchers and policymakers to estimate household-level tax liabilities and benefit eligibility, and to simulate the distributional impacts and budgetary effects of proposed policy reforms. It is actively maintained with continuous updates driven by changes in tax and benefit legislation.

pip install policyengine-us
INSTALL
IMPORT
SIG · POLICYENGINE-US
P
policyengine-us
datapythonv1.729.0
Install
35.1s avg
Import
40793ms
Disk
690MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.729.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
build_error
glibc
py 3.103.920 runs
installs and imports cleanly · install 35.1s · import 40.793s · 679MB
690MB installed
● package 690MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

system
from policyengine_us import system
Person
from policyengine_core.entities import Person
Household
from policyengine_core.entities import Household
Simulation
from policyengine_core.simulation import Simulation
from openfisca_us.simulation import Simulation
The library was renamed from openfisca-us to policyengine-us in November 2022. Core components also moved to policyengine_core.

This quickstart demonstrates how to define a simple household, retrieve the current US tax-benefit system, run a simulation to calculate a person's net income, and then apply a basic policy reform (Universal Basic Income) to see its impact.

from policyengine_us import system from policyengine_core.entities import Person, Household from policyengine_core.simulation import Simulation # Define a simple household # A person named 'alice' who is 40 years old and has wage income alice = Person(age=40, wages=50000, employment_status='EMPLOYED') # A household with Alice household = Household(members=[alice]) # Get the current US tax-benefit system # By default, uses the latest available policy year (e.g., 2025 as of recent updates) sim_system = system.get_system() # Create a simulation for the household simulation = Simulation(household=household, system=sim_system) # Calculate a variable, e.g., Alice's net income in 2025 alice_net_income = simulation.get_person_variable(person_id=alice.id, variable_name='net_income', period='2025') print(f"Alice's net income in 2025: ${alice_net_income:,.2f}") # Example of applying a simple reform (e.g., a universal basic income) reform_code = { 'universal_basic_income': [ { 'period': '2025', 'value': 12000, 'description': 'A universal basic income of $12,000 per year for all adults.' } ] } # Apply the reform to the system reformed_system = system.get_system(reform=reform_code) # Run simulation with the reformed system reformed_simulation = Simulation(household=household, system=reformed_system) alice_net_income_reformed = reformed_simulation.get_person_variable( person_id=alice.id, variable_name='net_income', period='2025' ) print(f"Alice's net income in 2025 with UBI reform: ${alice_net_income_reformed:,.2f}")
policyengine --version
Debug
Known issues
breakingThe library was renamed from `openfisca-us` to `policyengine-us` in November 2022. This included changes to package names and core import paths.
fix
Update all import statements from `openfisca_us` or `openfisca_core` to `policyengine_us` and `policyengine_core` respectively.
affects: < 1.0 (before Nov 2022)
gotchaPolicyEngine US relies on complex underlying data, which can have caveats. For example, population impact analyses using the Current Population Survey (CPS) may have truncated high incomes or underestimated benefits. Policy may also be applied to older data years (e.g., 2022 policy on 2020 data).
fix
Always review the data source and its limitations described in the PolicyEngine documentation. Understand that microsimulation models are approximations and consult official sources for definitive figures.
affects: All versions
gotchaKnown issues exist with state-specific tax calculations and non-conformity to federal changes (e.g., for Maine, DC, South Carolina). This can lead to discrepancies compared to other tax simulators like TAXSIM35.
fix
For highly precise state-level analysis, cross-verify results with other sources or consult PolicyEngine's GitHub issues for known limitations and ongoing fixes.
affects: All versions
gotchaWhen developing with `policyengine-us-data` (often used for generating microdata), a dependency on `torch` for certain machine learning features can cause unexpected test failures or installation issues if not properly handled in the environment.
fix
If encountering issues related to `policyengine-us-data` or `torch`, ensure `torch` is correctly installed, or consider using pre-generated datasets if extensive data manipulation is not required. Review `policyengine-us-data`'s specific installation instructions if directly developing with it.
affects: Versions requiring `policyengine-us-data` for L0 penalty features (specific versions not fully specified but noted as a breaking change in issue #6303)
gotchaPolicyEngine's REST API (used if you integrate with their external service) requires client ID/secret for authentication tokens, which expire monthly. This can lead to 'Authorization failed' errors if not regularly refreshed.
fix
Implement a token refresh mechanism in your application to obtain a new authentication token before the current one expires.
affects: All versions interacting with the PolicyEngine REST API
Upgrade
Version history
1.729.0latest on PyPI
Audit
Dependencies
policyengine-corerequiredCore microsimulation framework.
policyengine-us-dataoptionalProvides microdata for simulations; can introduce complex dependencies like `torch` for specific features.
Agent activity
16 hits · last 30 days
node
14
Amazon
1
Resources
policyengine-us — pip install policyengine-us · libregistry