policyengine 6.2.0__tar.gz → 6.2.2__tar.gz

{policyengine-6.2.0 → policyengine-6.2.2}/.github/workflows/draft-pdf.yml

@@ -10,6 +10,10 @@ on:
       - paper.bib
       - architecture.png
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 jobs:
   paper:
     runs-on: ubuntu-latest

{policyengine-6.2.0 → policyengine-6.2.2}/.github/workflows/pr_code_changes.yaml

@@ -14,6 +14,10 @@ on:
       - src/policyengine/data/bundle/manifest.json
   workflow_dispatch:
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 jobs:
   check-changelog:
     name: Check changelog fragment
@@ -77,7 +81,7 @@ jobs:
       - name: Smoke-import core modules
         run: python -c "import policyengine; from policyengine.core import Dataset, Policy, Simulation; from policyengine.outputs import aggregate, poverty, inequality; print('import OK')"
   BundleVerification:
-    name: Verify bundle metadata
+    name: Verify release inputs and bundle packages
     # 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
@@ -93,8 +97,19 @@ jobs:
         uses: actions/setup-python@v6
         with:
           python-version: '3.13'
-      - name: Check derived bundle metadata
-        run: python scripts/bundle.py check
+      - name: Install package for TRACE verification
+        run: uv pip install -e . h5py --system
+      - name: Check reviewed release inputs
+        env:
+          HUGGING_FACE_TOKEN: ${{ secrets.HUGGING_FACE_TOKEN }}
+        run: |
+          if [[ -z "${HUGGING_FACE_TOKEN:-}" ]]; then
+            echo "::error::Full private release verification requires HUGGING_FACE_TOKEN"
+            exit 1
+          fi
+          python scripts/check_release_credentials.py
+          python scripts/bundle.py check --published-spm --include-tros --strict-tros
+          python scripts/release_lock.py
       - name: Install bundle package scaffold
         run: |
           uv pip install -e ".[models]" --system
@@ -117,17 +132,10 @@ jobs:
           PY
       - name: Check installed package consistency
         run: python -m pip check
-      # Only the reviewed registry lock is a pull-request concern. The
-      # read-only credential, published-measurement and TRACE sidecar gates
-      # are release gates: the release workflow regenerates the sidecars and
-      # publishes the wheels immediately before checking them, so they cannot
-      # be satisfied from a pull request. They run in push.yaml instead.
-      - name: Check the reviewed registry lock
-        run: python scripts/release_lock.py
       - name: Verify bundle packages
         run: policyengine bundle verify --country us --country uk --packages-only --json
   Test:
-    runs-on: macos-latest
+    runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:

{policyengine-6.2.0 → policyengine-6.2.2}/.github/workflows/pr_docs_changes.yaml

