Childcare subsidies documentation

.gitignore

@@ -53,3 +53,4 @@ policyengine_uk/calibration/*.h5
 **/ukmod.json
 
 *.ipynb
+!docs/**/*.ipynb

docs/book/_toc.yml

@@ -26,3 +26,7 @@ parts:
       - file: programs/gov/dcms/bbc/tv-licence
       - file: programs/gov/revenue_scotland/land-and-buildings-transaction-tax
       - file: programs/gov/wra/land-transaction-tax
+      - file: programs/gov/hmrc/tax-free-childcare
+      - file: programs/gov/dfe/extended-childcare-entitlement
+      - file: programs/gov/dfe/universal-childcare-entitlement
+

docs/book/programs/gov/dfe/extended-childcare-entitlement.ipynb

@@ -0,0 +1,150 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Extended childcare entitlement\n",
+    "\n",
+    "[Official government guidance](https://www.gov.uk/check-eligible-free-childcare-if-youre-working?step-by-step-nav=f517cd57-3c18-4bb9-aa8b-1b907e279bf9) | [Legislation](https://www.legislation.gov.uk/uksi/2017/1160/pdfs/uksiem_20171160_en.pdf)\n",
+    "\n",
+    "## Program description\n",
+    "\n",
+    "### Overview\n",
+    "\n",
+    "The program provides free childcare hours based on the child's age:\n",
+    "* Children aged **9 months to 2 years** receive **15 hours** of free childcare per week\n",
+    "* Children aged **3 to 4 years** receive **30 hours** of free childcare per week\n",
+    "\n",
+    "### Eligibility requirements\n",
+    "\n",
+    "#### Work status\n",
+    "Eligible individuals must be either employed or about to start employment. This includes those on qualifying leave types: **sick**, **annual**, **shared parental**, **maternity**, **paternity**, or **adoption** leave.\n",
+    "\n",
+    "Non-working partners may qualify if they receive: **incapacity benefit**, **severe disablement allowance**, **carer's allowance**, **limited capability for work benefit**, or **contribution-based employment and support allowance**.\n",
+    "\n",
+    "#### Income requirements\n",
+    "Minimum earnings thresholds (per **3 months**) vary by age:\n",
+    "\n",
+    "| Age group | Minimum earnings | Weekly equivalent |\n",
+    "|-----------|-----------------|-------------------|\n",
+    "| **21+** | **£2,380** | **£183** |\n",
+    "| **18-20** | **£1,788** | **£137** |\n",
+    "| **Under 18/Apprentices** | **£1,331** | **£102** |\n",
+    "\n",
+    "These thresholds are based on national minimum wage calculations for **16 hours** per week.\n",
+    "\n",
+    "Maximum income limit: Adjusted net income must not exceed **£100,000** per year.\n",
+    "\n",
+    "### Additional rules\n",
+    "\n",
+    "#### Income assessment\n",
+    "The program offers flexible income assessment:\n",
+    "* Combines **multiple income sources**\n",
+    "* Allows **annual income averaging**\n",
+    "* Gives **self-employed** individuals choice between total or self-employment income\n",
+    "\n",
+    "Certain types of income are excluded from calculations: **dividends**, **interest**, **property income**, and **pension payments**.\n",
+    "\n",
+    "## Implementation\n",
+    "\n",
+    "The extended childcare entitlement program is modeled through several interconnected components:\n",
+    "\n",
+    "### 1. Parameter definition\n",
+    "Located in [`parameters/gov/dfe/extended_childcare_entitlement/`](https://github.com/PolicyEngine/policyengine-uk/tree/20ed1a9d77a3307b3e2bc4a0986ec606ab7fead9/policyengine_uk/parameters/gov/dfe/extended_childcare_entitlement), key parameters include:\n",
+    "\n",
+    "* Income requirements:\n",
+    "  * [`countable_sources.yaml`](https://github.com/PolicyEngine/policyengine-uk/tree/20ed1a9d77a3307b3e2bc4a0986ec606ab7fead9/policyengine_uk/parameters/gov/dfe/extended_childcare_entitlement): Defines eligible income sources\n",
+    "  * [`limit.yaml`](https://github.com/PolicyEngine/policyengine-uk/tree/20ed1a9d77a3307b3e2bc4a0986ec606ab7fead9/policyengine_uk/parameters/gov/dfe/extended_childcare_entitlement): Sets the £100,000 maximum income threshold\n",
+    "  * [`minimum_weekly_hours.yaml`](https://github.com/PolicyEngine/policyengine-uk/tree/20ed1a9d77a3307b3e2bc4a0986ec606ab7fead9/policyengine_uk/parameters/gov/dfe/extended_childcare_entitlement): Specifies required working hours\n",
+    "\n",
+    "* Program specifics:\n",
+    "  * [`hours.yaml`](https://github.com/PolicyEngine/policyengine-uk/tree/20ed1a9d77a3307b3e2bc4a0986ec606ab7fead9/policyengine_uk/parameters/gov/dfe/extended_childcare_entitlement): Defines entitlement hours by age group\n",
+    "  * [`expense_rate.yaml`](https://github.com/PolicyEngine/policyengine-uk/tree/20ed1a9d77a3307b3e2bc4a0986ec606ab7fead9/policyengine_uk/parameters/gov/dfe/extended_childcare_entitlement): Sets childcare funding rates\n",
+    "  * [`weeks_per_year.yaml`](https://github.com/PolicyEngine/policyengine-uk/tree/20ed1a9d77a3307b3e2bc4a0986ec606ab7fead9/policyengine_uk/parameters/gov/dfe/extended_childcare_entitlement): Specifies annual coverage\n",
+    "  * [`disability_criteria.yaml`](https://github.com/PolicyEngine/policyengine-uk/blob/20ed1a9d77a3307b3e2bc4a0986ec606ab7fead9/policyengine_uk/parameters/gov/dfe/extended_childcare_entitlement/disability_criteria.yaml): Lists qualifying disability conditions\n",
+    "\n",
+    "### 2. Income assessment\n",
+    "Implemented in [`extended_childcare_entitlement_meets_income_requirements.py`](https://github.com/PolicyEngine/policyengine-uk/tree/20ed1a9d77a3307b3e2bc4a0986ec606ab7fead9/policyengine_uk/variables/gov/dfe/extended_childcare_entitlement/conditions):\n",
+    "* Calculates total eligible income from specified sources\n",
+    "* Converts yearly income to quarterly periods\n",
+    "* Applies minimum wage thresholds based on work hours\n",
+    "* Checks against maximum income limit\n",
+    "\n",
+    "Example table:\n",
+    "\n",
+    "| Child age | Is compulsory school age | Weekly hours entitlement |\n",
+    "|-----------|-------------------------|------------------------|\n",
+    "| 1         | False                   | 15                     |\n",
+    "| 3         | False                   | 30                     |\n",
+    "| 4         | False                   | 30                     |\n",
+    "| 5         | True                    | 0                      |\n",
+    "\n",
+    "### 3. Work condition verification\n",
+    "Handled by [`extended_childcare_entitlement_work_condition.py`](https://github.com/PolicyEngine/policyengine-uk/tree/20ed1a9d77a3307b3e2bc4a0986ec606ab7fead9/policyengine_uk/variables/gov/dfe/extended_childcare_entitlement/conditions):\n",
+    "* Verifies employment status\n",
+    "* Handles special cases for:\n",
+    "  * Single parents (must be working)\n",
+    "  * Couples (both working or one working with partner qualifying for disability benefits)\n",
+    "  * Carers (considers UC Carer Element)\n",
+    "* Includes disability-based eligibility checks using defined criteria\n",
+    "\n",
+    "Example table:\n",
+    "\n",
+    "| Adult age | Quarterly earnings | Is over £100k | Meets minimum earnings | Is income eligible |\n",
+    "|-----------|-------------------|---------------|----------------------|-------------------|\n",
+    "| 22        | £2,500            | False         | True                 | True              |\n",
+    "| 19        | £1,500            | False         | False                | False             |\n",
+    "| 35        | £10,000           | True          | True                 | False             |\n",
+    "| 18        | £1,400            | False         | True                 | True              |\n",
+    "\n",
+    "### 4. Overall eligibility determination\n",
+    "Managed by [`extended_childcare_entitlement_eligible.py`](https://github.com/PolicyEngine/policyengine-uk/tree/20ed1a9d77a3307b3e2bc4a0986ec606ab7fead9/policyengine_uk/variables/gov/dfe/extended_childcare_entitlement):\n",
+    "* Combines results from income and work condition checks\n",
+    "* Applies eligibility rules at the benefit unit level\n",
+    "* Ensures all adult members (except children) meet requirements\n",
+    "* Returns final boolean eligibility determination\n",
+    "\n",
+    "Example table:\n",
+    "\n",
+    "| Family composition | Is partner 1 working | Is partner 2 working | Has qualifying disability | Meets work condition |\n",
+    "|-------------------|---------------------|---------------------|------------------------|-------------------|\n",
+    "| Single            | True                | N/A                 | N/A                    | True              |\n",
+    "| Couple            | True                | True                | False                  | True              |\n",
+    "| Couple            | True                | False               | True                   | True              |\n",
+    "| Couple            | False               | False               | True                   | False             |\n",
+    "\n",
+    "### 5. Entitlement calculation\n",
+    "Final calculations in [`extended_childcare_entitlement.py`](https://github.com/PolicyEngine/policyengine-uk/tree/20ed1a9d77a3307b3e2bc4a0986ec606ab7fead9/policyengine_uk/variables/gov/dfe/extended_childcare_entitlement):\n",
+    "* Determines weekly hours based on child's age\n",
+    "* Applies appropriate funding rates\n",
+    "* Calculates total annual entitlement value\n",
+    "* Considers:\n",
+    "  * Child's age for hours allocation\n",
+    "  * Applicable expense rates\n",
+    "  * Number of weeks per year\n",
+    "  * Multiple children in the benefit unit\n",
+    "\n",
+    "Example table:\n",
+    "\n",
+    "| Child age | Weekly hours | Funding rate | Annual entitlement |\n",
+    "|-----------|-------------|-------------|-------------------|\n",
+    "| 2         | 15          | £8.28       | £4,719.6         |\n",
+    "| 3         | 30          | £5.88     | £6,703.2         |"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "base",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.11.10"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

