Score a sized UK local release's per-area representativeness (#1124 item G)

[juaristi22]

Adds the per-area representativeness scorecard that #1124 item G asks for, as a tool that reads any finished sized UK local run. A sized release ships S, a selection of the pool's households with refitted weights, while the dense solution D weights every pool household. Calibration checks only the rows we bind. This asks whether, inside each constituency and local authority, S still looks like D on household characteristics no target binds.

Part of #1124 (item G). The pool profile and variables come from #1163's size-experiment scorecard, unchanged, so that harness can import them from here. Planned under #1278.

What it compares

• Variables. Household size (capped at 6), tenure, the head's age band, the ONS household type and the income decile (cut at D's weighted income distribution), alone and in six joints: size × tenure, tenure × head age, size × decile, head age × decile, type × tenure and type × decile.
• Distance. The total variation distance (TVD) of S's distribution from D's, per area. Beside it sits the noise null, the TVD a draw of S's effective sample size from D would show by chance, and their ratio. A ratio near one means S is as close to D as its own size allows.

How it reads a run

uk_runtime.representativeness.read_uk_local_run(run_dir) reads:

• the problem and D (uk.full.dense/solution);
• S (uk.full.size_refit/solution), on the pool rows the size receipt names;
• the pool frame from the run's graph store.

Every artifact is checked against the run's evidence index, and the receipt's rows must be the refit solution's own households. A run without a size refit ships D itself, so it is reported as not applicable.

What it writes

tools/score_uk_local_representativeness.py --run-dir <run> --out <dir> writes two files. The tool refuses an --out inside the repository.

• representativeness_by_area.csv: per grain, area and variable. It names areas and carries their support, so it stays private.

• representativeness_summary.json: cross-area statistics only, beside the digests of the artifacts read:

  • the median and 90th-percentile TVD;
  • the median TVD-to-noise ratio;
  • the number of areas above a ratio of 2.

  Only areas where S rests on at least ten distinct source households are scored, and quantiles over fewer than ten scored areas are withheld. No area code, maximum or minimum appears (UKDS disclosure control).

Nothing in the build, its gates or the release changes. The first run is meant for the frozen pre-Budget build's run directory.

Not in this PR

• A weighted energy distance against a sampling floor (Holdout-masked builds + population-view scorecards as release gates (incl. pre/post-calibration delta) #302's second distance). That can follow if the TVD views leave a question open.
• A graph node or gate. The scorecard runs after the fact, so no pins move.

Tests

packages/microcosm-build/tests/engine_free/uk/test_uk_local_representativeness.py has 9 tests, using a synthetic pool and a synthetic finished run written by test_support/microcosm_build/uk_local_representativeness.py. They check that:

• D scored against itself gives zero distance in every area;
• a tenure shift in one area shows there and nowhere else;
• the noise null shrinks as the effective sample grows, and an empty S is not valid;
• the summary scores only areas resting on ten or more sources, withholds its quantiles below the area minimum, and carries no area code or extreme;
• the run reader returns D and S, returns nothing for a dense-only run and refuses a changed artifact;
• the tool writes both files, refuses an --out inside the repository and reports a dense-only run as not applicable.

Locally: the new test file passes, tools/ci_test_plan.py verify is ok and ruff is clean on the edited files.

🤖 Generated with Claude Code