Add net_wealth variable and mortgage_debt / consumer_debt inputs

changelog.d/net-wealth.added.md

@@ -0,0 +1 @@
+Added `net_wealth` (total wealth net of mortgage, consumer, and student loan debt) and the `mortgage_debt` and `consumer_debt` household inputs. Unlike gross `total_wealth`, net wealth can be negative when a household's debts exceed its assets.

policyengine_uk/tests/policy/baseline/household/wealth/net_wealth.yaml

@@ -0,0 +1,27 @@
+- name: Net wealth subtracts mortgage, consumer and student-loan debt
+  period: 2026
+  absolute_error_margin: 1
+  input:
+    total_wealth: 500_000
+    mortgage_debt: 200_000
+    consumer_debt: 10_000
+    student_loan_balance: 15_000
+  output:
+    net_wealth: 275_000
+
+- name: Net wealth is negative when debts exceed assets
+  period: 2026
+  absolute_error_margin: 1
+  input:
+    total_wealth: 50_000
+    mortgage_debt: 120_000
+  output:
+    net_wealth: -70_000
+
+- name: Net wealth equals total wealth with no debt
+  period: 2026
+  absolute_error_margin: 1
+  input:
+    total_wealth: 300_000
+  output:
+    net_wealth: 300_000

policyengine_uk/variables/household/wealth/net_wealth.py

@@ -0,0 +1,22 @@
+from policyengine_uk.model_api import *
+
+
+class net_wealth(Variable):
+    label = "Net wealth"
+    documentation = (
+        "Total wealth less mortgage, consumer, and student loan debt. Unlike "
+        "total_wealth (gross assets), net wealth can be negative when a "
+        "household's debts exceed its assets."
+    )
+    entity = Household
+    definition_period = YEAR
+    value_type = float
+    unit = GBP
+    quantity_type = STOCK
+
+    def formula(household, period, parameters):
+        total_wealth = household("total_wealth", period)
+        mortgage_debt = household("mortgage_debt", period)
+        consumer_debt = household("consumer_debt", period)
+        student_loan_debt = add(household, period, ["student_loan_balance"])
+        return total_wealth - mortgage_debt - consumer_debt - student_loan_debt

policyengine_uk/variables/input/consumer_debt.py

@@ -0,0 +1,13 @@
+from policyengine_uk.model_api import *
+
+
+class consumer_debt(Variable):
+    label = "consumer debt"
+    documentation = "Outstanding non-mortgage, non-student-loan borrowing (personal loans, credit, hire purchase), imputed from the Wealth and Assets Survey"
+    entity = Household
+    definition_period = YEAR
+    value_type = float
+    unit = GBP
+    uprating = "gov.economic_assumptions.indices.obr.per_capita.gdp"
+    quantity_type = STOCK
+    default_value = 0

policyengine_uk/variables/input/mortgage_debt.py

@@ -0,0 +1,13 @@
+from policyengine_uk.model_api import *
+
+
+class mortgage_debt(Variable):
+    label = "mortgage debt"
+    documentation = "Outstanding debt secured on UK land or property (mortgages and secured loans), imputed from the Wealth and Assets Survey"
+    entity = Household
+    definition_period = YEAR
+    value_type = float
+    unit = GBP
+    uprating = "gov.economic_assumptions.indices.obr.per_capita.gdp"
+    quantity_type = STOCK
+    default_value = 0