docs/book/programs/gov/dfe/universal-childcare-entitlement.ipynb

@@ -0,0 +1,97 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Universal childcare entitlement\n",
+    "\n",
+    "[Official government guidance](https://www.gov.uk/help-with-childcare-costs/free-childcare-and-education-for-3-to-4-year-olds?step-by-step-nav=f237ec8e-e82c-4ffa-8fba-2a88a739783b) | [Legislation](https://researchbriefings.files.parliament.uk/documents/CBP-8054/CBP-8054.pdf.#:~:text=All%20three%20and%20four%2Dyear%2Dolds%20in%20England%20are%20eligible,and%20applies%20irrespective%20of%20income.)\n",
+    "\n",
+    "## Program description\n",
+    "\n",
+    "### Overview\n",
+    "\n",
+    "A universal program providing free childcare for all **3-4 year olds** in England. Each eligible child receives **570 hours** of free childcare annually, typically delivered as **15 hours** per week across **38 weeks** of the year. Parents may arrange different hour distributions if their provider offers flexibility.\n",
+    "\n",
+    "### Key features\n",
+    "\n",
+    "#### Provider requirements\n",
+    "The free childcare must be delivered through an **approved childcare provider**.\n",
+    "\n",
+    "#### Regional scope\n",
+    "\n",
+    "This program applies to **England** only. Scotland, Wales, and Northern Ireland operate their own distinct childcare support schemes.\n",
+    "\n",
+    "## Implementation\n",
+    "\n",
+    "The universal childcare entitlement program is implemented through a combination of parameter definitions and variable calculations:\n",
+    "\n",
+    "### 1. Parameter Definition\n",
+    "Located in [`parameters/gov/dfe/universal_childcare_entitlement/`](https://github.com/PolicyEngine/policyengine-uk/tree/20ed1a9d77a3307b3e2bc4a0986ec606ab7fead9/policyengine_uk/parameters/gov/dfe), key parameters include:\n",
+    "\n",
+    "* Program eligibility:\n",
+    "  * [`min_age.yaml`](https://github.com/PolicyEngine/policyengine-uk/tree/20ed1a9d77a3307b3e2bc4a0986ec606ab7fead9/policyengine_uk/parameters/gov/dfe/universal_childcare_entitlement): Defines the minimum eligible age (3 years)\n",
+    "  * [`compulsory_school_age.yaml`](https://github.com/PolicyEngine/policyengine-uk/tree/20ed1a9d77a3307b3e2bc4a0986ec606ab7fead9/policyengine_uk/parameters/gov/dfe): Sets the upper age limit\n",
+    "  * [`hours.yaml`](https://github.com/PolicyEngine/policyengine-uk/tree/20ed1a9d77a3307b3e2bc4a0986ec606ab7fead9/policyengine_uk/parameters/gov/dfe/universal_childcare_entitlement): Specifies the 15 hours per week entitlement\n",
+    "\n",
+    "* Funding parameters:\n",
+    "  * [`childcare_funding_rate.yaml`](https://github.com/PolicyEngine/policyengine-uk/tree/20ed1a9d77a3307b3e2bc4a0986ec606ab7fead9/policyengine_uk/parameters/gov/dfe): Defines the hourly funding rates\n",
+    "\n",
+    "### 2. Eligibility Determination\n",
+    "Implemented in [`universal_childcare_entitlement_eligible.py`](https://github.com/PolicyEngine/policyengine-uk/tree/20ed1a9d77a3307b3e2bc4a0986ec606ab7fead9/policyengine_uk/variables/gov/dfe/universal_childcare_entitlement), which checks:\n",
+    "\n",
+    "* Geographic eligibility:\n",
+    "  * Verifies residence in England using `country` variable\n",
+    "  * Based on Childcare Regulations 2016 (part 33)\n",
+    "\n",
+    "* Age requirements:\n",
+    "  * Checks child meets minimum age requirement\n",
+    "  * Ensures child is below compulsory school age\n",
+    "  * Referenced in Section 7 of Childcare Act 2006\n",
+    "\n",
+    "Example table:\n",
+    "\n",
+    "| Child age | Is under compulsory school age | Meets minimum age | Is age eligible |\n",
+    "|-----------|--------------------------------|------------------|-----------------|\n",
+    "| 2         | True                           | False            | False           |\n",
+    "| 3         | True                           | True             | True            |\n",
+    "| 4         | True                           | True             | True            |\n",
+    "| 5         | False                          | True             | False           |\n",
+    "\n",
+    "\n",
+    "### 3. Entitlement Calculation\n",
+    "Handled by [`universal_childcare_entitlement.py`](https://github.com/PolicyEngine/policyengine-uk/tree/20ed1a9d77a3307b3e2bc4a0986ec606ab7fead9/policyengine_uk/variables/gov/dfe/universal_childcare_entitlement):\n",
+    "\n",
+    "* Defined at the person level (`entity = Person`)\n",
+    "* Only calculated for eligible individuals (`defined_for = \"universal_childcare_entitlement_eligible\"`)\n",
+    "* Uses parameters to:\n",
+    "  * Get weekly hours entitlement\n",
+    "  * Apply appropriate funding rate based on age\n",
+    "  * Calculate total annual value\n",
+    "\n",
+    "Example table:\n",
+    "\n",
+    "| Child age | Is eligible | Weekly hours | Funding rate | Number of weeks | Annual entitlement |\n",
+    "|-----------|------------|--------------|--------------|-----------------|-------------------|\n",
+    "| 2         | False      | 0            | £11.22       | 38             | £0                |\n",
+    "| 3         | True       | 15           | £5.88        | 38             | £3,351.6         |\n",
+    "| 4         | True       | 15           | £5.88        | 38             | £3,351.6         |\n",
+    "| 5         | False      | 0            | £5.88        | 38             | £0                |"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "base",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.11.10"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}