Add HBAI income concept page to the docs (#1196)

* Update HBAI docs page, add missing uprating assumptions

* Grammar

Author: nikhilwoodruff

changelog_entry.yaml

@@ -0,0 +1,5 @@
+- bump: patch
+  changes:
+    fixed:
+    - Documentation improved for HBAI income concept.
+    - Restructured HBAI income variables to better match the official definition.

docs/book/_toc.yml

@@ -7,6 +7,9 @@ parts:
   - caption: Economic assumptions
     chapters:
       - file: assumptions/growthfactors
+  - caption: Validation
+    chapters:
+      - file: validation/hbai
   - caption: Programs
     chapters:
       - file: programs/gov/hmrc/child-benefit

docs/book/validation/hbai.md

@@ -0,0 +1,72 @@
+# HBAI
+
+PolicyEngine UK includes variables that match to the Households Below Average Income (HBAI) income concepts. These are:
+
+- `hbai_household_net_income`: Household net income, before housing costs
+- `hbai_household_net_income_ahc`: Household net income, after housing costs
+- `equiv_hbai_household_net_income`: Equivalised household net income, before housing costs (BHC)
+- `equiv_hbai_household_net_income_ahc`: Equivalised household net income, after housing costs (AHC)
+
+These variables are used in the HBAI income distribution and poverty [statistics](https://www.gov.uk/government/statistics/households-below-average-income-for-financial-years-ending-1995-to-2024/households-below-average-income-an-analysis-of-the-uk-income-distribution-fye-1995-to-fye-2024), which are published by the Department for Work and Pensions (DWP) in the UK. The HBAI income concepts are defined [here](https://www.gov.uk/government/statistics/households-below-average-income-for-financial-years-ending-1995-to-2023/households-below-average-income-series-quality-and-methodology-information-report-fye-2023#income-definition).
+
+The table below shows how the HBAI income components map to PolicyEngine variables. The HBAI income definition is based on the income of all members of a household, and includes various sources of income, subtractions, and housing costs (for the AHC variant).
+
+| HBAI component | PolicyEngine variable/notes |
+|------|-------------|
+| **Income** |  |
+| Usual net earnings from employment |`employment_income` |
+| Profit or loss from self-employment (losses are treated as a negative income) | `self_employment_income`|
+| Income received from dividends (from FYE 2022) |`dividend_income`|
+| State support - all benefits and tax credits |`hbai_benefits`|
+| Income from occupational and private pensions |`private_pension_income` (includes occupational pension income)|
+| Investment income |`dividend_income`, `savings_interest_income`, `property_income`|
+| Maintenance payments |`maintenance_income`|
+| Income from educational grants and scholarships (including, for students, student loans and parental contributions) |`student_payments`|
+| The cash value of certain forms of income in kind (free school meals, free school breakfast, free school milk, free school fruit and vegetables, Healthy Start vouchers and free TV licences for those aged 75 and over who receive Pension Credit) |`free_school_meals`, `free_school_fruit_veg`, `free_school_milk`, [Healthy Start vouchers currently to-add](https://github.com/PolicyEngine/policyengine-uk/issues/1193), `free_tv_licence_value`|
+| **Subtractions** | |
+| Income tax payments |`income_tax`|
+| National Insurance contributions |`national_insurance`|
+| Domestic rates/council tax |`council_tax` and `domestic_rates`|
+| Contributions to occupational pension schemes (including all additional voluntary contributions (AVCs) to occupational pension schemes, and any contributions to stakeholder and personal pensions) |`employee_pension_contributions`, `personal_pension_contributions`|
+| All maintenance and child support payments, which are deducted from the income of the person making the payment |`maintenance_expenses`|
+| Parental contributions to students living away from home | [Missing](https://github.com/PolicyEngine/policyengine-uk/issues/1194)|
+| Student loan repayments | `student_loan_repayments`|
+| **Housing costs** | |
+| Rent (gross of housing benefit) | `rent`|
+| Water rates, community water charges and council water charges | `water_and_sewerage_charges`|
+| Mortgage interest payments | `mortgage_interest_repayment`|
+| Structural insurance premiums (for owner occupiers) | [Missing](https://github.com/PolicyEngine/policyengine-uk/issues/1195) |
+| Ground rent and service charges |`housing_service_charges`|
+
+## Nowcasting/forecasting
+
+
+Each of the variables above is either derived from other variables, or is a direct input variable. Direct input variables are uprated in future years according to economic indices, specified in the table below.
+
+| Variable | Index | Notes |
+|----------|-------|-------|
+| `employment_income` | gov.obr.per_capita.employment_income | Uprated based on OBR per capita employment income projections |
+| `self_employment_income` | gov.obr.per_capita.mixed_income | Uprated based on OBR per capita mixed income projections |
+| `dividend_income` | gov.obr.per_capita.gdp | Uprated based on OBR per capita GDP projections |
+| `hbai_benefits` | Various | Different benefits use different uprating indices, mostly gov.obr.consumer_price_index |
+| `private_pension_income` | gov.obr.private_pension_index | Uprated based on OBR private pension index |
+| `savings_interest_income` | gov.obr.per_capita.gdp | Uprated based on OBR per capita GDP projections |
+| `property_income` | gov.obr.per_capita.gdp | Uprated based on OBR per capita GDP projections |
+| `maintenance_income` | gov.obr.per_capita.gdp | Uprated based on OBR per capita GDP projections |
+| `student_payments` | Not uprated directly | Currently no specific uprating for student payments |
+| `free_school_meals` |gov.obr.consumer_price_index | Uprated based on CPI inflation |
+| `free_school_fruit_veg` | gov.obr.consumer_price_index | Uprated based on CPI inflation |
+| `free_school_milk` | gov.obr.consumer_price_index | Uprated based on CPI inflation |
+| `free_tv_licence_value` | Not directly uprated | Depends on policy parameters |
+| `income_tax` | Derived | Calculated based on income and tax policy |
+| `national_insurance` | Derived | Calculated based on income and NI policy |
+| `council_tax` | gov.obr.council_tax | Uprated based on OBR council tax revenue projections |
+| `domestic_rates` | gov.obr.council_tax | Uprated with council tax as proxy |
+| `employee_pension_contributions` | gov.obr.per_capita.employment_income | Uprated based on per capita employment income growth |
+| `personal_pension_contributions` | gov.obr.per_capita.employment_income | Uprated based on per capita employment income growth |
+| `maintenance_expenses` | gov.obr.consumer_price_index | Uprated based on CPI inflation |
+| `student_loan_repayments` | gov.obr.average_earnings | Uprated based on OBR average earnings projections |
+| `rent` | gov.obr.rent | Uprated based on OBR rent projections |
+| `water_and_sewerage_charges` | gov.obr.consumer_price_index | Uprated based on CPI as proxy |
+| `mortgage_interest_repayment` | gov.obr.mortgage_interest | Uprated based on OBR mortgage interest projections |
+| `housing_service_charges` | gov.obr.consumer_price_index | Uprated based on CPI as proxy |

policyengine_uk/data/uprating_growth_factors.csv

@@ -26,6 +26,7 @@ employment_income_before_lsr,gov.obr.per_capita.employment_income,0,0.072,0.074,
 esa_contrib_reported,gov.obr.consumer_price_index,0,0.039,0.101,0.057,0.023,0.032,0.02,0.02,0.02,0.02
 esa_income_reported,gov.obr.consumer_price_index,0,0.039,0.101,0.057,0.023,0.032,0.02,0.02,0.02,0.02
 food_and_non_alcoholic_beverages_consumption,gov.obr.consumer_price_index,0,0.039,0.101,0.057,0.023,0.032,0.02,0.02,0.02,0.02
+free_school_milk,gov.obr.consumer_price_index,0,0.039,0.101,0.057,0.023,0.032,0.02,0.02,0.02,0.02
 gross_financial_wealth,household.wealth.financial_assets,0,0.014,-0.108,0.004,0.03,0.032,0.034,0.034,0.036,0.0
 health_consumption,gov.obr.consumer_price_index,0,0.039,0.101,0.057,0.023,0.032,0.02,0.02,0.02,0.02
 household_furnishings_consumption,gov.obr.consumer_price_index,0,0.039,0.101,0.057,0.023,0.032,0.02,0.02,0.02,0.02
@@ -39,6 +40,7 @@ jsa_contrib_reported,gov.obr.consumer_price_index,0,0.039,0.101,0.057,0.023,0.03
 jsa_income_reported,gov.obr.consumer_price_index,0,0.039,0.101,0.057,0.023,0.032,0.02,0.02,0.02,0.02
 lump_sum_income,gov.obr.per_capita.gdp,0,0.125,0.092,0.05,0.038,0.028,0.028,0.031,0.033,0.033
 main_residence_value,household.wealth.financial_assets,0,0.014,-0.108,0.004,0.03,0.032,0.034,0.034,0.036,0.0
+maintenance_expenses,gov.obr.consumer_price_index,0,0.039,0.101,0.057,0.023,0.032,0.02,0.02,0.02,0.02
 maintenance_income,gov.obr.per_capita.gdp,0,0.125,0.092,0.05,0.038,0.028,0.028,0.031,0.033,0.033
 maternity_allowance_reported,gov.obr.consumer_price_index,0,0.039,0.101,0.057,0.023,0.032,0.02,0.02,0.02,0.02
 miscellaneous_consumption,gov.obr.consumer_price_index,0,0.039,0.101,0.057,0.023,0.032,0.02,0.02,0.02,0.02

policyengine_uk/variables/gov/dcms/bbc/tv_licence/free_tv_licence_value.py

@@ -0,0 +1,20 @@
+from policyengine_uk.model_api import *
+
+
+class free_tv_licence_value(Variable):
+    label = "free TV licence value"
+    entity = Household
+    definition_period = YEAR
+    value_type = float
+    unit = "/1"
+    reference = (
+        "https://www.legislation.gov.uk/ukpga/2003/21/section/365A",
+        "https://www.tvlicensing.co.uk/reducedfee",
+    )
+
+    def formula(household, period, parameters):
+        owns_tv = household("household_owns_tv", period)
+        discount = household("tv_licence_discount", period)
+        would_evade = household("would_evade_tv_licence_fee", period)
+        fee = parameters(period).gov.dcms.bbc.tv_licence.colour
+        return (owns_tv & ~would_evade) * fee * discount

policyengine_uk/variables/gov/dfe/free_school_milk.py

@@ -7,3 +7,4 @@ class free_school_milk(Variable):
     definition_period = YEAR
     value_type = float
     unit = GBP
+    uprating = "gov.obr.consumer_price_index"

policyengine_uk/variables/household/consumption/housing_costs.py

@@ -8,4 +8,4 @@ class housing_costs(Variable):
     definition_period = YEAR
     unit = GBP
 
-    adds = ["rent", "mortgage"]
+    adds = ["rent", "mortgage", "water_and_sewerage_charges"]

policyengine_uk/variables/household/income/hbai_benefits.py

@@ -0,0 +1,39 @@
+from policyengine_uk.model_api import *
+
+
+class hbai_benefits(Variable):
+    label = "HBAI-included benefits"
+    entity = Household
+    definition_period = YEAR
+    value_type = float
+    unit = GBP
+    adds = [
+        "child_benefit",
+        "esa_income",
+        "esa_contrib",
+        "housing_benefit",
+        "income_support",
+        "jsa_income",
+        "jsa_contrib",
+        "pension_credit",
+        "universal_credit",
+        "working_tax_credit",
+        "child_tax_credit",
+        "attendance_allowance",
+        "afcs",
+        "bsp",
+        "carers_allowance",
+        "dla",
+        "iidb",
+        "incapacity_benefit",
+        "pip",
+        "sda",
+        "state_pension",
+        "maternity_allowance",
+        "statutory_sick_pay",
+        "statutory_maternity_pay",
+        "ssmg",
+        "cost_of_living_support_payment",
+        "winter_fuel_allowance",
+        "tax_free_childcare",
+    ]

policyengine_uk/variables/household/income/hbai_household_net_income.py

@@ -21,48 +21,22 @@ class hbai_household_net_income(Variable):
         "private_pension_income",
         "private_transfer_income",
         "maintenance_income",
-        "child_benefit",
-        "esa_income",
-        "esa_contrib",
-        "housing_benefit",
-        "income_support",
-        "jsa_income",
-        "jsa_contrib",
-        "pension_credit",
-        "universal_credit",
-        "working_tax_credit",
-        "child_tax_credit",
-        "attendance_allowance",
-        "afcs",
-        "bsp",
-        "carers_allowance",
-        "dla",
-        "iidb",
-        "incapacity_benefit",
-        "jsa_contrib",
-        "pip",
-        "sda",
-        "state_pension",
-        "maternity_allowance",
-        "statutory_sick_pay",
-        "statutory_maternity_pay",
-        "ssmg",
-        "cost_of_living_support_payment",
-        "winter_fuel_allowance",
-        "tax_free_childcare",
+        "hbai_benefits",
         "free_school_meals",
         "free_school_fruit_veg",
         "free_school_milk",
-        "tv_licence_discount",
+        "free_tv_licence_value",
         # Reference for tax-free-childcare: https://assets.publishing.service.gov.uk/media/5e7b191886650c744175d08b/households-below-average-income-1994-1995-2018-2019.pdf
     ]
     subtracts = [
         "council_tax",
         "domestic_rates",
-        "wealth_tax",
         "income_tax",
         "national_insurance",
         "student_loan_repayments",
+        "employee_pension_contributions",
+        "personal_pension_contributions",
+        "maintenance_expenses",
     ]
 
 

policyengine_uk/variables/household/income/hbai_household_net_income_ahc.py

@@ -11,4 +11,8 @@ class hbai_household_net_income_ahc(Variable):
     unit = GBP
 
     adds = ["hbai_household_net_income"]
-    subtracts = ["housing_costs"]
+    subtracts = [
+        "rent",
+        "water_and_sewerage_charges",
+        "mortgage_interest_repayment",
+    ]