@@ -11,6 +11,10 @@ on:
       - .github/**
   workflow_dispatch:
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 jobs:
   Test:
     runs-on: ubuntu-latest

{policyengine-6.2.0 → policyengine-6.2.2}/.github/workflows/push.yaml

@@ -39,7 +39,7 @@ jobs:
 
   Test:
     if: github.event.head_commit.message != 'Update package version'
-    runs-on: macos-latest
+    runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:

{policyengine-6.2.0 → policyengine-6.2.2}/CHANGELOG.md

@@ -1,3 +1,22 @@
+## [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
+
+- Update the certified PolicyEngine bundle to PolicyEngine Core 3.32.10.
+- Run the full Python test matrices on GitHub-hosted Ubuntu machines and cancel earlier workflow runs when a pull request receives a new commit.
+
+### Fixed
+
+- Correct the US and UK TRACE composition fingerprints after the PolicyEngine Core 3.32.10 bundle update, and run the authenticated TRACE comparison on same-repository pull requests.
+
+
 ## [6.2.0] - 2026-09-29
 
 ### Added

{policyengine-6.2.0/src/policyengine.egg-info → policyengine-6.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: policyengine
-Version: 6.2.0
+Version: 6.2.2
 Summary: A package to conduct policy analysis using PolicyEngine tax-benefit models.
 Author-email: PolicyEngine <hello@policyengine.org>
 License:                     GNU AFFERO GENERAL PUBLIC LICENSE
@@ -685,15 +685,15 @@ Requires-Dist: plotly>=5.0.0; extra == "plotting"
 Provides-Extra: graph
 Requires-Dist: networkx>=3.0; extra == "graph"
 Provides-Extra: models
-Requires-Dist: policyengine-core==3.32.5; extra == "models"
+Requires-Dist: policyengine-core==3.32.10; extra == "models"
 Requires-Dist: policyengine-us==2.2.1; extra == "models"
 Requires-Dist: policyengine-uk==2.102.3; extra == "models"
 Requires-Dist: spm-calculator==1.0.0; extra == "models"
 Provides-Extra: uk
-Requires-Dist: policyengine-core==3.32.5; extra == "uk"
+Requires-Dist: policyengine-core==3.32.10; extra == "uk"
 Requires-Dist: policyengine-uk==2.102.3; extra == "uk"
 Provides-Extra: us
-Requires-Dist: policyengine-core==3.32.5; extra == "us"
+Requires-Dist: policyengine-core==3.32.10; extra == "us"
 Requires-Dist: policyengine-us==2.2.1; extra == "us"
 Requires-Dist: spm-calculator==1.0.0; extra == "us"
 Provides-Extra: dev
@@ -711,7 +711,7 @@ Requires-Dist: towncrier>=24.8.0; extra == "dev"
 Requires-Dist: mypy>=1.11.0; extra == "dev"
 Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
 Requires-Dist: hypothesis>=6.100.0; extra == "dev"
-Requires-Dist: policyengine-core==3.32.5; extra == "dev"
+Requires-Dist: policyengine-core==3.32.10; extra == "dev"
 Requires-Dist: policyengine-us==2.2.1; extra == "dev"
 Requires-Dist: policyengine-uk==2.102.3; extra == "dev"
 Requires-Dist: spm-calculator==1.0.0; extra == "dev"

{policyengine-6.2.0 → policyengine-6.2.2}/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.2/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.0 → policyengine-6.2.2}/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.0 → policyengine-6.2.2}/docs/households.md

@@ -106,7 +106,7 @@ separate benefit inputs; they do not override SPM measurement composition.
 
 These changes require the coordinated canonical country/calculator bundle, which
 the packaged production manifest now pins and certifies: `policyengine-us`
-2.2.1, `policyengine-core` 3.32.5, `spm-calculator` 1.0.0, and the US data
+2.2.1, `policyengine-core` 3.32.10, `spm-calculator` 1.0.0, and the US data
 release `populace-us-2024-spm-20260915`. Local-wheel development manifest
 fixtures remain explicitly uncertified. The measurement receipt identifies a
 calculation; it does not certify a population dataset or establish publication

{policyengine-6.2.0 → policyengine-6.2.2}/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.0 → policyengine-6.2.2}/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,9 @@ 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 parliamentary constituencies
 

{policyengine-6.2.0 → policyengine-6.2.2}/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.0 → policyengine-6.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "policyengine"
-version = "6.2.0"
+version = "6.2.2"
 description = "A package to conduct policy analysis using PolicyEngine tax-benefit models."
 readme = "README.md"
 authors = [
@@ -40,17 +40,17 @@ graph = [
     "networkx>=3.0",
 ]
 models = [
-    "policyengine-core==3.32.5",
+    "policyengine-core==3.32.10",
     "policyengine-us==2.2.1",
     "policyengine-uk==2.102.3",
     "spm-calculator==1.0.0",
 ]
 uk = [
-    "policyengine-core==3.32.5",
+    "policyengine-core==3.32.10",
     "policyengine-uk==2.102.3",
 ]
 us = [
-    "policyengine-core==3.32.5",
+    "policyengine-core==3.32.10",
     "policyengine-us==2.2.1",
     "spm-calculator==1.0.0",
 ]
@@ -69,7 +69,7 @@ dev = [
     "mypy>=1.11.0",
     "pytest-cov>=5.0.0",
     "hypothesis>=6.100.0",
-    "policyengine-core==3.32.5",
+    "policyengine-core==3.32.10",
     "policyengine-us==2.2.1",
     "policyengine-uk==2.102.3",
     "spm-calculator==1.0.0",

{policyengine-6.2.0 → policyengine-6.2.2}/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.0 → policyengine-6.2.2}/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.0 → policyengine-6.2.2}/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: