Model balance-aware student loan repayments

changelog.d/student-loan-balance-aware-repayments.fixed.md

@@ -0,0 +1 @@
+Use modelled student loan repayments in aggregates and cap them by outstanding balance when available.

policyengine_uk/tests/policy/baseline/gov/hmrc/student_loans/student_loan_repayment.yaml

@@ -128,3 +128,34 @@
         student_loan_plan: PLAN_2
   output:
     student_loan_repayment: 0
+
+- name: Student loan repayment is capped by outstanding balance
+  period: 2025
+  input:
+    people:
+      person:
+        employment_income: 40_000
+        student_loan_plan: PLAN_2
+        student_loan_balance: 500
+  output:
+    student_loan_repayment: 500
+    student_loan_repayments: 500
+
+- name: Student loan repayments default to the modelled formula in HBAI income
+  period: 2025
+  input:
+    people:
+      person:
+        employment_income: 40_000
+        student_loan_plan: PLAN_2
+        student_loan_balance: 500
+        income_tax: 0
+        national_insurance: 0
+    households:
+      household:
+        members: person
+        council_tax: 0
+        domestic_rates: 0
+  output:
+    student_loan_repayments: 500
+    hbai_household_net_income: 39_500

policyengine_uk/variables/gov/hmrc/student_loan_repayments.py

@@ -7,4 +7,6 @@ class student_loan_repayments(Variable):
     definition_period = YEAR
     value_type = float
     unit = GBP
-    uprating = "gov.economic_assumptions.indices.obr.average_earnings"
+
+    def formula(person, period, parameters):
+        return person("student_loan_repayment", period)

policyengine_uk/variables/gov/hmrc/student_loans/__init__.py

@@ -1,2 +1,3 @@
+from policyengine_uk.variables.gov.hmrc.student_loans.student_loan_balance import *
 from policyengine_uk.variables.gov.hmrc.student_loans.student_loan_plan import *
 from policyengine_uk.variables.gov.hmrc.student_loans.student_loan_repayment import *

policyengine_uk/variables/gov/hmrc/student_loans/student_loan_balance.py

@@ -0,0 +1,14 @@
+from policyengine_uk.model_api import *
+
+
+class student_loan_balance(Variable):
+    value_type = float
+    entity = Person
+    label = "Student loan balance"
+    documentation = (
+        "Outstanding student loan balance. "
+        "When not provided, repayments are left uncapped."
+    )
+    definition_period = YEAR
+    unit = GBP
+    default_value = 0

policyengine_uk/variables/gov/hmrc/student_loans/student_loan_repayment.py

@@ -11,14 +11,16 @@ class student_loan_repayment(Variable):
     documentation = (
         "Annual student loan repayment calculated from income and plan type. "
         "Repayments are 9% of income above threshold for Plans 1/2/4/5, "
-        "and 6% for Postgraduate loans."
+        "and 6% for Postgraduate loans, capped by the outstanding balance "
+        "when that balance is available."
     )
     definition_period = YEAR
     unit = GBP
 
     def formula(person, period, parameters):
         plan = person("student_loan_plan", period)
         income = person("adjusted_net_income", period)
+        balance = max_(0, person("student_loan_balance", period))
         p = parameters(period).gov.hmrc.student_loans
 
         # Get threshold based on plan type
@@ -41,7 +43,8 @@ def formula(person, period, parameters):
         )
 
         rate = person("student_loan_repayment_rate", period)
-        return rate * max_(0, income - threshold)
+        uncapped_repayment = rate * max_(0, income - threshold)
+        return where(balance > 0, min_(uncapped_repayment, balance), uncapped_repayment)
 
 
 class has_student_loan(Variable):