policyengine 6.2.1__tar.gz → 6.2.3__tar.gz

{policyengine-6.2.1 → policyengine-6.2.3}/.github/workflows/draft-pdf.yml

@@ -1,5 +1,8 @@
 on:
+  # Feature branches get the pull_request run below; building the draft again
+  # on every branch push duplicated it.
   push:
+    branches: [main]
     paths:
       - paper.md
       - paper.bib
@@ -18,6 +21,7 @@ jobs:
   paper:
     runs-on: ubuntu-latest
     name: Draft PDF
+    timeout-minutes: 15
     steps:
       - uses: actions/checkout@v4
       - uses: openjournals/openjournals-draft-action@master

{policyengine-6.2.1 → policyengine-6.2.3}/.github/workflows/pr_code_changes.yaml

@@ -22,6 +22,7 @@ jobs:
   check-changelog:
     name: Check changelog fragment
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     steps:
       - uses: actions/checkout@v6
         with:
@@ -32,6 +33,7 @@ jobs:
         run: .github/check-changelog.sh
   Lint:
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     steps:
         - uses: actions/checkout@v6
         - name: Install ruff
@@ -44,6 +46,7 @@ jobs:
           run: ruff check .
   Mypy:
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     steps:
         - uses: actions/checkout@v6
         - name: Install uv
@@ -61,6 +64,7 @@ jobs:
   Python-Compat:
     name: Install + smoke-import (py${{ matrix.python-version }})
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     strategy:
       fail-fast: false
       matrix:
@@ -85,6 +89,7 @@ jobs:
     # Private manifest credentials are available only to trusted repository PRs.
     if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
+    timeout-minutes: 30
     env:
       POLICYENGINE_SKIP_COUNTRY_IMPORTS: "1"
     steps:
@@ -136,6 +141,9 @@ jobs:
         run: policyengine bundle verify --country us --country uk --packages-only --json
   Test:
     runs-on: ubuntu-latest
+    # Slowest observed 2026-10-06..08: 28 minutes. Fail a hung job instead of
+    # holding a shared org runner for the 6-hour default.
+    timeout-minutes: 60
     strategy:
       fail-fast: false
       matrix:

{policyengine-6.2.1 → policyengine-6.2.3}/.github/workflows/pr_docs_changes.yaml

@@ -19,6 +19,7 @@ jobs:
   Test:
     runs-on: ubuntu-latest
     name: Test documentation builds
+    timeout-minutes: 30
     steps:
       - name: Checkout repo
         uses: actions/checkout@v6

{policyengine-6.2.1 → policyengine-6.2.3}/.github/workflows/push.yaml

@@ -28,6 +28,7 @@ jobs:
   Lint:
     if: github.event.head_commit.message != 'Update package version'
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     steps:
       - uses: actions/checkout@v6
       - name: Install ruff
@@ -40,6 +41,8 @@ jobs:
   Test:
     if: github.event.head_commit.message != 'Update package version'
     runs-on: ubuntu-latest
+    # Slowest observed 2026-10-06..08: 26 minutes.
+    timeout-minutes: 60
     strategy:
       fail-fast: false
       matrix:

{policyengine-6.2.1 → policyengine-6.2.3}/AGENTS.md

@@ -33,3 +33,16 @@ round-trip is a documented property of the public surface.
 
 Do not cache arbitrary Python objects in public result structures. The
 `core.Simulation` output must stay serialisable.
+
+## UK country filtering
+
+Select Scotland, Wales, and Northern Ireland through the stored household
+`region` column: `SCOTLAND`, `WALES`, and `NORTHERN_IRELAND`, respectively.
+Never require a `country` column when filtering raw UK household inputs;
+`country` is derived by the UK model after loading the data. The public selector
+`country/scotland` describes the requested area, not an input column name.
+
+England must select the nine English `region` values, not `ENGLAND` and not
+the complement of the other countries. Preserve these rules in new filters,
+refactors, and tests. Read the UK country filtering section in
+`docs/engineering/skills/repository-guidance.md` before changing this behavior.

