[vahid-ahmadi]

Summary

Adds examples/household_targeting_uk.py, a worked replication of a published household-level targeting rule, and lists it in docs/examples.md and the README.

Published UK analyses often define eligibility with a rule that is not a PolicyEngine variable. Reproducing one as a new user, the steps that took time were not in the docs:

• aggregating a person variable to the household (highest individual income), using person_household_id;
• joining benefit units to households. sim.calculate("household_id", map_to="benunit") looks like the way to do it, but mapping from a larger entity to a smaller one shares the value among the smaller units (a household value of 1 becomes 2/3 and 1/3 for two benefit units of two and one people). That is right for amounts and wrong for ids and flags; the example joins through the person-level ids instead and says why;
• choosing between benefit receipt reported in the survey (*_reported) and modelled entitlement;
• deciles: household_income_decile ranks people by income before housing costs, while HBAI headline distributions and many publications use after housing costs. The example builds an AHC ranking explicitly;
• the equivalisation scale: household_equivalisation_bhc is the HBAI-rescaled modified OECD scale (couple = 1.0), and a threshold on the unrescaled form passes far more households;
• turning eligibility into counts, shares and per-household amounts under a fixed budget.

The case is the energy bill discount options in "Billing me softly" (August 2026). The example links https://github.com/PolicyEngine/uk-energy-reforms, which implements those options as a policyengine-uk reform with the published figures beside PolicyEngine's.

Output

Run on 6.10.1 with the bundle's Microcosm UK 2024-25, fiscal year 2024-25:

GB households: 28.1m
Highest individual income below £24,000: 38%
  share of the four lowest AHC deciles: 71%
Equivalised household income below £30,000: 35%
Passported, reported receipt: 23%
Passported, modelled entitlement: 26%
£2bn among 11.9m eligible households: £168 each
Two tiers of £220 and £85 cost £2.33bn
Couples with children passing the household test but not the individual one: 633k

The publication reports about 40%, 75%, about 25%, £175 and 490,000 for the matching figures. The example prints PolicyEngine's numbers only; it does not claim to match.

It needs the private UK data, like the other UK population examples, so it does not run in CI. ruff check and ruff format --check pass.

🤖 Generated with Claude Code