UK local-area exports: add the constituency_code_oa, la_code_oa and region_code_oa columns that policyengine.py and the simulation API read, and record the area-code frames in the release manifest #1114

Why

policyengine.py finds UK constituencies and local authorities through two household columns, constituency_code_oa and la_code_oa:

• its constituency and local-authority regions filter on them (countries/uk/regions.py);
• its constituency and local-authority impact outputs group on them (outputs/constituency_impact.py, outputs/local_authority_impact.py);
• it copies them, with oa_code, lsoa_code, msoa_code and region_code_oa, into every UK output dataset (UK_HOUSEHOLD_PASSTHROUGH_COLUMNS).

The simulation API reads the same pair for geographic reports (UK_GEOGRAPHIC_DATASET_VARIABLES in policyengine-sim-api's stage12_runtime/output_planning.py). These are the names the incumbent enhanced FRS carries; 1.56.16 has all six.

Our full-build exports carry the ladder names instead: the ladder columns (UK_GEOGRAPHY_LADDER_COLUMNS) leave through graph_terminal._tables, with none of the _oa names. The last staged local candidate (staged/uk-local-candidate-f100-s42-20260919T154920Z-1d33cff6, 55,361 households) has oa_code, lsoa_code, msoa_code, local_authority_code, ward_code, constituency_code, region_code and itl1_code to itl3_code. On a Microcosm file, every constituency or local-authority run in policyengine.py therefore raises Variable 'constituency_code_oa' not found in household data. Renaming on the consumer side would break the enhanced FRS and the API; writing the aliases here keeps every consumer working.

The codes themselves already line up with policyengine.py:

• Constituencies: the July 2024 Westminster frame, all 650 including Northern Ireland's 18. The enhanced FRS covers the 632 in Great Britain, all shared.
• Local authorities: the April 2023 LAD frame, 361 codes (LAD23_COUNT).
  • policyengine.py's list (local_authorities_2021.csv, on the same frame despite its name) has 360 of them. It lacks Ards and North Down (N09000011), which UK: certify a Microcosm national dataset as the UK default, with separate national and local-area datasets and a corrected local-authority list policyengine.py#553 adds.
  • The enhanced FRS is on the pre-2023 frame: 363 codes in Great Britain, 17 of them for districts abolished in 2023.

Proposed change

1. Write three alias columns at the single-year export boundary (graph_terminal._tables, where the nation-native aliases are already dropped), on every UK release that carries area codes (the dense and local lines):

   • constituency_code_oa = constituency_code
   • la_code_oa = local_authority_code
   • region_code_oa = region_code

   Keep the ladder columns: our gates, diagnostics and target compilation read them. The _oa suffix is the consumers' name only. Northern Irish households are placed through data zones rather than output areas, and the codes are the same either way. UK_ALLOWED_EXTRA_EXPORT_COLUMNS in terminal_gates.py already admits all three names.

2. Record the frames in the release manifest's metadata, for example "area_code_frames": {"constituency": "westminster_2024", "local_authority": "lad_2023_04"}. policyengine.py can then check that its area lists match before it wires a local release in. The next frame change to watch is the 1 April 2025 Barnsley/Sheffield recode, which the LAD lookups we pin do not carry yet.

3. Add a release-contract test: a UK release with area codes carries the three aliases, each equal to its ladder column and non-empty for every household.

The national line needs no change. It carries region only, and policyengine.py will scope nations and regions from region (PolicyEngine/policyengine.py#553).

Done when

• The next staged dense or local candidate carries the three aliases.
• policyengine.py's constituency and local-authority row filters find households in all 650 constituencies and all 361 local authorities of that candidate.

Related:

• UK: certify a Microcosm national dataset as the UK default, with separate national and local-area datasets and a corrected local-authority list policyengine.py#553: certifying a Microcosm national dataset in policyengine.py, with separate national and local-area datasets.
• Use ACS-local data for US regional simulations policyengine.py#552: regional dataset defaults.

🤖 Generated with Claude Code