Presume a member 20+ years younger is the claimant's child when no roles are supplied

[MaxGhenis]

Refs #2039. Follow-up to #2040 (merged 3 October), kept separate because it changes calculator results for unflagged inputs, which is a methodology call (Max ruled d842: adopt).

What changes

is_claimant_or_partner gains one more presumption for households entered without relationships. A member at least 20 years younger than the claimant is presumed to be their child at any age, flagged or not (new parameter household.demographic.benefit_unit.presumed_child.minimum_age_gap_at_any_age = 20). It is OR'ed onto #2040's rule (now on main), which is unchanged: 16+ years younger and either under 20, or below a flagged claimant whose flag no young child explains.

Unflagged household (ages)	main	This PR
50, 25	couple	single claimant; the 25-year-old is not claimant or partner
50, 31 (19 apart)	couple	couple
50, 30 (20 apart)	couple	single claimant
60, 38, child 10	couple with child	lone parent (trade-off below)
60, 38, child 10, roles supplied	couple with child	couple with child

A member flagged is_parent still takes priority as the partner, so a flagged couple 25 years apart stays a couple. With flags, it also fixes two cases #2040 documents as limitations, provided the adult is 20+ years younger:

• a flagged lone parent (50) with an adult child (25) and a younger child (12) is now single, not a couple;
• a flagged grandparent (70) with a daughter (45) and grandchild (10) no longer has the daughter as partner.

At 16-19 years apart the limitation stays (38/20/12 is still read as a couple, YAML case).

Why 20 years

Once a dataset supplies is_claimant_or_partner (PolicyEngine/policyengine-uk-data#524 does, from the FRS adult table), the presumption no longer touches the microsimulation. It only applies to inputs without roles, so it can follow how often a large age gap means a couple. Measured on the enhanced FRS 2024-25 with the survey's own roles (couple = both in one benefit unit as claimant and partner), co-resident HBAI adults with the younger aged 20+:

Age gap	Couple share	Survey households (couple pair / other pair)
16-19	54.3%	78 / 132
20-24	13.3%	52 / 371
25-29	0.5%	12 / 553
30+	0.2%	10 / 932
16+ overall	5.4%	152 / 1,516

Shares are of weighted pairs (each pair takes its household's weight). #2040's evidence cited 61% / 12% / 0.6% / 0.2% from the released eFRS snapshot using benefit-unit membership alone; the 20-year boundary is the same either way.

Below 20 years apart, a couple is the more likely reading; from 20, a parent and adult child is. The table describes co-resident adults in the population, not calculator submissions.

Trade-off and who it reaches

An unflagged couple 20+ years apart entered without roles, whose elder is the claimant (the head, or the eldest adult when no adult head is given), is now read as a single claimant plus a non-member adult. A younger explicit head keeps the couple: the gap is measured below the claimant.

• policyengine-app-v2: Send explicit UK claimant roles and stop reading an adult dependant as the partner policyengine-app-v2#1240 (draft) makes the builder send is_claimant_or_partner for "you" and a declared partner, once the API runs a policyengine-uk release containing Replace generic child and adult flags with each programme's legal definitions #1896. With it, a declared partner keeps the couple whatever the gap. Until it lands, a declared partner 20+ years younger would be read as a non-member adult, so Add automatic function for decomposing variable outputs #1240 should land before or with this PR.
• policyengine.py uk.calculate_household, policyengine-api, household-api: pass households through. Callers that send ages only get the presumption. Supplying is_claimant_or_partner (or flagging both partners is_parent) keeps the couple. The docstring says so.

Impact (real microsimulation runs)

Seeded build of policyengine-uk-data#524's branch (enhanced FRS 2024-25 with is_claimant_or_partner from the adult table), simulated for 2025 and 2026. Latest run: main at 493f0d2 (which includes #2040) against this branch at 34c83a9. Two earlier runs, at earlier heads of both, gave the same figures. Cells under 10 survey households are suppressed; SPI-synthetic and donor copies don't count toward the 10.

Role supplied (the data this PR should ship with): base (main) vs branch identical. Every compared array is identical in 2025 and 2026 across the versions run. The arrays are: person is_claimant_or_partner, income tax and NI; benefit-unit UC, HB, Pension Credit, Child Benefit, CTC, WTC, IS, benefit cap and relation_type; household CTR, net income, HBAI net income BHC/AHC, benefits, tax and BHC/AHC poverty.

Role dropped (any enhanced FRS without the column):

• main infers the survey roles exactly for all 113,567 people.
• This branch splits 33 survey households (108 person records; 96k weighted households in 2025, 97k in 2026). All are survey couples 20+ years apart, the younger 20+, with no parent flag. It makes no other error: no partner added, and no flagged couple, couple under 20 years apart or single claimant affected.
• relation_type changes in those 33 households. UC, Pension Credit, CTR, household net income and income tax change in fewer than 10 survey households (suppressed).

Calculator-style input: each eFRS household entered as one benefit unit with no roles, flags or heads (2025). Truth is the survey claimant and partner of the eldest member's own benefit unit, because the model's claimant is the eldest adult.

Rule	Claimant and partner right (weighted households)	Wrong
main	98.13%	919 survey households (587k weighted)
this PR	98.88%	379 survey households (351k weighted)

Where the rules disagree, this PR is right in 612 survey households (382k weighted) and main in 72 (146k weighted).

Sequencing (Max ruled d842: adopt; merge on gates, ship with uk-data#524)

• policyengine-uk has no default dataset (Simulation() needs one explicitly or via POLICYENGINE_UK_DEFAULT_DATASET). policyengine.py's bundle manifest pins model and data together. On policyengine.py main (6a9c878) the UK default is enhanced_frs_2024_25 from policyengine-uk-data 1.56.16, the dataset policyengine-uk-data#524 changes.
• The bundle also offers three non-default UK overlays that carry no is_claimant_or_partner: populace_uk_2023 (policyengine/populace-uk-private), enhanced_frs_2023_24 and frs_2023_24 (policyengine-uk-data at 655dd07e). Real runs, Presume a much younger member is a flagged parent's child at any age #2040's head (c18c836) vs this branch (f43e5ec), 2025. Cells under 10 source households are suppressed; populace's ten OA clones count as one source household, and in enhanced_frs_2023_24 only households whose ids are raw FRS 2023-24 serial numbers count (the file doesn't flag its copies).
  • populace_uk_2023: roles change in 18 source households (about 25k weighted households). Benefit and income amounts move in fewer than 10 (suppressed).
  • enhanced_frs_2023_24: roles change in 18 survey households (64 households in the file, counting its unflagged synthetic and donor copies; about 13k weighted). Amounts move in fewer than 10 (suppressed).
  • These are role-less inputs like any calculator household. Max ruled d871: merge on gates and accept this. Any published number based on an overlay should be re-run before that overlay carries is_claimant_or_partner. A separate task adds the role to microcosm's populace UK build.
• A merge to main publishes policyengine-uk to PyPI on its own (versioning workflow). A standalone consumer pairing that release with an enhanced FRS older than Set default basic income threshold to £0 #524 would see the 33 couples above split. Bundles should take this release together with the data release carrying Set default basic income threshold to £0 #524 (the d833 batch).
• policyengine-app-v2#1240 adds roles when a builder household is saved; it does not backfill households saved earlier with ages only. Those keep the presumption until re-saved.

Invariants

Executed as Hypothesis properties in test_child_and_adult_definitions_properties.py, plus the exhaustive age × education × flag grid against the updated reference claimants_or_partners:

1. Any benefit unit: at most two claimants or partners, all HBAI adults (existing).
2. A flagged claimant: an unflagged member 16+ years younger is never their partner unless a young child explains the flag (Presume a much younger member is a flagged parent's child at any age #2040, unchanged).
3. Metamorphic: flagging the claimant as a parent never adds a partner (Presume a much younger member is a flagged parent's child at any age #2040, unchanged).
4. Differential (changed): on FRS-shaped units, the rule equals the rule without the any-age gap except in childless two-adult units 20+ years apart, where the younger adult is no longer the partner if the elder is the claimant. This is the intended violation of Presume a much younger member is a flagged parent's child at any age #2040's "FRS-shaped units are unchanged" property, and is why the data must supply the role.
5. New: supplied is_claimant_or_partner roles are always kept, and is_couple follows them.

Mutation check (local log; run at 0448203, 31 YAML cases and 13 properties):

• Reverting to Presume a much younger member is a flagged parent's child at any age #2040's formula fails 5 YAML cases and 5 properties.
• Setting the parameter to 21 or 19, or using a strict >, fails the 20-year YAML boundary case and the new exhaustive pair test.

Tests

• YAML (full suite: 2,006 passed locally at this head; benefit_unit_structure.yaml, 32 cases):
  • unflagged 50/25 is single;
  • the 20-year boundary (50/31 couple, 50/30 and 90/70 single);
  • a flagged partner 25 years younger stays the partner;
  • unflagged 60/38/10 is a lone parent, but a couple when roles are supplied;
  • Presume a much younger member is a flagged parent's child at any age #2040's two documented limitations at 20+ gaps are now read correctly, and a 16-19-year variant (38/20/12) keeps the limitation;
  • the under-20 boundary moves to an 18-year gap so it still tests the age limit;
  • a younger explicit head (50) with a partner 20 years older keeps the couple.
• Other fixtures: every test on main that enters a couple 20+ years apart without roles now supplies is_claimant_or_partner for the two partners, with expectations unchanged. YAML: Lifetime ISA capital (70/45), Pension Credit mixed-age (79/54), and ten 70/50 mixed-age cases (benefit cap for pension-age claimants, CTR pensioner status, HB earnings disregard). Hypothesis generators: Pension Credit reported capital, the mixed-age couple invariants, the benefit cap pension-age partner test and the CTR pensioner earnings disregard (main already supplies roles in the UC State Pension generator). Without roles the presumption splits these couples, as intended.
• Properties: valid families are now checked against the reference rule exactly, with the one intended exception stated: an unflagged couple whose head is 20+ years older. Two new tests: the exhaustive test_unflagged_adult_pairs_follow_the_20_year_gap (2,556 unflagged pairs aged 20-90), and a 70/45 couple under each head order, inferred and with supplied roles. The reference HBAI helper now needs an identified parent aged 16+, as is_hbai_dependent_child does; the under-16-parent regression also checks the reference.
• Full suites: PR CI on 73a7b90 (run 37151606551) is in progress. The last fully green run of the whole suite (YAML + pytest) was 37120834812 on f43e5ec, before main added the fixtures listed above.
• Lint: ruff format and ruff check on the changed Python files.

axiom: n/a: a PolicyEngine presumption for households entered without relationships, not a statutory rule. Benefit law defines the claimant and partner by relationship, not age.

🤖 Generated with Claude Code

[vahid-ahmadi]

Thanks Max. The rule itself is right and tightly scoped. At 12962b0 I checked it against the docstring and the YAML: gap >= 20 ORed onto #2040's rule (is_claimant_or_partner.py:99-108), with a flagged younger member still taking the partner slot through other_parent. Ages 50/31 stay a couple, 50/30 and 90/70 split, and the boundary uses >=. At the head, the six changed YAML files pass (32 + 24 + 13 + 11 + 8 + 30 cases), and so do the seven changed property files (36 passed, 1 xfail), each run in its own process. WRA 2012 s.39(1) and SSCBA 1992 s.137(1) define a couple by marriage, civil partnership or living together "as if they were a married couple or civil partners", with no age condition, so this is purely a presumption for role-less input. The parameter files say that, and they don't cite statute.

I compared calculator-style situations for 2026 (ages only, one benefit unit and one household) on main b5b0923 and on this branch with main merged in. In every case below, results are identical to the penny once the adults are flagged is_parent, roles are supplied, or the younger adult is the head. With ages only, they move as follows:

Ages (no roles)	main	this PR
50, 30	couple, UC £8,003.64	single, UC £5,098.80; net income −£2,904.85
50, 30, younger earns £20k	couple, UC £0	single, UC £5,098.80; net income +£4,846.80
60, 38, child 10	couple, UC £12,226.20	lone parent, UC £9,321.36
45, 24, child 2	couple, UC £11,650.92	lone parent, UC £8,746.08; net income −£2,904.84
70, 48	mixed-age couple on UC £8,003.64	single pensioner on Pension Credit £12,376.00; net income +£4,372.36
67, 45, rent £9,600	UC £17,003.64	PC £12,376.00 + HB £9,600.00; net income +£4,972.36
67, 45, rent £9,600, younger earns £15k	UC £8,989.26	PC £12,376.00 + HB £9,600.00; net income +£12,734.74

1. Blocking: main has added role-less mixed-age couples that this rule now splits. I merged origin/main (b5b0923) into the head locally. The full YAML suite then gives 2,444 passed and 4 failed. Each failure is a fixture added on main after your last merge (325d585) that enters a 20+ year-gap couple without roles:

   • finance/benefit/family/housing_benefit/housing_benefit_universal_credit_passport.yaml:240 (70/40)
   • finance/benefit/family/housing_benefit/pension_age_premiums.yaml:281 (50/70)
   • finance/benefit/family/universal_credit/income/uc_earnings_deductions.yaml:62 (70/45; uc_earned_income comes out 0 against an expected £12,879.60)
   • gov/dwp/pension_credit/state_pension_credit_qualifying_age.yaml:544 (Case 23, 50/70; pension_credit comes out £12,376 against an expected 0)
     Also tests/test_council_tax_reduction_carer_income_properties.py:155-165, a generator added on main that draws working-age couples aged 25 to 60 without roles. Hypothesis fails it on a 25/57 pair (full pytest on the merged tree: 2,725 passed, 1 failed).
     All five pass on main. Fix: merge main and supply is_claimant_or_partner: true for both partners in these four YAML cases and in that generator, as you did for the others. That merge also clears the current red Test job: the failure is code_health/test_cached_arrays_not_written_in_place.py (core 3.32.16's put(..., derived=...)), which main fixed at 4ac62cb and which passes after the merge (35 passed). The only textual conflict is a comment in tests/test_uc_state_pension_properties.py (about line 114 after the merge). Resolve just that hunk and don't take --ours for the whole file: main's #1947 rework of invariants 2 and 4 auto-merges into the same file, and taking your side whole makes test_tax_on_state_pension_does_not_reduce_partners_earned_income fail. With the hunk-only resolution, the file passes (5 passed, 1 xfail).

2. Blocking (merge gate): don't merge until policyengine-app-v2#1240 is merged and deployed. Today the app sends "you" and a declared partner with ages only, and #1240 is still a draft. A merge to main publishes to PyPI by itself, so as soon as the API picks the release up, a real mixed-age couple entered in the calculator (67 and 45) moves from UC to Pension Credit plus full HB, and the partner's earnings drop out of the means test (+£12,735 above). The body already says #1240 "should land before or with this PR"; I'd make that a hard gate in the PR description and hold the merge until #1240 is live. Households saved earlier with ages only also need re-saving (or a backfill) before they pick up roles.

3. Should fix: the split reading leaves the "adult child" uncharged. Once the 45-year-old is presumed the claimant's child, they are an adult in the claimant's benefit unit but not a claimant or partner, and main charges no non-dependant deduction for that. For the 67/45/£15k case, housing_benefit_non_dep_deductions is £0 and HB is the full £9,600. The same people in separate benefit units get a £3,346.20 deduction and HB of £6,253.80. So the PR's intended reading (parent plus adult child) is costed more generously than the law would cost it, until in-unit non-dependant deductions land (#2017, and #2077 for local CTR). Either sequence this after #2017, or add a sentence to the docstring (is_claimant_or_partner.py:39-46) and the changelog saying the presumed adult child is not yet charged as a non-dependant.

4. Nit: pin the young-child case. 45, 24, child 2 with ages only now reads as a lone parent with an adult child, and UC drops by £2,904.84. #2040's young-child exception only fires when the claimant is flagged, so it doesn't help unflagged input. The body's evidence is for adult pairs without conditioning on a young child in the unit, so I'm not claiming this is wrong. But it's a common calculator shape, so it deserves a YAML case in benefit_unit_structure.yaml (next to the 60/38/10 trade-off case at line 502) so the behaviour is explicit.

5. Nit: overlaps. Once main is in, test_uc_state_pension_properties.py is also touched by #2081, #1963, #1999 and #2131, and test_child_and_adult_definitions_properties.py by #2030 and #2016. Whichever lands second should keep the supplied roles in the generators.

The PR body is clean on disclosure: survey-household counts suppressed under 10 and weighted totals only, with no record ids, weights or record-level amounts.