{policyengine-6.2.1 → policyengine-6.2.3}/CHANGELOG.md

@@ -1,3 +1,21 @@
+## [6.2.3] - 2026-10-09
+
+### Changed
+
+- Give every lint, test, docs and paper CI job a timeout, so a hung job frees its shared GitHub Actions runner instead of holding it for six hours.
+
+### Fixed
+
+- Filter UK country simulations using stored household regions, selecting all nine English regions for England and preserving entity relationships and weights without requiring a derived country column.
+
+
+## [6.2.2] - 2026-10-07
+
+### Changed
+
+- Use the ACS-local Populace dataset by default for US state and congressional-district simulations while retaining the sparse Populace dataset as the national default.
+
+
 ## [6.2.1] - 2026-09-30
 
 ### Changed

{policyengine-6.2.1/src/policyengine.egg-info → policyengine-6.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: policyengine
-Version: 6.2.1
+Version: 6.2.3
 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-6.2.1 → policyengine-6.2.3}/docs/bundles.md

@@ -143,14 +143,20 @@ python scripts/bundle.py certify-data \
   --country us \
   --data-producer populace \
   --manifest-uri hf://dataset/policyengine/populace-us@<release>/releases/<release>/release_manifest.json \
+  --regional-manifest-uri hf://dataset/policyengine/populace-us@<local-area-release>/releases/<local-area-release>/release_manifest.json \
   --model-version <policyengine-us-version>
 ```
 
-US state and congressional-district regions scope the certified national
-Populace dataset with row filters. If a Populace release also publishes derived
-`states/*.h5` or `districts/*.h5` area slices, the bundle certification omits
-those slices from `data_releases.us.datasets`; they are not runtime dataset
-dependencies.
+US state and congressional-district regions scope one certified ACS-local
+Populace dataset with row filters. Pass its non-default local-area release
+manifest through `--regional-manifest-uri`; certification adds the pinned H5
+artifact to `data_releases.us.datasets` and writes both regional path templates
+under `data_releases.us.region_datasets`. If a legacy release publishes derived
+`states/*.h5` or `districts/*.h5` slices, certification still omits them.
+
+`policyengine bundle install` continues to materialize only each country's
+certified national `default_dataset`. Regional runtimes materialize the
+additional certified dataset when the selected region declares it.
 
 Use `python scripts/bundle.py generate` to regenerate derived bundle metadata,
 and `python scripts/bundle.py generate --include-tros` when TRACE TRO sidecars

policyengine-6.2.3/docs/engineering/runbooks/build-m-us-populace-certification.md

@@ -0,0 +1,129 @@
+# US Populace certification runbook
+
+Use this runbook to certify a new national US Populace release together with
+the shared ACS-local release used for state and congressional-district
+simulations. Read the [data certification](../skills/data-certification.md)
+skill first for validation semantics.
+
+This historical filename is retained so existing links remain valid; the
+procedure itself is release-independent.
+
+## When to use
+
+Both release manifests have been published to `policyengine/populace-us`, and
+the model version used by the national release is known. The national release
+will remain the default dataset; the local-area release will remain
+non-default and be selected only for supported regional runs.
+
+## Prerequisites
+
+- A clean worktree branched from current `origin/main`.
+- Network access: certification fetches the release manifest and PyPI wheel
+  metadata and runs reachability `HEAD` checks against Hugging Face.
+- `HUGGING_FACE_TOKEN` (or `HF_TOKEN`) exported — required to regenerate the
+  UK TRO in the `--include-tros` step and to run the UK data-release fetch in
+  the test suite. The US populace repo is public.
+
+## Step 1 — identify the releases
+
+Set values from the two published release manifests rather than copying an
+older certification:
+
+```
+NATIONAL_RELEASE_ID = populace-us-2024-<national-build>-<sha>-<timestamp>Z
+LOCAL_AREA_RELEASE_ID = populace-us-2024-<local-build>-<sha>-<timestamp>Z
+MODEL_VERSION = <policyengine-us version declared by the national release>
+```
+
+The local-area manifest must declare `dataset_role: non_default_local_area`,
+`is_default: false`, no default datasets, and exactly one pinned H5 microdata
+artifact.
+
+## Step 2 — certify both releases
+
+```bash
+python scripts/bundle.py certify-data \
+  --country us \
+  --data-producer populace \
+  --model-version "$MODEL_VERSION" \
+  --manifest-uri "hf://dataset/policyengine/populace-us@$NATIONAL_RELEASE_ID/releases/$NATIONAL_RELEASE_ID/release_manifest.json" \
+  --regional-manifest-uri "hf://dataset/policyengine/populace-us@$LOCAL_AREA_RELEASE_ID/releases/$LOCAL_AREA_RELEASE_ID/release_manifest.json"
+```
+
+This one command:
+
+- rewrites `data_releases.us` in `src/policyengine/data/bundle/manifest.json`
+  from the national release manifest (default dataset, per-artifact
+  repo/revision/sha256 pins, certified artifact, certification block);
+- runs `generate(check=False)`, which re-normalizes `manifest.json` and
+  updates `pyproject.toml` **only if the model pins moved**;
+- writes the changelog fragment
+  `changelog.d/certify-us-$NATIONAL_RELEASE_ID.changed.md`.
+
+## Step 3 — regenerate TRACE sidecars
+
+The certify step does not touch TRACE sidecars. Regenerate them so they record
+the new bundle-manifest SHA-256:
+
+```bash
+HUGGING_FACE_TOKEN="$HUGGING_FACE_TOKEN" python scripts/bundle.py generate --include-tros
+```
+
+Both country sidecars contain the bundle-manifest hash, so both may change when
+the bundle changes. If UK cannot be reached, the run writes a *limited* UK
+sidecar; do not commit that degraded output.
+
+## Step 4 — update pinned expectations
+
+Update tests that intentionally pin the outgoing national release, local-area
+release, model version, or artifact hashes. Derive every replacement from the
+new manifests; do not copy identifiers from this runbook.
+
+If the model version changed, refresh the household snapshots with:
+
+```bash
+PE_UPDATE_SNAPSHOTS=1 pytest tests/test_household_calculator_snapshot.py
+```
+
+## Step 5 — certify and verify the local-area release
+
+The certification command passes the immutable ACS-local release manifest with
+`--regional-manifest-uri`. Confirm all of the following:
+
+- `default_dataset` remains the national Populace dataset;
+- the local-area artifact appears in `data_releases.us.datasets` with its
+  repository type, immutable revision, and SHA-256;
+- `region_datasets.national` selects the national artifact;
+- `region_datasets.state` and `region_datasets.congressional_district` select
+  the shared local-area artifact;
+- no derived `states/*.h5` or `districts/*.h5` artifacts are runtime inputs.
+
+```bash
+pytest tests/test_certify_data_release.py \
+  tests/test_release_manifests.py \
+  tests/test_us_regions.py \
+  -q
+```
+
+## Step 6 — check, format, lint, test
+
+```bash
+python scripts/bundle.py check          # must exit 0
+make format
+make lint
+make test                               # needs HUGGING_FACE_TOKEN for UK
+```
+
+## Step 7 — inspect and commit the generated changes
+
+The expected diff normally includes the bundle manifest, TRACE sidecars, one
+Towncrier fragment, and pinned test expectations. Include package pins and
+snapshots only when the certified model version changed. Investigate any other
+generated difference before committing it.
+
+## Step 8 — open the PR
+
+Follow [github-prs](../skills/github-prs.md): open/find the issue, put
+`Fixes #ISSUE` first, push to the canonical repo, and open a **draft** PR. The
+certify step already wrote the changelog fragment, so the changelog check
+passes.

{policyengine-6.2.1 → policyengine-6.2.3}/docs/engineering/skills/data-certification.md

@@ -31,21 +31,30 @@ For US Populace certification, certify the Populace release manifest directly:
 ```bash
 python scripts/bundle.py certify-data --country us --data-producer populace \
   --manifest-uri "hf://dataset/policyengine/populace-us@<tag>/releases/<tag>/release_manifest.json" \
+  --regional-manifest-uri "hf://dataset/policyengine/populace-us@<local-area-tag>/releases/<local-area-tag>/release_manifest.json" \
   --model-version "<policyengine-us-version>"
 ```
 
-US state and congressional-district regions are row filters over the certified
-national Populace dataset. Certification writes:
+US state and congressional-district regions are row filters over one shared,
+certified ACS-local Populace dataset. Its release manifest must declare
+`dataset_role: non_default_local_area`, `is_default: false`, no default
+datasets, and exactly one pinned H5 microdata artifact. Certification writes:
 
 ```json
 "region_datasets": {
-  "national": {"path_template": "populace_us_2024.h5"}
+  "national": {"path_template": "populace_us_2024.h5"},
+  "state": {"path_template": "populace_us_2024_acs_local.h5"},
+  "congressional_district": {"path_template": "populace_us_2024_acs_local.h5"}
 }
 ```
 
+The ACS-local artifact is a second entry in `data_releases.us.datasets`; it is
+not a dataset overlay and it never replaces the national `default_dataset`.
+
 If the Populace release publishes derived `states/*.h5` or `districts/*.h5`
 files for compatibility checks, certification omits them from the runtime
-bundle. The national H5 is the canonical `.py` dataset.
+bundle. The country-wide default and ACS-local dataset are each single shared
+files; region registries select one and then filter its rows.
 
 The script fetches and validates the manifest (every artifact must carry a
 revision pin; the certified dataset must be reachable), writes the canonical
@@ -74,8 +83,9 @@ A certification PR should normally change only:
 Hard failures (certification refuses): missing national default dataset,
 default dataset absent from artifacts, any artifact without a revision pin,
 unreachable certified dataset, missing required supplemental release files
-(for example Populace-US `us_source_coverage.json`), missing or malformed US
-state overlay artifacts when `--regional-manifest-uri` is used, unknown country.
+(for example Populace-US `us_source_coverage.json`), a malformed shared
+local-area release or malformed legacy per-state artifacts when
+`--regional-manifest-uri` is used, unknown country.
 
 Certification gate: the model version must either exactly match the
 build-time model (`compatibility_basis: built_with_model_package`) or be
@@ -92,8 +102,9 @@ publisher-claim basis above.
 
 Concrete, fill-in-the-id runbooks that replay a specific certification live
 under `docs/engineering/runbooks/`. See
-`runbooks/build-m-us-populace-certification.md` for the next US Populace
-`sparse-rmloss100` default.
+`runbooks/build-m-us-populace-certification.md` for the reusable US national
+and local-area certification procedure. The historical filename is retained
+so existing links remain valid.
 
 ## Legacy paths
 

{policyengine-6.2.1 → policyengine-6.2.3}/docs/engineering/skills/repository-guidance.md

@@ -52,6 +52,35 @@ representative-data runs unless the change specifically needs that coverage.
 When a test needs country package data, make the dependency explicit and skip
 cleanly if credentials or local artifacts are unavailable.
 
+## UK country filtering
+
+Raw UK household data stores `region`. The UK model derives `country` from
+that input during calculation. Filtering precedes calculation, so agents and
+developers must use `region` for country selection even though the registry's
+public identifiers start with `country/`.
+
+| Public selector | Required input filter |
+| --- | --- |
+| `country/scotland` | `region == "SCOTLAND"` |
+| `country/wales` | `region == "WALES"` |
+| `country/northern_ireland` | `region == "NORTHERN_IRELAND"` |
+| `country/england` | `region` is one of the nine English values below |
+
+The English values are `NORTH_EAST`, `NORTH_WEST`, `YORKSHIRE`, `EAST_MIDLANDS`,
+`WEST_MIDLANDS`, `EAST_OF_ENGLAND`, `LONDON`, `SOUTH_EAST`, and `SOUTH_WEST`.
+There is no stored `ENGLAND` region value. Use explicit membership so unknown
+or missing regions do not become English households.
+
+Keep all four country entries as `RowFilterStrategy` so the simulation API can
+combine them with `RegionGroupStrategy`. Do not add a dataset `country` column
+or run a preliminary model calculation to work around an incorrect filter.
+Preserve household membership, related people/benefit units, and weights.
+
+Regression tests must exercise Scotland, Wales, Northern Ireland, and England
+against household inputs with `region` and **no `country` column**, including
+the string and byte representations accepted by the dataset loader. See
+`tests/test_uk_regions.py` and the public explanation in `docs/regions.md`.
+
 ## Anti-Patterns
 
 - Do not bypass the wrapper layer without a clear reason.

{policyengine-6.2.1 → policyengine-6.2.3}/docs/microsim.md

@@ -134,15 +134,16 @@ pe.us.load_datasets()  # or pe.uk.load_datasets()
 
 ### US local-area dataset
 
-Alongside the certified national default, the bundle registers a **non-default**
-US dataset for finer geographic work: `populace_us_2024_acs_local`. It is a
+Alongside the certified national default, the bundle registers a US dataset for
+finer geographic work: `populace_us_2024_acs_local`. It is a
 Populace US 2024 build of roughly **1.6 million households** on an **ACS 2024
 multispine**, with each household **PUMA-assigned** to a 119th-Congress
 congressional district, county, and state, and calibrated to **state
 administrative totals and state and congressional-district population**. Its
-release gate summary records **four reviewed limitations**, so read that gate
-summary before relying on it. It ships in its own immutable release and is never
-selected implicitly — you load it by name.
+release validation summary records **four reviewed limitations**, so read that
+summary before relying on it. It ships in its own immutable release. State and
+congressional-district region simulations select it through the bundle's
+`region_datasets` metadata; direct microsimulations can still load it by name.
 
 Two-line load:
 

{policyengine-6.2.1 → policyengine-6.2.3}/docs/regions.md

@@ -23,9 +23,9 @@ ca_snap = Aggregate(
 ca_snap.run()
 ```
 
-Each state is a region in the US registry. State regions scope the certified
-national Populace dataset by `state_fips`; they do not require separate state
-H5 files:
+Each state is a region in the US registry. State regions load the ACS-local
+Populace dataset declared by `region.dataset_path`, then scope its rows by
+`state_fips`. They do not require separate state H5 files:
 
 ```python
 states = pe.us.model.region_registry.get_by_type("state")
@@ -33,8 +33,9 @@ for region in states:
     print(region.code, region.label, region.scoping_strategy)
 ```
 
-For state-specific simulations, pass `scoping_strategy=region.scoping_strategy`
-with the certified national dataset.
+For state-specific simulations, use both `region.dataset_path` and
+`region.scoping_strategy`. The regional simulation API performs both steps from
+the registry entry.
 
 ## US congressional districts
 
@@ -49,7 +50,41 @@ for row in impacts.district_results:
     print(row["district_geoid"], row["avg_change"], row["winner_percentage"])
 ```
 
-`district_geoid` is the SSDD integer (state FIPS × 100 + district number; at-large districts use `00`). Congressional district regions scope the certified national Populace dataset by `congressional_district_geoid`.
+`district_geoid` is the SSDD integer (state FIPS × 100 + district number;
+at-large districts use `00`). Congressional district regions load the same
+ACS-local file and scope its rows by `congressional_district_geoid`.
+
+## UK countries
+
+UK country simulations filter the national dataset's stored household `region`
+column. The UK model derives `country` from `region`; the input dataset does not
+need a separate `country` column.
+
+| Country selector | Stored household input selection |
+| --- | --- |
+| `country/scotland` | `region == "SCOTLAND"` |
+| `country/wales` | `region == "WALES"` |
+| `country/northern_ireland` | `region == "NORTHERN_IRELAND"` |
+
+The `country/` prefix identifies a public geographic selector; it does not name
+a dataset column. Always filter these countries through `region` before running
+the simulation.
+
+Each country uses `RowFilterStrategy`. England matches a list of nine ITL1 regions:
+`NORTH_EAST`, `NORTH_WEST`, `YORKSHIRE`, `EAST_MIDLANDS`, `WEST_MIDLANDS`,
+`EAST_OF_ENGLAND`, `LONDON`, `SOUTH_EAST`, and `SOUTH_WEST`. Scotland, Wales and
+Northern Ireland each match their corresponding stored value: `SCOTLAND`,
+`WALES`, or `NORTHERN_IRELAND`. Unknown regions are excluded
+from all four countries. These filters preserve the selected households'
+people, benefit units and weights.
+
+```python
+scotland = pe.uk.model.get_region("country/scotland")
+england = pe.uk.model.get_region("country/england")
+```
+
+Pass the registry entry's `scoping_strategy` to `Simulation` when using a
+national UK dataset.
 
 ## UK parliamentary constituencies
 

{policyengine-6.2.1 → policyengine-6.2.3}/docs/release-bundles.md

@@ -201,31 +201,32 @@ US Populace certification uses the Populace release manifest directly:
 ```bash
 python scripts/bundle.py certify-data --country us --data-producer populace \
   --manifest-uri "hf://dataset/policyengine/populace-us@<tag>/releases/<tag>/release_manifest.json" \
+  --regional-manifest-uri "hf://dataset/policyengine/populace-us@<local-area-tag>/releases/<local-area-tag>/release_manifest.json" \
   --model-version "<policyengine-us-version>"
 ```
 
 That produces one US bundle manifest entry containing the Populace national
-default dataset. State and congressional-district regions are runtime row
-filters over that national dataset, so derived `states/*.h5` or
-`districts/*.h5` files are not vendored into `data_releases.us.datasets`.
+default dataset and the certified ACS-local regional dataset. State and
+congressional-district simulations use the latter with runtime row filters, so
+derived `states/*.h5` or `districts/*.h5` files are not vendored into
+`data_releases.us.datasets`.
 
 ### Non-default dataset overlays
 
 `certify_data_release` rewrites `data_releases.{country}` wholesale from the
-certified release manifest, so that block only ever holds datasets from the
-certified release. A staged artifact published in its own release — one that is
-deliberately not the certified default — is registered instead under the
+certified release manifest or manifests. A staged artifact that is not part of
+that certification and is deliberately not a default is registered under the
 sibling `dataset_overlays.{country}` map:
 
 ```json
 "dataset_overlays": {
-  "us": {
-    "populace_us_2024_acs_local": {
+  "uk": {
+    "populace_uk_2023": {
       "data_package_name": "populace-data",
-      "path": "populace_us_2024_acs_local.h5",
-      "repo_id": "policyengine/populace-us",
+      "path": "populace_uk_2023.h5",
+      "repo_id": "policyengine/populace-uk-private",
       "repo_type": "dataset",
-      "revision": "populace-us-2024-buildo-acs-local-...",
+      "revision": "populace-uk-2023-...",
       "sha256": "..."
     }
   }
@@ -237,8 +238,15 @@ sibling `dataset_overlays.{country}` map:
 their own pinned, sha-verified revision. Overlays are strictly additive: an
 overlay may not shadow the certified default or any certified dataset, so
 default resolution is untouched. Because certification only rewrites
-`data_releases`, overlays survive re-certification without any manual
-re-add step.
+`data_releases`, overlays survive re-certification without any manual re-add
+step.
+
+Datasets used automatically for a region type are not overlays. They are
+certified into `data_releases.{country}.datasets`, and
+`data_releases.{country}.region_datasets` maps each region type to its artifact
+path. The national `default_dataset` remains unchanged. Ordinary bundle
+installation downloads only that national default; a regional runtime is
+responsible for materializing the additional certified dataset.
 
 Cross-package overlays must declare `data_package_name` and `repo_type`
 explicitly. Ordinary artifacts inherit these values from the country release's

{policyengine-6.2.1 → policyengine-6.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "policyengine"
-version = "6.2.1"
+version = "6.2.3"
 description = "A package to conduct policy analysis using PolicyEngine tax-benefit models."
 readme = "README.md"
 authors = [

{policyengine-6.2.1 → policyengine-6.2.3}/scripts/bundle.py

@@ -202,11 +202,11 @@ def _parser() -> argparse.ArgumentParser:
     )
     certify.add_argument(
         "--regional-artifact-prefix",
-        help="Regional artifact prefix to import. Defaults to states/.",
+        help="Legacy per-state artifact prefix to import. Defaults to states/.",
     )
     certify.add_argument(
         "--regional-path-template",
-        help="Region dataset path template to certify.",
+        help="Legacy per-state dataset path template to certify.",
     )
     certify.add_argument(
         "--no-generate",

{policyengine-6.2.1 → policyengine-6.2.3}/scripts/certify_data_release.py

@@ -60,12 +60,12 @@ def main(argv=None) -> int:
     parser.add_argument(
         "--regional-artifact-prefix",
         default="states/",
-        help="Regional artifact path prefix to import. Defaults to states/.",
+        help="Legacy per-state artifact path prefix to import. Defaults to states/.",
     )
     parser.add_argument(
         "--regional-path-template",
         default="states/{state_code}.h5",
-        help="Region dataset path template to certify into the bundle manifest.",
+        help="Legacy per-state dataset path template to certify.",
     )
     parser.add_argument(
         "--model-version",

{policyengine-6.2.1 → policyengine-6.2.3}/src/policyengine/core/region.py

@@ -1,10 +1,10 @@
 """Region definitions for geographic simulations.
 
 This module provides the Region and RegionRegistry classes for defining
-geographic regions that a tax-benefit model supports. Regions can have:
-1. A dedicated dataset, usually for the national default.
-2. A scoping strategy that derives the region from a parent dataset
-   (row filter or weight replacement).
+geographic regions that a tax-benefit model supports. Regions can select an
+input dataset, apply a scoping strategy to a selected dataset, or do both. For
+example, US states and congressional districts select the shared ACS-local
+dataset and then filter its rows.
 """
 
 from typing import Literal, Optional, Union
@@ -22,10 +22,8 @@ RegionType = Union[USRegionType, UKRegionType]
 class Region(BaseModel):
     """Geographic region for tax-benefit simulations.
 
-    Regions can either have:
-    1. A dedicated dataset (``dataset_path`` is set).
-    2. A scoping strategy that derives the region from a parent dataset
-       (``scoping_strategy`` is set).
+    ``dataset_path`` selects the input dataset. ``scoping_strategy`` optionally
+    scopes that dataset to the requested geography. A region may declare both.
 
     The unique identifier is the code field, which uses a prefixed format:
     - National: "us", "uk"
@@ -56,7 +54,7 @@ class Region(BaseModel):
     # Dataset configuration
     dataset_path: Optional[str] = Field(
         default=None,
-        description="URI to a dedicated dataset when the region has one.",
+        description="URI to the input dataset selected before regional scoping.",
     )
 
     # Scoping strategy for regions that derive from a parent dataset
@@ -173,11 +171,11 @@ class RegionRegistry(BaseModel):
         return [r for r in self.regions if r.parent_code == parent_code]
 
     def get_dataset_regions(self) -> list[Region]:
-        """Get all regions that have a dedicated dataset on disk."""
+        """Get all regions that select an input dataset."""
         return [r for r in self.regions if r.dataset_path is not None]
 
     def get_filter_regions(self) -> list[Region]:
-        """Get all regions that derive from a parent dataset via a scoping strategy."""
+        """Get all regions that apply a scoping strategy to their input dataset."""
         return [r for r in self.regions if r.scoping_strategy is not None]
 
     def __len__(self) -> int: