Repository navigation
Update the capital gains distribution docs page (#818) - #1731
Merged
Merged
Conversation
vahid-ahmadi
force-pushed
the
vahid-ahmadi/issue-818-cg-multivariate-plan
branch
from
October 8, 2026 14:53
1f9dcfe to
07625f2
Compare
#818 asks for a multivariate capital gains imputation instead of the current per-income-decile-independent fits. #817 reports the related failure mode of imputing gains to zero-wealth households. The imputation lives in policyengine-uk-data, not in this repo, but persist the model-facing plan here so the cross-repo agreement is discoverable. The page covers: - the current state (per-decile marginal distributions fit to HMRC CGT statistics binned by income), - three concrete limitations (overfitting boundaries, no wealth conditioning per #817, no within-decile correlation), - two candidate approaches: A. multivariate Gaussian KDE following OG-USA's bequest-transmission model; B. two-stage QRF reusing the existing imputation infrastructure already proposed in the #1621 pipeline-alignment plan, - recommendation: B (QRF) because the infrastructure exists, it handles correlated predictors naturally, and it solves both #818 and #817 in one move by adding total_wealth as a predictor, - the model-side surface (negligible, since the input variable stays the same; one new regression test for "no gains on zero-wealth households"), - open questions on the wealth donor source (FRS vs WAS) and on elasticity-by-band as a follow-up. Closes both #818 and #817 in the planning sense.
Describe the BADR, residential property and carried interest components (#1861) and the retention-rate elasticity, replace the per-decile description with the Microcosm stages that fit gains to HMRC Table 3 by size of gain and taxable income, and list what is left for #817 and #818. Type the changelog fragment. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Enhanced FRS is still the certified default. Describe the BADR elasticity switch added on 1 October (off by default), the six Microcosm CGT stages including the incidence anchor and residential split, and the income-band (not decile) spline in policyengine-uk-data. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
vahid-ahmadi
force-pushed
the
vahid-ahmadi/issue-818-cg-multivariate-plan
branch
from
October 12, 2026 09:09
07625f2 to
544cb21
Compare
Main already carries this page (#2386) and released its changelog line in 2.143.0. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The page reached main through #2386 and its changelog line shipped in 2.143.0, so this drops the released .added fragment and corrects main's copy: - Microcosm UK became the certified default on 21 October 2026 (policyengine.py#685); the Enhanced FRS is no longer the default. - Gains uprate through gov.economic_assumptions.indices.capital_gains (#2274), GDP per capita by default; the tax is on capital_gains, including the behavioural response. - The retention-rate elasticity defaults to 1.0 since #2419, not 0. - The OBR's 1.4 BADR elasticity costed the October 2024 rises. - uk-data's donor stack has been in releases since 1.57.4; from 1.59.0 it covers bands from £500,000 up. - #818 asks for a joint model; the listed failings are this page's own analysis (the "noisy tails" one is unsupported and cut). - Microcosm stages 1, 2, 4 and 6 aligned with sources.yaml; HMRC's 2026 release was published on 27 August 2026, not in July. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Collaborator
|
UK hub (Claude build session, for Max) Head: Read this first. The page is already on main, word for word, through #2386 ( This branch now:
Against main, the diff is the page and the fragment. Suggested title on landing: "Update the capital gains distribution page". Claims checked (main
|
| Claim | Verdict | Source |
|---|---|---|
The imputation is in the data build; capital_gains_before_response is a person input |
true | variables/gov/hmrc/capital_gains_tax/capital_gains_before_response.py:5-11 |
| Uprated "by OBR per-capita GDP growth" | made precise: through gov.economic_assumptions.indices.capital_gains, which copies GDP per capita unless a CapitalGainsProjection is passed (#2274) |
same file :11; policyengine_uk/data/capital_gains_projection.py:208-216 |
capital_gains_tax charges "it" |
made precise: it charges capital_gains, which adds the behavioural response |
variables/household/income/capital_gains.py:12-15; capital_gains_tax.py:73 |
| Three components at their own rates, from #1861; each a component, not an addition | true | capital_gains_tax.py:118-141,279-287; component docstrings |
| Retention-rate elasticity "0 by default" | outdated: 1.0 since #2419 (2026-10-15) | parameters/gov/simulation/capital_gains_responses/elasticity.yaml:2-3 |
separate_badr_elasticity false; badr_elasticity 1.4 |
true | separate_badr_elasticity.yaml, badr_elasticity.yaml |
| The OBR used 1.4 "in its January 2025 costing" | made precise: the costing is of the October 2024 rises; the release was January 2025 | OBR PDF (archived copy): "rates of capital gains tax (CGT) in our October 2024 Economic and fiscal outlook" and "For the increase in BADR rates, a retention rate elasticity of 1.4 was used" |
| Enhanced FRS is "the certified default" | outdated: Microcosm UK since 2026-10-21 | policyengine.py#685; bundle manifest.json default_dataset: microcosm_uk_2024_25 |
| Spline per income band; "cannot produce gains above about £2m" | true | uk-data imputations/capital_gains.py comments (~£2m) |
| Donor stack "on main (not yet in a release)", 30 per band | false: DONORS_PER_BAND = 30 and stack_cgt_band_donors are in tags 1.57.4 and 1.58.0; since 1.59.0 _MIN_DONOR_BAND_LOWER = 500_000 (was 12_300) |
uk-data capital_gains.py:199,204 (1.58.0); :239,241 (main); create_datasets.py |
| "#818 pointed out the problems" | fixed attribution: #818 asks only for a multivariate model across income groups | #818 body |
| "tails were noisy" | cut: unsupported | — |
| Six Microcosm stages, in order | true | uk/spec/sources.yaml:4540,4617,4673,4839,4907,4972 |
| Stage 1 "business wealth" | fixed: the columns are gross_financial_wealth, corporate_wealth, other_residential_property_value, non_residential_property_value |
sources.yaml:4594-4598 |
| Stage 2 "set and order of gainers come from A&S incidence" | fixed: equal-mass clone (copies: 2, mass_split: 0.5); the oldest adult draws an A&S prior; order comes from stage 3's blended rank (wealth_rank_weight: 0.75) |
sources.yaml:4628-4653,4771-4774 |
| Stage 3: Table 3 jointly by gain size × taxable income, conditioned on Tables 1, 2.1a, 5, 6 | true | sources.yaml:4674 |
| Stage 4 "more weighted people than HMRC publishes" | fixed: HMRC publishes no count; the anchor uses the A&S reporter composition | sources.yaml:4906 |
Stage 5, Table 8, capital_gains_residential_property |
true | sources.yaml:4939-4955 |
| Stage 6 "the rest are given asset types" | fixed: all liable non-residential gainers get a main asset type, diagnostic only; carried interest is not modelled | sources.yaml:5033-5073 (diagnostic_only: true), :5092 |
| "July 2026 release" | fixed: published 27 August 2026 (Microcosm's own label at sources.yaml:4542 has the same slip) |
gov.uk content API change history, /government/statistics/capital-gains-tax-statistics |
| "largest gains placed on the wealthiest households" | softened to "mainly", via the 0.75/0.25 blended rank | sources.yaml:4773-4774 |
uk_cgt_projection_entrants gate |
true | microcosm uk/gates.json:1324-1327 |
| No zero-wealth test in either repo | true (review agent's search) | — |
| Close #818 once Microcosm is the default | updated: that condition is met | — |
| Advani and Summers (2020), CAGE WP 465 | true | RePEc cge:wacage:465 |
Corrections: 15.
Uncertain
- A strict "no gains on zero-wealth households" test may conflict with Microcosm's design: every clone carrier draws a prior, and the sub-AEA remainder can land anywhere. The page keeps it as a plan, and the owner may want a share-based check instead.
- I did not read the certified build's private receipt. The stage description follows the spec at microcosm main and at the PR's earlier pin, which have the same six stages.
Full ledger: ~/reviews/uk-hub/jobs/docs-c2/b/1731-ledger.md.
3 of 5 tasks
vahid-ahmadi
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Corrects the capital gains distribution planning page (
docs/book/assumptions/capital-gains-distribution-plan.md), written for #818 and #817.The page itself is already on main: it shipped in #2386 (merged 21 October 2026), and its original
.addedchangelog entry was released in 2.143.0. This branch has merged main, dropped the released fragment and now carries only corrections to main's copy of the page.What this PR corrects (from its changelog fragment):
The claim-by-claim review behind these corrections, with sources, is in the "Ready for hub review" comment on this PR.
changelog.d/818-capital-gains-plan-corrections.changed.md(changed).🤖 Generated with Claude Code