Publish a small calibrated national sample (populace_us_20k) for Colab/CI/tutorials

Request

Publish a small, calibrated national Populace US sample (e.g. populace_us_20k, ~20k households) as a first-class, registered dataset, so tutorials, Colab, and CI can run a national microsimulation without the full file.

Motivation

The full populace_us_2024 (224,026 households / 572,780 people, 1.2 GB) is too heavy for free Google Colab: a single national household_net_income run peaked at ~21 GB RSS in testing. That blocks hands-on population analysis in the IMA 2026 tutorial (and is generally awkward for CI / quick iteration).

A uniform 20k-household subsample (household integrity preserved, weights rescaled) already reproduces full-file headline aggregates to ~1–3% (net income to ~0.02%) — so a calibrated 20k artifact would be accurate enough for headline cost/poverty/decile work while being light and fast.

Requirements

1. Size: ~20k households (~50k people). Mirror the full file's HDF5 schema/keys exactly so it loads through the same path.
2. Household integrity: when a household is sampled, keep all members and their tax_unit / spm_unit / family / marital_unit rows.
3. Calibration: reweight with the existing L0 / microcalibrate machinery (the bundle already exposes populace_us_2024_calibration) to hit national targets — population by age/state, aggregate employment income / AGI / net income / federal tax, major program totals (SNAP, SSI, EITC, CTC, Social Security), SPM poverty rate.
4. Register it in the bundle manifest so pe.us.managed_microsimulation(dataset="populace_us_20k") works without allow_unmanaged.
5. Validate vs full Populace: net income, tax, benefits, SNAP/SSI/EITC/CTC, SPM poverty, deciles — document residual error per metric.

Notes

• The bundle already ships per-state datasets (states/XX) as a lighter-than-national option; this is the national small-sample complement.
• A quick uniform sample exists locally from tutorial prep for testing only (not calibrated, not for publishing).
• Surfaced during IMA World Congress 2026 PolicyEngine tutorial prep.

Start with the existing populace_us_2024_calibration bundle and the manifest registration path used by pe.us.managed_microsimulation. Trace how datasets preserve household-related rows and are loaded, then determine how the L0/microcalibrate machinery can produce the requested national sample. Done means a registered populace_us_20k loads without allow_unmanaged and documented validation compares its requested metrics with the full dataset.