Add Housing Benefit documentation page (#771)

changelog.d/771-housing-benefit.md

@@ -0,0 +1 @@
+- Add a Housing Benefit documentation page covering eligibility (legacy-only working-age claimants, pension-age and supported-housing tenants), the four-stage entitlement computation, a personal-allowances chart, and statutory references; checks off one of the entries in the #771 docs-pages todo list.

docs/book/programs/gov/dwp/housing-benefit.ipynb

@@ -0,0 +1,129 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Housing Benefit\n",
+    "\n",
+    "Housing Benefit is a means-tested DWP benefit that helps people on a low income with their rent. It is a legacy benefit that is being phased out: new working-age claimants are routed to the Universal Credit housing element instead, and a managed migration of the remaining HB caseload to UC is in progress. Housing Benefit continues to operate for two groups — pensioners and tenants of supported/temporary accommodation — and PolicyEngine models it alongside the UC housing element so reform analyses can move between the two systems cleanly.\n",
+    "\n",
+    "Parameters live in `policyengine_uk/parameters/gov/dwp/housing_benefit/` and the formulas in `policyengine_uk/variables/gov/dwp/housing_benefit/`."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Eligibility\n",
+    "\n",
+    "`housing_benefit_eligible` requires all of:\n",
+    "\n",
+    "- the benunit was **already claiming** Housing Benefit in the previous period (proxied by a positive `housing_benefit_reported`) — this gates out new working-age claimants per the UC migration policy,\n",
+    "- the benunit is either in **social housing** or eligible for the **Local Housing Allowance** rate (broadly, private renters),\n",
+    "- the benunit is **not claiming Universal Credit**, and\n",
+    "- assessable capital is at or below the working-age (or pension-age) capital limit.\n",
+    "\n",
+    "The take-up step is handled separately by the input variable `would_claim_housing_benefit`, populated stochastically when the dataset is built so that aggregates match published DWP caseloads."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## How PolicyEngine computes Housing Benefit\n",
+    "\n",
+    "The award is computed in four stages:\n",
+    "\n",
+    "1. **Eligible rent** (`benunit_rent`): the contracted rent for the property, capped at the Local Housing Allowance rate where the LHA applies.\n",
+    "2. **Applicable amount** (`housing_benefit_applicable_amount`): a personal allowance derived from the benunit's composition (single, couple, lone parent) and age, plus any disability/carer premiums. This is the \"minimum income\" the household needs before HB tapers begin.\n",
+    "3. **Means test** (`housing_benefit_entitlement`): the benunit's `housing_benefit_applicable_income` in excess of the applicable amount is tapered against the eligible rent at the published `withdrawal_rate` (currently 0.65). The result is then reduced by `housing_benefit_non_dep_deductions` for any non-dependant adults living in the household.\n",
+    "4. **Benefit cap** (`housing_benefit`): the post-means-test award is finally reduced by `benefit_cap_reduction` if the household's total benefit income exceeds the cap and no cap exemption applies.\n",
+    "\n",
+    "The take-up gate (`would_claim_housing_benefit`) is applied inside `housing_benefit_pre_benefit_cap` so the post-cap variable matches reported caseload after take-up."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Personal allowances\n",
+    "\n",
+    "The applicable amount uses age- and household-composition bands. The chart below shows how the weekly allowances have evolved."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {"tags": ["hide-input"]},
+   "source": [
+    "import warnings\n",
+    "warnings.filterwarnings(\"ignore\")\n",
+    "\n",
+    "from policyengine_uk.system import system\n",
+    "import pandas as pd\n",
+    "import plotly.express as px\n",
+    "from policyengine_core.charts import format_fig\n",
+    "\n",
+    "allowances = system.parameters.gov.dwp.housing_benefit.allowances\n",
+    "\n",
+    "params = {\n",
+    "    \"Single (younger)\": allowances.single.younger,\n",
+    "    \"Single (older)\": allowances.single.older,\n",
+    "    \"Single (aged)\": allowances.single.aged,\n",
+    "    \"Lone parent (younger)\": allowances.lone_parent.younger,\n",
+    "    \"Lone parent (older)\": allowances.lone_parent.older,\n",
+    "    \"Lone parent (aged)\": allowances.lone_parent.aged,\n",
+    "    \"Couple (younger)\": allowances.couple.younger,\n",
+    "    \"Couple (older)\": allowances.couple.older,\n",
+    "    \"Couple (aged)\": allowances.couple.aged,\n",
+    "}\n",
+    "\n",
+    "dates = [f\"{y}-04-01\" for y in range(2016, 2026)]\n",
+    "rows = [\n",
+    "    {\"date\": d, \"composition\": name, \"weekly allowance\": p(d)}\n",
+    "    for d in dates\n",
+    "    for name, p in params.items()\n",
+    "]\n",
+    "df = pd.DataFrame(rows)\n",
+    "\n",
+    "fig = px.line(\n",
+    "    df,\n",
+    "    x=\"date\",\n",
+    "    y=\"weekly allowance\",\n",
+    "    color=\"composition\",\n",
+    "    title=\"Housing Benefit weekly personal allowances\",\n",
+    ").update_layout(\n",
+    "    yaxis_tickprefix=\"£\",\n",
+    "    yaxis_tickformat=\",.2f\",\n",
+    "    xaxis_title=\"Date\",\n",
+    "    legend_title=\"Composition\",\n",
+    ").update_traces(line_shape=\"hv\")\n",
+    "fig = format_fig(fig)\n",
+    "fig"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## References\n",
+    "\n",
+    "- [Social Security Contributions and Benefits Act 1992, s. 130](https://www.legislation.gov.uk/ukpga/1992/4/section/130) — the primary statute creating Housing Benefit.\n",
+    "- [The Housing Benefit Regulations 2006 (SI 2006/213)](https://www.legislation.gov.uk/uksi/2006/213/contents) and [The Housing Benefit (Persons who have attained the qualifying age for state pension credit) Regulations 2006 (SI 2006/214)](https://www.legislation.gov.uk/uksi/2006/214/contents) — the operational regulations for working-age and pension-age claimants respectively.\n",
+    "- DWP, [Housing Benefit: detailed information](https://www.gov.uk/housing-benefit) — user-facing guidance covering the move to Universal Credit.\n",
+    "- DWP, [Housing Benefit caseload statistics](https://www.gov.uk/government/collections/housing-benefit-caseload-statistics) — official caseload and expenditure outturns used by `policyengine-uk-data` for calibration."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}