policyengine 6.3.3__tar.gz → 6.4.0__tar.gz

{policyengine-6.3.3 → policyengine-6.4.0}/CHANGELOG.md

@@ -1,3 +1,27 @@
+## [6.4.0] - 2026-10-14
+
+### Added
+
+- Added `policyengine.disclosure`, a self-contained layer for statistical disclosure control and uncertainty on area-level outputs, and `compute_uk_geography_disclosure` for UK regions, constituencies and local authorities. Each published number rests on at least 10 distinct survey households (clones counted once through `source_household_id`), carries a 90% bootstrap interval and is rounded to the order of its standard error. Rows are `reported`, `approximate` or `withheld`. A release check reports numbers a reader could recover by subtraction across geography levels, a package and its components, and earlier publications. Keyed noise per survey household is available behind `DisclosureSettings(noise=True)`. `validate_public` and `python -m policyengine.disclosure validate` check the format of published files. UK runs now keep `source_household_id` and `region` on the household output when the dataset provides them.
+
+### Changed
+
+- Deprecated `compute_uk_constituency_impacts`, `compute_uk_local_authority_impacts` and their `ConstituencyImpact` and `LocalAuthorityImpact` classes. Their output is not disclosure-controlled; use `compute_uk_geography_disclosure` instead. They now log a warning through the `policyengine` logger and emit a `DeprecationWarning`, and otherwise behave as before.
+
+
+## [6.3.4] - 2026-10-13
+
+### Changed
+
+- `Poverty.rate` is now `None`, not `0.0`, when nobody in the group is measured (its weighted population with a poverty status is zero), for every source. `headcount` and `total_population` are unchanged, and the poverty DataFrame helpers report the rate as missing. Callers that format or subtract rates must handle `None`.
+- US state and congressional-district regions temporarily filter the certified national dataset again, as in 6.2.1, because the ACS-local release lacks source-backed SPM independence and canonical SPM refused every state-region run (PolicyEngine/microcosm#1263).
+
+### Fixed
+
+- Measure SPM poverty on legacy certified US sources that predate SPM measurement-scope declarations, such as the ACS-local Build O release. Following Census's ACS household-population method, ACS group-quarters units are outside the SPM measurement: their SPM results are missing instead of stopping the run with `SPM_COMPOSITION_REQUIRED`, and poverty rates count measured people only. Ordinary tax and benefit results are unchanged.
+- Supply the certified SPM independence role from the national release for the ASEC and PUF records of legacy certified US sources, so independent-teen SPM units are measured instead of stopping SPM calculations.
+
+
 ## [6.3.3] - 2026-10-13
 
 ### Changed

{policyengine-6.3.3/src/policyengine.egg-info → policyengine-6.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: policyengine
-Version: 6.3.3
+Version: 6.4.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-6.3.3 → policyengine-6.4.0}/docs/_quarto.yml

@@ -39,6 +39,7 @@ website:
           - impact-analysis.md
           - outputs.md
           - regions.md
+          - disclosure.md
           - visualisation.md
       - section: "Methodology"
         contents:

{policyengine-6.3.3 → policyengine-6.4.0}/docs/bundles.md

@@ -147,7 +147,9 @@ python scripts/bundle.py certify-data \
   --model-version <policyengine-us-version>
 ```
 
-US state and congressional-district regions scope one certified ACS-local
+**Temporarily**, state and congressional-district regions filter the certified national dataset (`populace_us_2024`), as in policyengine 6.2.1. The certified ACS-local release has no source-backed SPM independence, so canonical SPM refuses thousands of its SPM units (PolicyEngine/microcosm#1263, PolicyEngine/policyengine-sim-api#747). They move back to the ACS-local dataset with a release whose SPM units all have a classified adult.
+
+When they use it, 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

policyengine-6.4.0/docs/disclosure.md

@@ -0,0 +1,239 @@
+---
+title: "Disclosure control"
+---
+
+Local results from survey microdata rest on few households, and a licence
+binds every published number. `policyengine.disclosure` turns per-household
+results into area tables that follow the licence's rules and carry their
+uncertainty. Use it for every UK result below the national level that leaves
+your machine.
+
+```python
+from policyengine.outputs import compute_uk_geography_disclosure
+
+impact = compute_uk_geography_disclosure(
+    baseline_simulation=baseline,
+    reform_simulation=reform,
+    year=2026,
+    levels=("region", "constituency"),
+    reform="budget",
+)
+impact.findings  # what blocks publication, if anything
+impact.public  # the rows that may be published, or None while blocked
+```
+
+The UK datasets derive from surveys under the UK Data Service End User
+Licence. The defaults below follow its disclosure rules. You can raise them
+for a study with stricter conditions; you cannot lower them.
+
+## What a published row holds
+
+Each row is one outcome for one area, reform and year.
+
+| Column | Content |
+|---|---|
+| `level`, `area_code`, `reform`, `year`, `outcome` | The key of the row |
+| `value`, `lo`, `hi` | The rounded estimate and its 90% interval |
+| `direction` | `gain`, `loss`, `too_close_to_call` or `no_change` |
+| `tier` | `reported`, `approximate` or `withheld` |
+| `reason` | `thin_support` for an approximate row, `disclosure_control` for a withheld row |
+| `support_band` | `<10`, `10–29` or `30+` survey households, never an exact count |
+| `noise` | Whether the row carries keyed noise |
+| `estimator` | `direct`: the estimate comes from the area's own records |
+
+The outcomes are `average_change`, `relative_change`, `total_change`,
+`share_gaining`, `share_losing` and `share_no_change`. A withheld row carries
+no value, interval, direction or support band.
+
+## The rules
+
+**Count floor.** A number must rest on at least 10 distinct survey households
+that contribute to it. For a change, a household contributes when its income
+changes by more than `change_tolerance` (£1 a year, which is also the lowest
+value the setting takes). Copies and clones of one survey household count
+once, through the dataset's `source_household_id`. For a share, both sides
+must pass: the households that gain and those that do not.
+
+**Dominance.** While noise is off, a number is withheld in two cases:
+
+- one survey household carries more than half of it, by size;
+- the p% rule: a reader of the number, or one household that knows its own
+  part, could estimate some household's part to within 10%. Every household
+  is a possible target and every other household a possible reader, so the
+  rule also catches a total whose other parts cancel.
+
+These rules protect each household against any reader and against any one
+other household. They do not stop two or more households that pool what they
+know: a number that three households carry almost alone passes, as long as 10
+contribute.
+
+**Effective sample.** Weights that differ a lot make an estimate less precise
+than its household count suggests. Where the data gives one area and one
+weight per record, a low effective sample makes a row `approximate`: it keeps
+its value and interval, but the interval understates the uncertainty. Where
+the data is an area × household weight matrix, the household count passes by
+construction, so the effective sample must also be at least 10. Weights given
+as a matrix keep this rule whatever they hold: one row of a dense matrix has
+one weight per record, yet every household of the nation sits in that area.
+
+**Zero cells.** A cell with no contributing household is published as zero,
+with the interval [0, 0] and the direction `no_change`. It means that no
+surveyed household in the area changed, not that no household there does. Its
+support band counts the households it was measured on.
+
+**Settings.** The layer validates its settings again before it uses them, so
+a copy made with `model_copy(update=...)` cannot lower a floor.
+
+**Linked outcomes.** Average, relative and total change share a numerator, so
+they are published or withheld together. Gaining, losing and no change add to
+one, so the third share is published only when it is safe to derive.
+
+## Uncertainty and rounding
+
+Intervals come from a Poisson bootstrap over survey households with 1,000
+replicates. A ratio resamples its numerator and denominator together. The
+weights stay fixed, so the intervals leave out calibration uncertainty and are
+too narrow, most of all where support is thin.
+
+Values are rounded to the order of magnitude of their standard error. The
+interval is rounded outward on the same base.
+
+## The release check
+
+Published numbers constrain each other. If a region is public and all but one
+of its constituencies are public, subtraction gives the last one. The check
+looks for such remainders:
+
+- child areas against their parent area (constituencies in regions, regions in
+  the nation);
+- the components of a package against the package;
+- when two levels that do not nest are released together, an area against
+  the areas of the other level that lie wholly inside it, and against the
+  areas that meet it (their sum minus the area is what they hold outside it);
+- earlier publications, passed as `prior_public`.
+
+A remainder gets the rules of a cell. Estimates added with `publish=False`
+are a reference: the release does not emit their rows, but it treats the rows
+that pass as public elsewhere and the withheld ones as secret, and checks
+them like its own.
+
+`compute_uk_geography_disclosure` always checks constituencies and local
+authorities against their region, and regions against the nation, also when
+you publish one level only. A level given as a weight matrix needs
+`parent_of=` with the region of each area; without it the function raises,
+because a check against the nation alone nearly always passes.
+
+The check reports; it does not withhold cells by itself. A blocking finding
+names the group and suggests a cell. Withhold it, then check again. When a
+finding suggests no cell, withhold the parent (`finding.group` at
+`finding.group_level`) instead:
+
+```python
+for finding in impact.findings:
+    print(finding.code, finding.group, finding.suggested)
+
+impact.release.withhold(
+    level="constituency",
+    area_code="E14001234",
+    reform="budget",
+    year=2026,
+    outcome="average_change",
+)
+impact.refresh()  # checks again and fills impact.public once nothing blocks
+```
+
+Two findings can be accepted after review, with `acknowledge=[...]`:
+
+- `unchecked_overlap`: levels that overlap without nesting, such as
+  constituencies and local authorities, are released together. The release
+  checks each area against the areas wholly inside it and against the areas
+  that meet it. It does not check other differences between overlapping
+  areas, and on weight-matrix data it checks none.
+- `noise_reference_public`: an earlier table shows the same cells under
+  another noise setting.
+
+## Noise
+
+Noise is off by default. With `DisclosureSettings(noise=True)`, each survey
+household's change is scaled by a fixed factor between 8% and 12% away from 1,
+derived from its id and a secret key. The same household has the same factor
+in every table and every rebuild. Noise replaces the dominance rule; the count
+floor still applies. The range cannot start closer to 1 than 8%.
+
+A number that one household dominates, published with noise, gives that
+household's part to within 8 to 12%. The p% rule treats 10% as the line, so
+noise puts such a number right at that line, not safely past it. Whether the
+UK Data Service accepts noise in place of the dominance rule is a licence
+question, which is why noise stays off by default.
+
+- **Size.** The noise in a total is about a tenth of that total's sampling
+  error.
+- **Key.** Pass `noise_key=` or set `POLICYENGINE_DISCLOSURE_NOISE_KEY`. There
+  is no default key. Keep the key out of repositories and CI logs, and do not
+  change it between releases of one dataset: two noised versions of a number
+  average towards the truth.
+- **Limits.** Denominators carry no noise. The factor cancels in a ratio of
+  two numbers that the same household dominates. A remainder that subtraction
+  recovers is the noised sum of the withheld cells, so it has the protection
+  of a noised cell and no more: the count floor applies to it, and noise
+  stands in for the dominance rule as it does for a cell. An un-noised copy
+  of the same cell gives the factor away.
+
+## Validating published files
+
+`validate_public` checks the format of a table, a CSV file or a directory. It
+needs no key and no microdata, so it can run on every pull request:
+
+```bash
+python -m policyengine.disclosure validate public/data --reviewed notes.csv
+```
+
+It rejects private audit columns, unknown tiers, a value in a withheld row,
+unrounded values, a direction that does not match its interval, and files it
+does not recognise. It cannot tell whether a number rested on enough
+households; only the release that made the file can.
+
+## Private objects
+
+`audit_dir=` writes the exact values, household counts and shares behind every
+row. The directory must be outside any git repository.
+
+`AreaEstimates`, the object that `estimate_change` returns, holds the same
+exact values. With noise on it also holds the noise factor of every household
+that gains or loses, and within one dataset those factors do the same job as
+the key. Keep it in memory and treat it as you treat the key. It cannot be
+pickled or copied.
+
+## What a reader can still derive
+
+`average_change` and `relative_change` together give the area's total
+baseline income to within a few per cent (household count × average ÷
+relative). That total is a denominator: it carries no noise and is not
+checked for dominance.
+
+## Arrays without a simulation
+
+The package works on arrays and imports nothing from the rest of the library:
+
+```python
+from policyengine.disclosure import AreaWeights, Release, estimate_change
+
+seats = estimate_change(
+    level="constituency",
+    reform="budget",
+    year=2026,
+    areas=AreaWeights.from_labels(seat_codes, household_weights),
+    source_ids=source_household_ids,
+    baseline=baseline_net_income,
+    reformed=reformed_net_income,
+)
+release = Release()
+release.add(seats)
+release.check()
+public = release.to_public()
+```
+
+`AreaWeights.from_matrix(matrix, area_codes)` takes an area × household weight
+matrix instead. A dataset without `source_household_id` needs `source_ids=`
+from the caller; the layer does not guess which records share a survey
+household.

{policyengine-6.3.3 → policyengine-6.4.0}/docs/engineering/runbooks/build-m-us-populace-certification.md

@@ -2,8 +2,10 @@
 
 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.
+simulations. For now, state and district simulations use the national release
+instead; see the interim exception in Step 2. 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.
@@ -13,7 +15,8 @@ procedure itself is release-independent.
 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.
+non-default and be selected only for supported regional runs (none while the
+interim exception in Step 2 holds).
 
 ## Prerequisites
 
@@ -60,6 +63,19 @@ This one command:
 - writes the changelog fragment
   `changelog.d/certify-us-$NATIONAL_RELEASE_ID.changed.md`.
 
+**Interim exception (from policyengine 6.3.4; PolicyEngine/policyengine.py#604).**
+State and congressional-district regions filter the national dataset until an
+ACS-local release has no SPM unit without a classified adult
+(PolicyEngine/microcosm#1263). Run the command above unchanged, with
+`--regional-manifest-uri`: without it, certification drops the ACS-local
+dataset and leaves no state or district template. Then, before Step 3, set
+`region_datasets.state` and `region_datasets.congressional_district` in
+`data_releases.us` to `{"path_template": "populace_us_2024.h5"}` by hand. In
+Step 5, expect those two templates to select the national artifact, not the
+local-area one. The data-certification skill
+(`docs/engineering/skills/data-certification.md`) says what must hold before
+the exception ends.
+
 ## Step 3 — regenerate TRACE sidecars
 
 The certify step does not touch TRACE sidecars. Regenerate them so they record
@@ -87,15 +103,16 @@ 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:
+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;
+  the shared local-area artifact (the national artifact while the interim
+  exception in Step 2 holds);
 - no derived `states/*.h5` or `districts/*.h5` artifacts are runtime inputs.
 
 ```bash

policyengine-6.4.0/docs/engineering/runbooks/us-legacy-spm-sources.md

@@ -0,0 +1,122 @@
+# Legacy US SPM sources (backward compatibility)
+
+> **Backward compatibility, not a data contract.** This layer exists so that
+> certified US sources published *before* SPM declarations existed can still
+> be measured. New certified sources must carry the declarations themselves;
+> do not register them here.
+
+policyengine-us measures SPM poverty only when a source declares two things:
+
+- **Measurement scope:** which SPM units are inside the SPM measurement
+  population (`spm_unit_spm_universe_status`: `INCLUDED`/`OUTSIDE`, the
+  contract of PolicyEngine/microcosm#977).
+- **Independence role:** which 15–17-year-olds independently head their own
+  SPM unit (`is_spm_independent_minor_role`).
+
+A legacy source carries neither. Every SPM calculation on it stops with
+`SPM_COMPOSITION_REQUIRED` ("SPM unit has no classified adult").
+
+The package
+[`policyengine.tax_benefit_models.us.legacy_spm`](../../../src/policyengine/tax_benefit_models/us/legacy_spm/__init__.py)
+derives the missing declarations from evidence a legacy source does carry.
+Nobody is dropped: memberships, weights and every ordinary tax, benefit and
+income calculation are unchanged.
+
+## Registered sources
+
+Sources are keyed by certified SHA-256 in `legacy_spm/registry.py`.
+
+| Source | Scope rule | Independence list |
+| --- | --- | --- |
+| `populace_us_2024_acs_local` Build O (`769756c3…a7ec`) | `acs_household_population` | national release `source_spm_person_independence.csv` (`22b5968d…3ce5`) |
+
+### Scope rule `acs_household_population` (#597)
+
+Census's ACS SPM methodology measures the household population only.
+
+- ACS records with `TYPEHUGQ` 2 or 3 and the matching `RELSHIPP` (37 or 38) are
+  group quarters, so their SPM units are `OUTSIDE`.
+- ACS housing-unit records are `INCLUDED`.
+- Records from the `asec` and `puf_tax_detail` channels are `INCLUDED`.
+
+Age is never used. Unknown channels, missing or inconsistent evidence, and SPM
+units that mix group quarters with household people all raise.
+
+On the full Build O source, 183,206 SPM units are outside the measurement.
+
+### Independence list (#598)
+
+The source's ASEC/PUF records are the same records the certified national
+release carries with a source-backed independence role. The list is joined by
+`person_id` and `person_spm_unit_id`, and the join must be exact:
+
+- every ASEC/PUF person appears once, in the same SPM unit;
+- the list names nobody else.
+
+ACS people keep the model's own fallback (household head or spouse).
+
+On Build O, exactly 28 units change: Census-built units around an independent
+teen.
+
+## How runs get the declarations
+
+| Path | What happens |
+| --- | --- |
+| `create_datasets` / `ensure_datasets` | Year files store the declarations as ordinary input columns, with a `policyengine_legacy_spm_declarations` record. |
+| `Simulation.run()` over a raw legacy source file | The declarations are derived in memory. The file is recognised by its evidence columns and then its SHA-256, which is hashed once per process. |
+| `managed_microsimulation` | The declarations are derived from the loaded tables and set on the simulation and its branches. |
+
+`legacy_spm.model_adapter` then makes the model honour the scope:
+
+- **native:** policyengine-us defines `spm_unit_spm_universe_status`
+  (PolicyEngine/policyengine-us#9462). The declaration is just an input, and
+  nothing is overridden.
+- **override:** policyengine-us 2.2.1 cannot read it. A variable-only reform:
+  - adds the input;
+  - wraps the installed SPM chain so that outside units never reach the
+    canonical provider and every SPM outcome for them is NaN ("not measured").
+
+  Poverty indicators become floats (1.0, 0.0 or NaN). The override wraps the
+  installed formulas, with one exception: `spm_unit_income_decile` ranks
+  units, so it is recalculated over measured units with the installed method.
+  A contract test pins that method. The override refuses to run if the SPM
+  chain no longer has the verified shape.
+
+Poverty rates count measured people only. A group with nobody measured has a
+rate of `None`, not 0.
+
+## Staleness
+
+The record holds a `LegacySPMProfile`: the registry entry plus
+`ADAPTER_REVISION`. Checks are total and exact, like the year-file stamp:
+
+- `ensure_datasets` cuts a year file again, and `load_datasets` refuses it, when
+  its record is absent, unreadable, malformed, or from another profile.
+- `Simulation.load()` refuses an output saved under a different profile.
+
+Raise `ADAPTER_REVISION` whenever a change to derivation or the override means
+existing files must be made again.
+
+## When the model or data changes
+
+- **policyengine-us gains native scope (#9462).**
+  `test_the_installed_model_does_not_read_scope_natively_yet` fails. Check that
+  the native members include `INCLUDED` and `OUTSIDE`, and confirm the native
+  runs in the integration tests. Then delete the override half of
+  `model_adapter` (keep the derivation) and raise `ADAPTER_REVISION`.
+- **The SPM chain changes.** `test_the_override_covers_every_variable_that_depends_on_the_provider`,
+  `test_the_installed_chain_has_the_verified_shape` or
+  `test_the_recalculated_decile_matches_the_installed_method` fails. Re-verify
+  the override against the new chain before bumping the pin.
+- **A rebuilt source declares scope and role itself.** Point the bundle at it.
+  Keep the Build O registry entry only while anything still reads Build O,
+  then delete it.
+
+## Related
+
+- Microcosm #977: scope classification at source.
+- Microcosm #959: independence role in US builds.
+- policyengine-us #9462: native scope.
+- policyengine.py #519: nullable SPM summaries.
+- The year-file and output stamps (#590, and #593/#594 in flight). Fold this
+  record into them once those land.

{policyengine-6.3.3 → policyengine-6.4.0}/docs/engineering/skills/data-certification.md

@@ -35,8 +35,33 @@ python scripts/bundle.py certify-data --country us --data-producer populace \
   --model-version "<policyengine-us-version>"
 ```
 
-US state and congressional-district regions are row filters over one shared,
-certified ACS-local Populace dataset. Its release manifest must declare
+**Interim exception (from policyengine 6.3.4; PolicyEngine/policyengine.py#604).**
+State and congressional-district regions currently filter the certified
+national dataset, not the ACS-local one. The certified ACS-local release has
+no source-backed SPM independence, so canonical SPM refuses its SPM units that
+have no classified adult, and with them every state-region run
+(PolicyEngine/microcosm#1263, PolicyEngine/policyengine-sim-api#747). The 6.3.4
+manifest was certified with `--regional-manifest-uri`, as below, and then
+edited by hand. Until the exception ends, do the same:
+
+- still pass `--regional-manifest-uri`. Without it, certification rewrites
+  `data_releases.us` from the national manifest alone, which drops the
+  ACS-local dataset and leaves no state or district template at all;
+- then set `region_datasets.state` and `region_datasets.congressional_district`
+  to `{"path_template": "populace_us_2024.h5"}` by hand, before regenerating
+  the TRACE sidecars. `tests/test_release_manifests.py` fails if they name
+  the ACS-local file, and also if the ACS-local dataset is no longer
+  certified.
+
+Restore the ACS-local regions only with an ACS-local release in which every
+SPM unit has at least one classified adult under the pinned spm-calculator's
+rule (zero unclassified units), and after a state-region run through the
+public wrapper succeeds on it. Then remove this exception, the temporary test
+and the matching notes in `docs/regions.md` and `docs/bundles.md`.
+
+Outside that exception, 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:
 

{policyengine-6.3.3 → policyengine-6.4.0}/docs/examples.md

@@ -16,6 +16,13 @@ Applying parametric reforms, comparing baseline and reform with `ChangeAggregate
 ```{.python include="../examples/policy_change_uk.py"}
 ```
 
+## UK geography results under disclosure control
+
+Estimating results by area from per-household arrays, checking the release, withholding a cell and validating the public table. The data is synthetic.
+
+```{.python include="../examples/uk_geography_disclosure.py"}
+```
+
 ## UK income bands
 
 Calculating net income and tax by income decile using representative microdata and `Aggregate` with quantile filters.

{policyengine-6.3.3 → policyengine-6.4.0}/docs/microsim.md

@@ -87,6 +87,24 @@ before passing them to the country model. Generic adult/child counts remain
 separate. The native source enrichment is not recalibration, and inherited
 schema-5 calibration diagnostics cannot be relabeled as schema 6.
 
+**Legacy SPM sources (backward compatibility).** Some certified US sources
+predate SPM declarations, for example the ACS-local Build O release. For those
+sources, .py derives the declarations from evidence they carry, following
+Census's ACS SPM methodology, which measures the household population only:
+
+- ACS group-quarters SPM units are outside the SPM measurement. Their SPM
+  thresholds, resources and poverty indicators are missing (NaN).
+- Poverty indicators on those sources are floats: 1.0, 0.0, or NaN for "not
+  measured".
+- Poverty rates count measured people only. A group with nobody measured has
+  a rate of `None`, not 0.
+- The sources' ASEC and PUF records take the certified SPM independence role
+  from the national release.
+
+Ordinary tax, benefit and income results are unchanged. Outputs record the
+declarations they used under `legacy_spm_declarations`. See
+[the runbook](engineering/runbooks/us-legacy-spm-sources.md).
+
 The wrapper's native pandas HDF loader accepts files that store only calibrated
 `household_weight`. It maps missing person and group weight columns through
 native membership IDs in memory, retaining supplied weight columns and the

{policyengine-6.3.3 → policyengine-6.4.0}/docs/outputs.md

@@ -167,6 +167,12 @@ rate.run()
 rate.headcount, rate.total_population, rate.rate
 ```
 
+`rate.rate` is `None` when nobody in the group is measured: the group's
+weighted population with a poverty status is zero, for example a filter that
+matches no one, or a group whose members are all outside the SPM measurement
+on a legacy source. That is not a measured rate of zero, so handle `None`
+before formatting or subtracting rates.
+
 For all canonical poverty measures over one simulation:
 
 ```python
@@ -260,7 +266,28 @@ for row in impacts.district_results:
     print(row["district_geoid"], row["avg_change"], row["winner_percentage"])
 ```
 
-### UK constituencies / local authorities
+### UK regions, constituencies and local authorities
+
+`compute_uk_geography_disclosure` returns results by area under disclosure
+control: each number passes a floor on the survey households behind it and
+carries a 90% interval. Use it for anything you publish. See
+[Disclosure control](disclosure.md).
+
+```python
+from policyengine.outputs import compute_uk_geography_disclosure
+
+impact = compute_uk_geography_disclosure(
+    baseline_simulation=baseline,
+    reform_simulation=reform,
+    year=2026,
+    levels=("region", "constituency"),
+)
+impact.public.to_frame()
+```
+
+The two older functions below are deprecated. Their output is not
+disclosure-controlled, so do not publish it when the data is licensed survey
+microdata.
 
 Constituency and local-authority breakdowns group household output rows by
 dataset-provided longwise geography columns. Constituencies use

{policyengine-6.3.3 → policyengine-6.4.0}/docs/regions.md

@@ -23,9 +23,13 @@ ca_snap = Aggregate(
 ca_snap.run()
 ```
 
-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:
+Each state is a region in the US registry. State regions load the Populace
+dataset declared by `region.dataset_path`, then scope its rows by `state_fips`.
+They do not require separate state H5 files.
+
+**Temporarily**, state and congressional-district regions filter the certified national dataset (`populace_us_2024`), as in policyengine 6.2.1. The certified ACS-local release has no source-backed SPM independence, so canonical SPM refuses thousands of its SPM units (PolicyEngine/microcosm#1263, PolicyEngine/policyengine-sim-api#747). They move back to the ACS-local dataset with a release whose SPM units all have a classified adult.
+
+For example:
 
 ```python
 states = pe.us.model.region_registry.get_by_type("state")
@@ -52,7 +56,8 @@ for row in impacts.district_results:
 
 `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`.
+file as state regions (for now the national dataset; see above) and scope its rows by
+`congressional_district_geoid`.
 
 ## UK countries
 
@@ -88,6 +93,11 @@ national UK dataset.
 
 ## UK parliamentary constituencies
 
+To publish results by constituency, local authority or region, use
+`compute_uk_geography_disclosure`; see [Disclosure control](disclosure.md).
+The functions in this section and the next are deprecated: their output is
+not disclosure-controlled.
+
 Constituency-level impacts group household output rows by the longwise
 `constituency_code_oa` column carried by the dataset. If the constituency CSV is
 available locally or from the PolicyEngine UK GCS bucket, PolicyEngine uses it

{policyengine-6.3.3 → policyengine-6.4.0}/docs/release-bundles.md

@@ -207,7 +207,8 @@ python scripts/bundle.py certify-data --country us --data-producer populace \
 
 That produces one US bundle manifest entry containing the Populace national
 default dataset and the certified ACS-local regional dataset. State and
-congressional-district simulations use the latter with runtime row filters, so
+congressional-district simulations use one of them with runtime row filters (for now the
+national dataset; see [Regions](regions.md)), so
 derived `states/*.h5` or `districts/*.h5` files are not vendored into
 `data_releases.us.datasets`.