policyengine 4.2.0__tar.gz → 4.3.0__tar.gz

{policyengine-4.2.0 → policyengine-4.3.0}/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [4.3.0] - 2026-04-20
+
+### Added
+
+- Added `policyengine.provenance.refresh_release_bundle`. Given a country and optional new model/data versions, the helper fetches the updated PyPI wheel metadata + HF dataset sha256, rewrites `data/release_manifests/{country}.json` and the matching extra pin in `pyproject.toml`, and (optionally) regenerates the bundle's TRACE TRO sidecar. A thin `scripts/refresh_release_bundle.py` wrapper exposes the library function as a CLI for release engineers. Unit-tested offline via mocked PyPI/HF responses.
+
+
+## [4.2.1] - 2026-04-20
+
+### Changed
+
+- Rewrite docs content for the v4 API: separate pages per task (households, reforms, microsim, outputs, impact analysis, regions), updated code samples against real output classes and `Simulation` dict reforms.
+
+
 ## [4.2.0] - 2026-04-20
 
 ### Added

{policyengine-4.2.0 → policyengine-4.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: policyengine
-Version: 4.2.0
+Version: 4.3.0
 Summary: A package to conduct policy analysis using PolicyEngine tax-benefit models.
 Author-email: PolicyEngine <hello@policyengine.org>
 License:                     GNU AFFERO GENERAL PUBLIC LICENSE

{policyengine-4.2.0 → policyengine-4.3.0}/docs/_quarto.yml

@@ -14,27 +14,38 @@ website:
     left:
       - href: index.md
         text: Overview
-      - core-concepts.md
-      - economic-impact-analysis.md
-      - country-models-us.md
-      - country-models-uk.md
+      - getting-started.md
+      - households.md
+      - reforms.md
+      - microsim.md
+      - impact-analysis.md
       - examples.md
       - dev.md
   sidebar:
     style: "floating"
     collapse-level: 2
     contents:
-      - index.md
-      - core-concepts.md
-      - economic-impact-analysis.md
-      - advanced-outputs.md
-      - regions-and-scoping.md
-      - country-models-uk.md
-      - country-models-us.md
-      - examples.md
-      - visualisation.md
-      - release-bundles.md
-      - dev.md
+      - section: "Get started"
+        contents:
+          - index.md
+          - getting-started.md
+      - section: "Calculate"
+        contents:
+          - households.md
+          - reforms.md
+          - microsim.md
+      - section: "Analyse"
+        contents:
+          - impact-analysis.md
+          - outputs.md
+          - regions.md
+          - visualisation.md
+      - section: "Reference"
+        contents:
+          - countries.md
+          - release-bundles.md
+          - examples.md
+          - dev.md
 
 format:
   html:

policyengine-4.3.0/docs/countries.md

@@ -0,0 +1,83 @@
+---
+title: "Country models"
+---
+
+The `policyengine` package is country-agnostic; country-specific rules live in separate packages (`policyengine-us`, `policyengine-uk`). This page captures the differences that matter to users.
+
+## Entities
+
+| US | UK |
+|---|---|
+| `person` | `person` |
+| `family` | — |
+| `marital_unit` | — |
+| `tax_unit` | `benunit` |
+| `spm_unit` | — |
+| `household` | `household` |
+
+The UK `benunit` is the closest analog to the US `tax_unit` for means-testing — a single adult or married couple plus dependent children.
+
+## Default income variable
+
+Net-income calculations use country-specific defaults:
+
+| | Variable |
+|---|---|
+| US | `spm_unit_net_income` |
+| UK | `hbai_household_net_income` |
+
+Override in any output with `income_variable=`.
+
+## Default dataset
+
+| | Dataset |
+|---|---|
+| US | Enhanced CPS 2024 (`enhanced_cps_2024.h5`) |
+| UK | Enhanced FRS 2023/24 (`enhanced_frs_2023_24.h5`) |
+
+## State / regional breakdown
+
+US: `state_code` and `congressional_district` on every household.
+
+UK: constituency code and local authority code on every household where available.
+
+## Poverty
+
+US: SPM (Supplemental Poverty Measure) and deep SPM (below half the threshold). Tracked measures are listed in `US_POVERTY_VARIABLES`.
+
+UK: AHC (After Housing Costs) and BHC (Before Housing Costs), both relative (60 % of median) and absolute.
+
+## Reform targeting
+
+Parameter paths mirror the country's rule-making structure:
+
+- US: `gov.irs.*`, `gov.states.<st>.*`, `gov.usda.*`, `gov.hhs.*`
+- UK: `gov.hmrc.*`, `gov.dwp.*`, `gov.obr.*`
+
+See [Reforms](reforms.md) for how to express changes in either tree.
+
+## Switching countries
+
+Most analysis patterns are identical — swap `pe.us` for `pe.uk`:
+
+```python
+# US
+pe.us.calculate_household(
+    people=[{"age": 35, "employment_income": 60_000}],
+    tax_unit={"filing_status": "SINGLE"},
+    household={"state_code": "CA"},
+    year=2026,
+)
+
+# UK
+pe.uk.calculate_household(
+    people=[{"age": 35, "employment_income": 50_000}],
+    year=2026,
+)
+```
+
+Microsim is similarly parallel: `pe.us.ensure_datasets` / `pe.uk.ensure_datasets`, `Simulation(tax_benefit_model_version=pe.us.model)` / `pe.uk.model`.
+
+## Pinned versions
+
+Each `policyengine` release pins specific `policyengine-us` and `policyengine-uk` versions. Check them via `pe.us.model.manifest` and `pe.uk.model.manifest`. If the installed country package version diverges, the model warns — see [Release bundles](release-bundles.md).

{policyengine-4.2.0 → policyengine-4.3.0}/docs/dev.md

@@ -70,7 +70,7 @@ This project uses [towncrier](https://towncrier.readthedocs.io/) for changelog m
 
 ```bash
 # Fragment types: breaking, added, changed, fixed, removed
-echo "Description of change" > changelog.d/my-change.added
+echo "Description of change" > changelog.d/my-branch.added.md
 ```
 
 On merge, the versioning workflow bumps the version, builds the changelog, and creates a GitHub Release.
@@ -84,14 +84,17 @@ For the target release-bundle architecture, see [Release bundles](release-bundle
 ```
 src/policyengine/
 ├── __init__.py            # Public surface: `pe.uk`, `pe.us`, `pe.Simulation`
+├── cli.py                 # `policyengine` entry point (e.g. TRACE TRO emission)
 ├── core/                  # Domain models (Simulation, Dataset, Policy, etc.)
 ├── tax_benefit_models/
 │   ├── common/            # MicrosimulationModelVersion base, result types, reform compiler
 │   ├── uk/                # UK model, datasets, household calculator, reform analysis
 │   └── us/                # US model, datasets, household calculator, reform analysis
 ├── outputs/               # Output templates (Aggregate, Poverty, etc.)
+├── results/               # Typed results + schema validation
 ├── provenance/            # Release manifests + TRACE TRO export
 ├── countries/             # Geographic region registries (scoping, constituencies, districts)
+├── data/                  # Bundled release manifests and schemas
 └── utils/                 # Helpers (reforms, entity mapping, plotting)
 ```
 

policyengine-4.3.0/docs/getting-started.md

@@ -0,0 +1,113 @@
+---
+title: "Getting started"
+---
+
+## Install
+
+```bash
+pip install policyengine
+```
+
+The base install contains the wrapper API. Install each country's rules alongside:
+
+```bash
+pip install policyengine[us]                # US
+pip install policyengine[uk]                # UK
+pip install policyengine[us,uk]             # both
+```
+
+Country modules (`pe.us`, `pe.uk`) are only importable if the matching country package is installed.
+
+## Compute one household
+
+```python
+import policyengine as pe
+
+result = pe.us.calculate_household(
+    people=[{"age": 35, "employment_income": 60_000}],
+    tax_unit={"filing_status": "SINGLE"},
+    household={"state_code": "CA"},
+    year=2026,
+)
+
+result.tax_unit.income_tax
+result.tax_unit.eitc
+result.household.household_net_income
+```
+
+Each `.*` lookup is a regular Python scalar. The result is a typed `HouseholdResult` with entity sections (`person[i]`, `tax_unit`, `spm_unit`, `household`) populated from every variable in the country model.
+
+## Apply a reform
+
+Reforms are parameter-path → value dicts:
+
+```python
+reformed = pe.us.calculate_household(
+    people=[{"age": 35, "employment_income": 60_000}],
+    tax_unit={"filing_status": "SINGLE"},
+    year=2026,
+    reform={"gov.irs.credits.ctc.amount.adult_dependent": 1_000},
+)
+```
+
+For values effective on specific dates, pass a nested dict:
+
+```python
+reform = {
+    "gov.irs.credits.ctc.amount.adult_dependent": {
+        "2026-01-01": 1_000,
+        "2028-01-01": 2_000,
+    },
+}
+```
+
+Scale parameters are addressed by bracket index:
+
+```python
+reform = {"gov.irs.credits.ctc.amount.base[0].amount": 3_000}
+```
+
+See [Reforms](reforms.md) for structural reforms and the `Simulation.policy=` counterpart for population analysis.
+
+## Scale up
+
+For population estimates — budget cost, distributional impact, poverty — move to a microsimulation over calibrated microdata. The reform dict carries over unchanged; only the constructor changes.
+
+```python
+from policyengine.core import Simulation
+
+datasets = pe.us.ensure_datasets(
+    datasets=["hf://policyengine/policyengine-us-data/enhanced_cps_2024.h5"],
+    years=[2026],
+)
+dataset = datasets["enhanced_cps_2024_2026"]
+
+baseline = Simulation(
+    dataset=dataset,
+    tax_benefit_model_version=pe.us.model,
+)
+reformed = Simulation(
+    dataset=dataset,
+    tax_benefit_model_version=pe.us.model,
+    policy={"gov.irs.credits.ctc.amount.adult_dependent": 1_000},
+)
+```
+
+(Note: `reform=` for household calc, `policy=` for `Simulation` — same dict shape.)
+
+## What you get back
+
+Every calculation returns a typed result with sections per entity:
+
+- **US**: `person`, `family`, `marital_unit`, `tax_unit`, `spm_unit`, `household`
+- **UK**: `person`, `benunit`, `household`
+
+Person-level lookups index the list: `result.person[0].age`. Group-entity lookups don't: `result.tax_unit.income_tax`.
+
+Unknown variable names raise with suggestions — no silent zero returns.
+
+## Next
+
+- [Households](households.md) — full reference for `calculate_household`
+- [Reforms](reforms.md) — parametric and structural reforms
+- [Microsimulation](microsim.md) — population-level analysis

policyengine-4.3.0/docs/households.md

@@ -0,0 +1,129 @@
+---
+title: "Households"
+---
+
+`pe.us.calculate_household` and `pe.uk.calculate_household` compute every variable in the country model for a single household. Same keyword arguments, different entity structures.
+
+## US
+
+```python
+result = pe.us.calculate_household(
+    people=[
+        {"age": 35, "employment_income": 40_000},
+        {"age": 33},
+        {"age": 8},
+        {"age": 5},
+    ],
+    tax_unit={"filing_status": "JOINT"},
+    household={"state_code": "TX"},
+    year=2026,
+)
+```
+
+### Entities
+
+| Argument | Purpose |
+|---|---|
+| `people` | List of person dicts. Keys are any person-level variable on the model. |
+| `tax_unit` | Tax-unit inputs (e.g. `filing_status`). |
+| `spm_unit` | SPM-unit inputs. |
+| `household` | Household inputs. `state_code` is essentially always needed. |
+| `family` | Family-level inputs. |
+| `marital_unit` | Marital-unit inputs. |
+
+All adults default to one shared tax unit and household. For separate tax units (e.g. two adult roommates), construct the `Simulation` directly and set the entity-membership arrays.
+
+## UK
+
+```python
+result = pe.uk.calculate_household(
+    people=[
+        {"age": 35, "employment_income": 50_000},
+        {"age": 33, "employment_income": 30_000},
+        {"age": 4},
+    ],
+    benunit={},
+    household={},
+    year=2026,
+)
+```
+
+| Argument | Purpose |
+|---|---|
+| `people` | Person-level inputs. |
+| `benunit` | Benefit unit (closest analog to US tax unit — single adult or couple plus their dependent children). |
+| `household` | Household-level inputs. |
+
+## Reforms
+
+Pass a `reform` dict of parameter-path to value:
+
+```python
+pe.us.calculate_household(
+    ...,
+    reform={"gov.irs.credits.ctc.amount.adult_dependent": 1_000},
+)
+```
+
+Scale parameters use bracket indexing:
+
+```python
+reform = {"gov.irs.credits.ctc.amount.base[0].amount": 3_000}
+```
+
+Time-varying reforms use a nested dict of `YYYY-MM-DD → value`:
+
+```python
+reform = {
+    "gov.irs.credits.ctc.amount.adult_dependent": {
+        "2026-01-01": 1_000,
+        "2028-01-01": 2_000,
+    },
+}
+```
+
+Structural reforms (new variables, formula swaps) require the `Simulation` path — see [Reforms](reforms.md).
+
+## Year
+
+```python
+pe.us.calculate_household(..., year=2026)
+```
+
+The year determines which parameter values apply. For multi-year analysis, call the function once per year rather than building a custom reform.
+
+## Extra variables
+
+The result exposes every variable in the model by default. To surface variables that aren't in the default catalog explicitly:
+
+```python
+result = pe.us.calculate_household(
+    ...,
+    extra_variables=["medicaid_income_level", "spm_unit_spm_threshold"],
+)
+```
+
+## Accessing the result
+
+```python
+result.person[0].income_tax                  # first person
+result.person[2].age                         # third person
+result.tax_unit.income_tax                   # single tax unit
+result.household.household_net_income        # single household
+```
+
+The result is a Pydantic model — `.model_dump()` gives you a dict, individual sections are regular attribute lookups.
+
+## Errors
+
+Unknown variables raise with the closest match:
+
+```
+ValueError: Unknown variable 'income_ax'. Did you mean 'income_tax'?
+```
+
+Unknown parameters in reforms raise similarly. Misplaced inputs (a person-level variable under `tax_unit=...`) raise with entity hints. The catalog is enumerated at construction time — typos fail fast.
+
+## When not to use this
+
+Loops over many households are much slower than a single `Simulation` call. For population analysis, see [Microsimulation](microsim.md) — the reform dict carries over identically.

policyengine-4.3.0/docs/impact-analysis.md

@@ -0,0 +1,110 @@
+---
+title: "Impact analysis"
+---
+
+`economic_impact_analysis` runs a baseline and a reform simulation through a bundled set of outputs — decile impacts, program statistics, poverty, and inequality — and returns a typed `PolicyReformAnalysis`.
+
+## Usage
+
+```python
+import policyengine as pe
+from policyengine.core import Simulation
+
+datasets = pe.us.ensure_datasets(
+    datasets=["hf://policyengine/policyengine-us-data/enhanced_cps_2024.h5"],
+    years=[2026],
+)
+dataset = datasets["enhanced_cps_2024_2026"]
+
+baseline = Simulation(dataset=dataset, tax_benefit_model_version=pe.us.model)
+reformed = Simulation(
+    dataset=dataset,
+    tax_benefit_model_version=pe.us.model,
+    policy={"gov.irs.credits.ctc.amount.base[0].amount": 3_000},
+)
+
+analysis = pe.us.economic_impact_analysis(baseline, reformed)
+```
+
+The UK equivalent is `pe.uk.economic_impact_analysis`. Both call `Simulation.ensure()` internally — run/cached simulations are reused, fresh ones are computed and cached.
+
+## What it returns
+
+A `PolicyReformAnalysis` with:
+
+| Attribute | Type | Content |
+|---|---|---|
+| `decile_impacts` | `OutputCollection[DecileImpact]` | Mean baseline / reform / change and winner-loser counts per decile |
+| `program_statistics` | `OutputCollection[ProgramStatistics]` | Totals, counts, winners/losers per program |
+| `baseline_poverty` | `OutputCollection[Poverty]` | Baseline rates by measure and demographic group |
+| `reform_poverty` | `OutputCollection[Poverty]` | Reform rates, same schema as baseline |
+| `baseline_inequality` | `Inequality` | Gini plus top / bottom income shares (baseline) |
+| `reform_inequality` | `Inequality` | Same, under the reform |
+
+`OutputCollection` exposes `.outputs` (typed list) and `.dataframe` (flat DataFrame).
+
+```python
+for prog in analysis.program_statistics.outputs:
+    print(prog.program_name, prog.change)
+
+for d in analysis.decile_impacts.outputs:
+    print(d.decile, d.absolute_change, d.relative_change)
+
+analysis.reform_inequality.gini - analysis.baseline_inequality.gini
+```
+
+## When to call it
+
+- Producing a reform brief covering multiple metrics
+- Standardising reporting across reforms where each run should cover the same bundle
+
+## When not to
+
+- If you only need one number (a budget cost, a single poverty rate), `ChangeAggregate` / `Aggregate` / `Poverty` avoids running ~30+ aggregations.
+- If you're sweeping a parameter, cache the baseline and build a new reform simulation per iteration:
+
+```python
+baseline = Simulation(dataset=dataset, tax_benefit_model_version=pe.us.model)
+for amount in [0, 1_000, 2_000, 3_000]:
+    reformed = Simulation(
+        dataset=dataset,
+        tax_benefit_model_version=pe.us.model,
+        policy={"gov.irs.credits.ctc.amount.base[0].amount": amount},
+    )
+    analysis = pe.us.economic_impact_analysis(baseline, reformed)
+```
+
+## Composing manually
+
+`economic_impact_analysis` is a thin wrapper over the convenience functions in `policyengine.outputs`. Replicate it if you need a different bundle or can skip sections:
+
+```python
+from policyengine.outputs import (
+    ChangeAggregate, ChangeAggregateType,
+    calculate_decile_impacts,
+    calculate_us_poverty_rates,
+    calculate_us_inequality,
+)
+
+budget = ChangeAggregate(
+    baseline_simulation=baseline,
+    reform_simulation=reformed,
+    variable="household_net_income",
+    aggregate_type=ChangeAggregateType.SUM,
+)
+budget.run()
+
+deciles = calculate_decile_impacts(baseline_simulation=baseline, reform_simulation=reformed)
+
+baseline_poverty = calculate_us_poverty_rates(simulation=baseline)
+reform_poverty = calculate_us_poverty_rates(simulation=reformed)
+
+baseline_ineq = calculate_us_inequality(simulation=baseline)
+reform_ineq = calculate_us_inequality(simulation=reformed)
+```
+
+## Next
+
+- [Outputs](outputs.md) — individual output classes and their options
+- [Regions](regions.md) — state, constituency, and district breakdowns
+- [Examples](examples.md) — runnable scripts using this helper

policyengine-4.3.0/docs/index.md

@@ -0,0 +1,46 @@
+---
+title: "policyengine"
+---
+
+`policyengine` is the Python wrapper for PolicyEngine's tax-benefit microsimulation models. One package for both single-household calculations and population-scale microsimulation, US and UK.
+
+## Install
+
+```bash
+pip install policyengine[us]                 # US rules
+pip install policyengine[uk]                 # UK rules
+pip install policyengine[us,uk]              # both
+```
+
+## Minimal example
+
+```python
+import policyengine as pe
+
+result = pe.us.calculate_household(
+    people=[{"age": 35, "employment_income": 60_000}],
+    tax_unit={"filing_status": "SINGLE"},
+    household={"state_code": "CA"},
+    year=2026,
+)
+
+result.tax_unit.income_tax
+result.household.household_net_income
+```
+
+## Where to go next
+
+| If you want to | Go to |
+|---|---|
+| Install and run your first calculation | [Getting started](getting-started.md) |
+| Compute taxes and benefits for one family | [Households](households.md) |
+| Express a policy change | [Reforms](reforms.md) |
+| Produce population estimates (budget cost, poverty) | [Microsimulation](microsim.md) |
+| See the full catalog of typed outputs | [Outputs](outputs.md) |
+| Run the canonical baseline-vs-reform bundle | [Impact analysis](impact-analysis.md) |
+| Break results down by state, constituency, district | [Regions](regions.md) |
+| Understand US vs UK differences | [Countries](countries.md) |
+| Build publication-ready charts | [Visualisation](visualisation.md) |
+| Pin a reproducible model-plus-data version | [Release bundles](release-bundles.md) |
+| See a full worked script | [Examples](examples.md) |
+| Develop against the source | [Development](dev.md) |