{"id":29989812,"url":"https://github.com/policyengine/policyengine.py","last_synced_at":"2026-03-01T07:34:27.043Z","repository":{"id":231946542,"uuid":"782739565","full_name":"PolicyEngine/policyengine.py","owner":"PolicyEngine","description":"PolicyEngine's main user-facing Python package, incorporating country packages and integrating data visualization and analytics.","archived":false,"fork":false,"pushed_at":"2025-07-22T19:51:01.000Z","size":4669,"stargazers_count":5,"open_issues_count":31,"forks_count":8,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-07-29T22:12:55.464Z","etag":null,"topics":["model","python","tax-benefit"],"latest_commit_sha":null,"homepage":"https://policyengine.github.io/policyengine.py/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PolicyEngine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2024-04-05T23:18:31.000Z","updated_at":"2025-07-17T10:28:01.000Z","dependencies_parsed_at":null,"dependency_job_id":"27046b40-c7b4-4715-968a-87e858ac3784","html_url":"https://github.com/PolicyEngine/policyengine.py","commit_stats":null,"previous_names":["policyengine/policyengine.py"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/PolicyEngine/policyengine.py","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolicyEngine%2Fpolicyengine.py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolicyEngine%2Fpolicyengine.py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolicyEngine%2Fpolicyengine.py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolicyEngine%2Fpolicyengine.py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PolicyEngine","download_url":"https://codeload.github.com/PolicyEngine/policyengine.py/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolicyEngine%2Fpolicyengine.py/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268802450,"owners_count":24309657,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-04T02:00:09.867Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["model","python","tax-benefit"],"created_at":"2025-08-04T23:26:59.407Z","updated_at":"2026-03-01T07:34:27.036Z","avatar_url":"https://github.com/PolicyEngine.png","language":"Python","readme":"# PolicyEngine.py\n\nA Python package for tax-benefit microsimulation analysis. Run policy simulations, analyse distributional impacts, and visualise results across the UK and US.\n\n## Quick start\n\n```python\nfrom policyengine.core import Simulation\nfrom policyengine.tax_benefit_models.uk import PolicyEngineUKDataset, uk_latest\nfrom policyengine.outputs.aggregate import Aggregate, AggregateType\n\n# Load representative microdata\ndataset = PolicyEngineUKDataset(\n    name=\"FRS 2023-24\",\n    filepath=\"./data/frs_2023_24_year_2026.h5\",\n    year=2026,\n)\n\n# Run simulation\nsimulation = Simulation(\n    dataset=dataset,\n    tax_benefit_model_version=uk_latest,\n)\nsimulation.run()\n\n# Calculate total universal credit spending\nagg = Aggregate(\n    simulation=simulation,\n    variable=\"universal_credit\",\n    aggregate_type=AggregateType.SUM,\n    entity=\"benunit\",\n)\nagg.run()\nprint(f\"Total UC spending: £{agg.result / 1e9:.1f}bn\")\n```\n\n## Documentation\n\n**Core concepts:**\n- [Core concepts](docs/core-concepts.md): Architecture, datasets, simulations, outputs\n- [UK tax-benefit model](docs/country-models-uk.md): Entities, parameters, examples\n- [US tax-benefit model](docs/country-models-us.md): Entities, parameters, examples\n\n**Examples:**\n- `examples/income_distribution_us.py`: Analyse benefit distribution by decile\n- `examples/employment_income_variation_uk.py`: Model employment income phase-outs\n- `examples/policy_change_uk.py`: Analyse policy reform impacts\n\n## Installation\n\n```bash\npip install policyengine\n```\n\n## Features\n\n- **Multi-country support**: UK and US tax-benefit systems\n- **Representative microdata**: Load FRS, CPS, or create custom scenarios\n- **Policy reforms**: Parametric reforms with date-bound parameter values\n- **Distributional analysis**: Aggregate statistics by income decile, demographics\n- **Entity mapping**: Automatic mapping between person, household, tax unit levels\n- **Visualisation**: PolicyEngine-branded charts with Plotly\n\n## Key concepts\n\n### Datasets\n\nDatasets contain microdata at entity level (person, household, tax unit). Load representative data or create custom scenarios:\n\n```python\nfrom policyengine.tax_benefit_models.uk import PolicyEngineUKDataset\n\ndataset = PolicyEngineUKDataset(\n    name=\"Representative data\",\n    filepath=\"./data/frs_2023_24_year_2026.h5\",\n    year=2026,\n)\ndataset.load()\n```\n\n### Simulations\n\nSimulations apply tax-benefit models to datasets:\n\n```python\nfrom policyengine.core import Simulation\nfrom policyengine.tax_benefit_models.uk import uk_latest\n\nsimulation = Simulation(\n    dataset=dataset,\n    tax_benefit_model_version=uk_latest,\n)\nsimulation.run()\n\n# Access calculated variables\noutput = simulation.output_dataset.data\nprint(output.household[[\"household_net_income\", \"household_benefits\"]])\n```\n\n### Outputs\n\nExtract insights with aggregate statistics:\n\n```python\nfrom policyengine.outputs.aggregate import Aggregate, AggregateType\n\n# Mean income in top decile\nagg = Aggregate(\n    simulation=simulation,\n    variable=\"household_net_income\",\n    aggregate_type=AggregateType.MEAN,\n    filter_variable=\"household_net_income\",\n    quantile=10,\n    quantile_eq=10,\n)\nagg.run()\nprint(f\"Top decile mean income: £{agg.result:,.0f}\")\n```\n\n### Policy reforms\n\nApply parametric reforms:\n\n```python\nfrom policyengine.core import Policy, Parameter, ParameterValue\nimport datetime\n\nparameter = Parameter(\n    name=\"gov.hmrc.income_tax.allowances.personal_allowance.amount\",\n    tax_benefit_model_version=uk_latest,\n    data_type=float,\n)\n\npolicy = Policy(\n    name=\"Increase personal allowance\",\n    parameter_values=[\n        ParameterValue(\n            parameter=parameter,\n            start_date=datetime.date(2026, 1, 1),\n            end_date=datetime.date(2026, 12, 31),\n            value=15000,\n        )\n    ],\n)\n\n# Run reform simulation\nreform_sim = Simulation(\n    dataset=dataset,\n    tax_benefit_model_version=uk_latest,\n    policy=policy,\n)\nreform_sim.run()\n```\n\n## Country models\n\n### UK\n\nThree entity levels:\n- **Person**: Individual with income and demographics\n- **Benunit**: Benefit unit (single person or couple with children)\n- **Household**: Residence unit\n\nKey benefits: Universal Credit, Child Benefit, Pension Credit\nKey taxes: Income tax, National Insurance\n\n### US\n\nSix entity levels:\n- **Person**: Individual\n- **Tax unit**: Federal tax filing unit\n- **SPM unit**: Supplemental Poverty Measure unit\n- **Family**: Census family definition\n- **Marital unit**: Married couple or single person\n- **Household**: Residence unit\n\nKey benefits: SNAP, TANF, EITC, CTC, SSI, Social Security\nKey taxes: Federal income tax, payroll tax\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.\n\n## License\n\nAGPL-3.0\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolicyengine%2Fpolicyengine.py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpolicyengine%2Fpolicyengine.py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolicyengine%2Fpolicyengine.py/lists"}