Add Universal Credit deductions with Fair Repayment Rate cap

.github/workflows/code_changes.yaml

@@ -54,6 +54,13 @@ jobs:
               # Only export token if non-empty (defensive against missing secrets)
               if [ -n "$HF_TOKEN_VALUE" ]; then
                 export HUGGING_FACE_TOKEN="$HF_TOKEN_VALUE"
+                # policyengine-core only passes a token to hf_hub_download when
+                # the repo reports private=True. policyengine-uk-data-private
+                # has been public + gated since 31 July 2026, so core sends the
+                # request anonymously and the gate returns 401. HF_TOKEN is
+                # huggingface_hub's implicit-token variable, used when the
+                # explicit token is None, which restores authentication.
+                export HF_TOKEN="$HF_TOKEN_VALUE"
               fi
               make test
             env:

.github/workflows/pr_code_changes.yaml

@@ -73,6 +73,13 @@ jobs:
               # Only export token if non-empty (avoids 'Bearer ' error for Dependabot PRs)
               if [ -n "$HF_TOKEN_VALUE" ]; then
                 export HUGGING_FACE_TOKEN="$HF_TOKEN_VALUE"
+                # policyengine-core only passes a token to hf_hub_download when
+                # the repo reports private=True. policyengine-uk-data-private
+                # has been public + gated since 31 July 2026, so core sends the
+                # request anonymously and the gate returns 401. HF_TOKEN is
+                # huggingface_hub's implicit-token variable, used when the
+                # explicit token is None, which restores authentication.
+                export HF_TOKEN="$HF_TOKEN_VALUE"
               fi
               make test
             env:

changelog.d/uc-deductions.added.md

@@ -0,0 +1 @@
+Universal Credit deductions: latent deduction demand assigned from DWP deductions statistics (incidence by region, rate distribution, type combinations), the deductions cap including the 2025 Fair Repayment Rate, last resort deductions exempt from the cap, reform switches to abolish advance, third party or government debt deductions, and a protected minimum floor lever limiting combined deductions and benefit cap reductions (JRF-style floor reforms). Per-household statistics are validated against the DWP deductions statistics; weighted aggregates (deducting households, total deducted, the cost of floor reforms) run low in proportion to the model's UC caseload shortfall (policyengine-uk-data#452) and should not be quoted without that caveat - see the deductions validation page in the documentation for the limitations that bound reform estimates.

docs/book/validation/uc-deductions.md

@@ -0,0 +1,84 @@
+# Universal Credit deductions
+
+```{important}
+Per-household deduction statistics are validated against the DWP deductions statistics. **Weighted aggregates are not.** They scale with the model's Universal Credit caseload, which falls short of the administrative count, so headcounts and costs of deduction reforms — including protected-floor reforms — run materially low. Quote the per-household layer; treat aggregates as lower bounds until the caseload gap closes.
+```
+
+PolicyEngine UK models the money DWP takes off Universal Credit awards to repay debts: advance repayments, government debt (benefit and tax credit overpayments) and third party deductions such as utility arrears.
+
+The implementation separates **latent demand** from the **statutory cap**. `uc_latent_deduction_rate` assigns deduction demand from the distribution DWP observed in March to May 2025 — the last full months under the 25% cap — and `gov.dwp.universal_credit.deductions.cap` applies the operational cap (40% to October 2019, 30%, 25%, then 15% under the Fair Repayment Rate from 30 April 2025) at runtime. Assigning observed post-cap rates directly would bake the cap into the data and make cap-raising reforms inexpressible.
+
+## Validation against DWP deductions statistics
+
+Enhanced FRS 2023/24 v1.40.3, against [DWP's Universal Credit deductions statistics](https://www.gov.uk/government/statistics/universal-credit-quarterly-statistics-29-april-2013-to-12-february-2026/universal-credit-deductions-statistics-march-2025-to-february-2026).
+
+| Statistic | Model | DWP published |
+|---|---|---|
+| Share of UC households with deductions | 47.0–47.1% | 46–47% |
+| At-cap share, 25% regime (2024) | 13.4% | 13–14% (Mar–May 2025) |
+| At-cap share, 15% regime (2025) | 26.4% | 21% (Jun 2025–Feb 2026) |
+| Above-cap share (last resort) | 1.8% | 2% |
+| Mean monthly deduction, 25% regime | £66 | £67–68 |
+| Mean monthly deduction, 15% regime | £50 | £51–54 |
+| Mean annual gain, 25%→15% cap | £421 | £420 (gov.uk) |
+| Households better off, 25%→15% cap | 1.01m | ~1.2m (gov.uk) |
+
+The pre-Fair-Repayment-Rate pileup at the cap and both regimes' mean amounts reproduce without being separately fitted: the cap parameter generates them from the same latent distribution.
+
+## Limitations
+
+These bound what the module can support. They are stated rather than tuned away.
+
+### Aggregates scale with the UC caseload
+
+The model has 4.2m UC benefit units against roughly 7.2m administrative households, and correspondingly 1.9m deducting households and £1.2bn/year deducted against 3.3m and roughly £2.0bn/year in the administrative data. This is the model's UC take-up and calibration gap, not a deductions artefact — per-household statistics validate precisely because the gap divides out. It is tracked in [policyengine-uk-data#452](https://github.com/PolicyEngine/policyengine-uk-data/issues/452).
+
+The practical consequence: **poverty headcounts and exchequer costs of a protected-floor or cap reform run low roughly in proportion to the caseload shortfall.** Analyses replicating published floor estimates (such as JRF's) should compare per-household gains and distributional shape, not totals.
+
+### The at-cap share under the 15% regime runs high
+
+The model puts 26.4% of UC households at the 15% cap against 21% observed. The latent-demand model holds demand fixed while real deductions attrit under a lower cap through affordability requests and composition drift.
+
+This has a direction. Reforms that **lower** the cap further overstate the number of constrained households and so overstate the gains from later raising it. Reforms that **raise** the cap toward 25% sit inside the observed window and are on firmer ground.
+
+### Only 2024 and 2025 are validated
+
+The latent distribution is observed in 2025 and applied to all model years as a constancy assumption; published deductions statistics begin in March 2025. Simulations of years before 2021 apply a 2025-shaped demand distribution under the 40% and 30% caps then in force, which no published statistic can check. Treat pre-2024 deduction results as uncalibrated.
+
+### The protected floor binds on last resort deductions
+
+The `protected_floor` lever limits combined deductions and benefit cap reductions to (1 − floor) × the standard allowance. It binds on the whole of `uc_deductions`, including the above-cap excess that current law exempts from the deductions cap (last resort and child maintenance deductions). JRF's briefing does not say whether their floor exempts those categories — its worked example involves only cappable deductions and the benefit cap — so this is a modeling choice.
+
+### Other assumptions
+
+- Rate and type combination are drawn independently: DWP publishes no joint table. Type-abolition reforms split a household's rate by national mean amounts per type (£41 advance / £37 third party / £59 government).
+- Deduction spells are annualised under the surveyed-status-as-full-year convention. Monthly means validate, so cross-sectional statistics are sound, but annual per-household gains are upper bounds for spell-limited types such as advance recovery (at most 24 months).
+- The last resort band is top-coded at 25% in DWP tables; its 30% upper edge is a modeling assumption.
+- Regional incidence factors derive from rounded constituency proportions across all 633 rows of DWP's Table 6.
+- The rate distribution is national. Regional composition plausibly differs (more advances in high-incidence regions); the module assumes it does not.
+
+## Reform levers
+
+```python
+# Return the cap to 25%:
+{"gov.dwp.universal_credit.deductions.cap": {"2026-01-01.2030-12-31": 0.25}}
+
+# Abolish government debt deductions only:
+{
+    "gov.dwp.universal_credit.deductions.abolish.government": {
+        "2026-01-01.2030-12-31": True
+    }
+}
+
+# JRF-style protected minimum floor at 85% of the standard allowance,
+# binding on deductions and benefit cap reductions jointly:
+{"gov.dwp.universal_credit.deductions.protected_floor": {"2026-01-01.2030-12-31": 0.85}}
+```
+
+A cap of 1 − *x* is equivalent to a protected minimum floor at *x* of the standard allowance for capped deduction types. The dedicated `protected_floor` lever additionally binds on benefit cap reductions, which is where most of JRF's post-Fair-Repayment-Rate effect comes from.
+
+## Where the assignment lives
+
+Statutory parameters — the cap, the protected floor, the minimum payable penny, the abolition switches — live under `gov.dwp.universal_credit.deductions`. The calibrated distributions live under `gov.simulation.uc_deductions`: they describe the world, not the law.
+
+The assignment formulas are an explicit fallback. The end state imputes `uc_latent_deduction_rate` and `uc_deduction_combination` at dataset build, at which point the model consumes them as plain inputs and the fallback retires; raw-FRS users keep working through the fallback until then. Assignment uses deterministic splitmix64 hashes of `benunit_id`, reproducible across runs and machines, and overridable by datasets or situations through `uc_deduction_random_draw` and `uc_deduction_type_random_draw`. Single-household simulations get no deductions unless set explicitly.

policyengine_uk/parameters/gov/dwp/universal_credit/deductions/abolish/advance.yaml

@@ -0,0 +1,9 @@
+description: Remove advance repayment deductions from Universal Credit. Reform switch - false under current law, which recovers advances by deduction under Schedule 6 of SI 2013/380 and DWP deductions guidance.
+values:
+  2015-04-01: false
+metadata:
+  label: Abolish UC advance repayment deductions
+  unit: bool
+  reference:
+    - title: DWP guidance, Deductions V17.0 (deduction types and priority order)
+      href: https://data.parliament.uk/DepositedPapers/Files/DEP2024-0673/054_Deductions_V17.0.pdf#page=3

policyengine_uk/parameters/gov/dwp/universal_credit/deductions/abolish/government.yaml

@@ -0,0 +1,9 @@
+description: Remove government debt deductions (benefit and tax credit overpayment recovery) from Universal Credit. Reform switch - false under current law, which recovers government debt by deduction under Schedule 6 of SI 2013/380 and DWP deductions guidance.
+values:
+  2015-04-01: false
+metadata:
+  label: Abolish UC government debt deductions
+  unit: bool
+  reference:
+    - title: DWP guidance, Deductions V17.0 (deduction types and priority order)
+      href: https://data.parliament.uk/DepositedPapers/Files/DEP2024-0673/054_Deductions_V17.0.pdf#page=2

policyengine_uk/parameters/gov/dwp/universal_credit/deductions/abolish/third_party.yaml

@@ -0,0 +1,9 @@
+description: Remove third party deductions (e.g. utility and housing arrears paid direct to creditors) from Universal Credit. Reform switch - false under current law, which makes third party deductions under Schedule 6 of SI 2013/380 and DWP deductions guidance.
+values:
+  2015-04-01: false
+metadata:
+  label: Abolish UC third party deductions
+  unit: bool
+  reference:
+    - title: DWP guidance, Deductions V17.0 (deduction types and priority order)
+      href: https://data.parliament.uk/DepositedPapers/Files/DEP2024-0673/054_Deductions_V17.0.pdf#page=4

policyengine_uk/parameters/gov/dwp/universal_credit/deductions/cap.yaml

@@ -0,0 +1,27 @@
+description: Maximum total deductions from a Universal Credit award, as a fraction of the standard allowance. Schedule 6 paragraph 4(1) of SI 2013/380 sets a statutory ceiling of 40%; within it, DWP sets the operational cap administratively - 30% from October 2019 (Budget 2018), 25% from April 2021 (announced for October 2021 at Budget 2020, brought forward at Budget 2021), and 15% (the Fair Repayment Rate) from 30 April 2025, which required no legislative change. Last resort deductions (housing and fuel arrears hardship deductions) and child maintenance deductions - separate categories in DWP guidance - may each exceed the cap (Explanatory Memorandum to SI 2025/387, paragraphs 5.10 to 5.15).
+values:
+  2015-04-01: 0.4
+  2019-10-01: 0.3
+  2021-04-01: 0.25
+  2025-04-30: 0.15
+metadata:
+  label: UC deductions cap
+  unit: /1
+  period: year
+  reference:
+    - title: SI 2013/380, Schedule 6, paragraph 4(1) (40% statutory ceiling)
+      href: https://www.legislation.gov.uk/uksi/2013/380/schedule/6/paragraph/4/1
+    - title: Explanatory Memorandum to SI 2025/387, paragraph 5.2 (operational cap set within the ceiling; no legislative change for the Fair Repayment Rate)
+      href: https://www.legislation.gov.uk/uksi/2025/387/pdfs/uksiem_20250387_en_001.pdf#page=2
+    - title: Explanatory Memorandum to SI 2025/387, paragraphs 5.10 to 5.15 (child maintenance deductions may exceed the 15% cap)
+      href: https://www.legislation.gov.uk/uksi/2025/387/pdfs/uksiem_20250387_en_001.pdf#page=3
+    - title: DWP guidance, Deductions V17.0 (maximum rates of deductions)
+      href: https://data.parliament.uk/DepositedPapers/Files/DEP2024-0673/054_Deductions_V17.0.pdf#page=3
+    - title: HM Treasury, Budget 2018, para 5.36 (cap to 30% from October 2019)
+      href: https://assets.publishing.service.gov.uk/media/5bd718b8ed915d78a0dc107d/Budget_2018_red_web.pdf#page=80
+    - title: HM Treasury, Budget 2020, para 2.9 (cap to 25%, announced for October 2021)
+      href: https://assets.publishing.service.gov.uk/media/5e68d0dce90e070ac74f08ea/Budget_2020_Web_Accessible_Complete.pdf#page=73
+    - title: HM Treasury, Budget 2021 (25% cap brought forward to April 2021)
+      href: https://www.gov.uk/government/publications/budget-2021-documents/budget-2021-html
+    - title: Universal Credit change brings £420 boost to over a million households (Fair Repayment Rate, 30 April 2025)
+      href: https://www.gov.uk/government/news/universal-credit-change-brings-420-boost-to-over-a-million-households

policyengine_uk/parameters/gov/dwp/universal_credit/deductions/minimum_payable.yaml

@@ -0,0 +1,10 @@
+description: Minimum Universal Credit payable after deductions, per assessment period. Schedule 6 of SI 2013/380 provides that deductions must not reduce the amount payable to the claimant below one penny.
+values:
+  2015-04-01: 0.01
+metadata:
+  label: UC minimum payable after deductions
+  unit: currency-GBP
+  period: month
+  reference:
+    - title: SI 2013/380, Schedule 6 (deductions from benefit and direct payment to third parties)
+      href: https://www.legislation.gov.uk/uksi/2013/380/schedule/6

policyengine_uk/parameters/gov/dwp/universal_credit/deductions/protected_floor.yaml

@@ -0,0 +1,10 @@
+description: Protected minimum floor in Universal Credit, as a fraction of the standard allowance. When above zero, combined deductions and benefit cap reductions are limited to (1 - floor) times the standard allowance, following JRF's proposal design (their worked example limits the reduction itself to 15% of the standard allowance). Zero - the value under current law, which has no such floor - leaves reductions unlimited. Setting 0.85 models JRF's proposal; this reform-lever parameter encodes no current-law value other than zero. The modeled floor binds on all deductions, including the above-cap excess that current law exempts from the deductions cap (last resort and child maintenance deductions) - JRF's briefing does not state whether their floor exempts those categories, and its worked example involves only cappable deductions and the benefit cap, so treating the floor as binding on everything is a modeling choice rather than a stated feature of the proposal.
+values:
+  2015-04-01: 0
+metadata:
+  label: UC protected minimum floor
+  unit: /1
+  period: year
+  reference:
+    - title: JRF, A protected minimum floor in Universal Credit (October 2025 briefing; proposal design source, not current law)
+      href: https://www.jrf.org.uk/social-security/protected-minimum-floor-in-universal-credit-new-policy-targeting-hardship

policyengine_uk/parameters/gov/simulation/uc_deductions/calibration_cap.yaml

@@ -0,0 +1,10 @@
+description: The deductions cap in force during the calibration window (March to May 2025, under the 25% cap). Latent demand above this boundary is the above-cap excess (last resort and child maintenance categories), which sits on top of the operational cap; demand at exactly this level is the old-cap pileup, treated as cappable. Changes only if the model is recalibrated to a window under a different cap.
+values:
+  2015-04-01: 0.25
+metadata:
+  label: UC deductions calibration-window cap
+  unit: /1
+  period: year
+  reference:
+    - title: DWP, Universal Credit deductions statistics March 2025 to February 2026, supplementary data tables, Table 2
+      href: https://assets.publishing.service.gov.uk/media/69fb3ea22a6137e93226b7ce/universal-credit-deductions-march-2025-to-february-2026.ods