Add student loan interest rate parameters and variable

MaxGhenis · claude · MaxGhenis · commit 3b1aa99384f5 · 2025-11-29T19:48:30.000-05:00
Add parameters documenting student loan interest rate rules: - Plan 1: Lower of RPI or base rate + 1% - Plan 2: Income-contingent (RPI to RPI+3% based on income thresholds) - Plan 4: Same as Plan 1 - Plan 5: RPI only (no income-based component) - Postgraduate: RPI + 3% Add student_loan_interest_rate variable that calculates the applicable rate based on plan type and income, with Plan 2 tapering between the lower and upper income thresholds. Fixes #1417 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/policyengine_uk/parameters/gov/hmrc/student_loans/interest_rates/index.yaml b/policyengine_uk/parameters/gov/hmrc/student_loans/interest_rates/index.yaml
@@ -0,0 +1,12 @@
+description: Student loan interest rates
+label: Interest rates
+documentation: |
+  Interest rates applied to student loan balances vary by plan type.
+  Plan 2 has income-contingent rates that vary between RPI and RPI+3%.
+  Plan 5 and Plans 1/4 have simpler fixed rate structures.
+
+  Note: These parameters document the policy rules. Interest accrual
+  is not currently modelled in the microsimulation as it requires
+  tracking loan balances over time.
+
+  Reference: https://www.gov.uk/repaying-your-student-loan/interest
diff --git a/policyengine_uk/parameters/gov/hmrc/student_loans/interest_rates/plan_1.yaml b/policyengine_uk/parameters/gov/hmrc/student_loans/interest_rates/plan_1.yaml
@@ -0,0 +1,20 @@
+description: Plan 1 student loan interest rate
+metadata:
+  label: Plan 1 interest rate
+  unit: /1
+  period: year
+  reference:
+    - title: GOV.UK - Student loan interest rates
+      href: https://www.gov.uk/repaying-your-student-loan/interest
+  documentation: |
+    Interest rate for Plan 1 student loans.
+    Set at the lower of RPI or Bank of England base rate + 1%.
+    In practice, this is typically RPI when RPI is low.
+
+values:
+  2020-09-01: 0.012  # 1.2%
+  2021-09-01: 0.013  # 1.3%
+  2022-09-01: 0.051  # 5.1%
+  2023-09-01: 0.071  # 7.1%
+  2024-09-01: 0.072  # 7.2%
+  2025-09-01: 0.032  # 3.2%
diff --git a/policyengine_uk/parameters/gov/hmrc/student_loans/interest_rates/plan_2/additional_rate.yaml b/policyengine_uk/parameters/gov/hmrc/student_loans/interest_rates/plan_2/additional_rate.yaml
@@ -0,0 +1,23 @@
+description: Plan 2 maximum additional interest rate
+metadata:
+  label: Plan 2 additional rate
+  unit: /1
+  period: year
+  reference:
+    - title: GOV.UK - Student loan interest rates
+      href: https://www.gov.uk/repaying-your-student-loan/interest
+    - title: House of Commons Library - Student loans and interest rates FAQs
+      href: https://commonslibrary.parliament.uk/student-loans-and-interest-rates-faqs/
+  documentation: |
+    Maximum additional interest rate for Plan 2 student loans.
+    Added to the base rate for higher earners.
+
+    The actual additional rate is tapered between the lower and upper
+    income thresholds, from 0% at the lower threshold to this maximum
+    at the upper threshold.
+
+    For income at or above the upper threshold, the total rate is:
+    base_rate + additional_rate (i.e., RPI + 3%)
+
+values:
+  2012-09-01: 0.03  # 3%
diff --git a/policyengine_uk/parameters/gov/hmrc/student_loans/interest_rates/plan_2/base_rate.yaml b/policyengine_uk/parameters/gov/hmrc/student_loans/interest_rates/plan_2/base_rate.yaml
@@ -0,0 +1,20 @@
+description: Plan 2 base interest rate (RPI)
+metadata:
+  label: Plan 2 base rate
+  unit: /1
+  period: year
+  reference:
+    - title: GOV.UK - Student loan interest rates
+      href: https://www.gov.uk/repaying-your-student-loan/interest
+  documentation: |
+    Base interest rate for Plan 2 student loans (RPI).
+    This is the minimum rate applied to all Plan 2 borrowers.
+    Higher earners pay this plus an additional rate up to 3%.
+
+values:
+  2020-09-01: 0.026  # 2.6%
+  2021-09-01: 0.012  # 1.2%
+  2022-09-01: 0.051  # 5.1%
+  2023-09-01: 0.071  # 7.1%
+  2024-09-01: 0.072  # 7.2%
+  2025-09-01: 0.032  # 3.2%
diff --git a/policyengine_uk/parameters/gov/hmrc/student_loans/interest_rates/plan_2/index.yaml b/policyengine_uk/parameters/gov/hmrc/student_loans/interest_rates/plan_2/index.yaml
@@ -0,0 +1,16 @@
+description: Plan 2 student loan interest rates
+label: Plan 2 interest rates
+documentation: |
+  Plan 2 student loan interest rates are income-contingent after graduation.
+
+  While studying: RPI + 3%
+  After graduating:
+  - Income at or below lower threshold: RPI only
+  - Income between lower and upper threshold: RPI + tapered rate (0% to 3%)
+  - Income at or above upper threshold: RPI + 3%
+
+  This progressive structure means higher earners pay more interest,
+  though the actual repayment amount still depends on income, not the
+  loan balance or interest rate.
+
+  Reference: https://www.gov.uk/repaying-your-student-loan/interest
diff --git a/policyengine_uk/parameters/gov/hmrc/student_loans/interest_rates/plan_2/lower_threshold.yaml b/policyengine_uk/parameters/gov/hmrc/student_loans/interest_rates/plan_2/lower_threshold.yaml
@@ -0,0 +1,22 @@
+description: Plan 2 lower income threshold for interest rate tapering
+metadata:
+  label: Plan 2 interest lower threshold
+  unit: currency-GBP
+  period: year
+  reference:
+    - title: GOV.UK - Student loan interest rates
+      href: https://www.gov.uk/repaying-your-student-loan/interest
+  documentation: |
+    Lower income threshold for Plan 2 interest rate tapering.
+    Below this income, borrowers pay the base rate (RPI) only.
+    Above this, the additional rate begins to taper in.
+
+    Note: This is the same as the Plan 2 repayment threshold.
+
+values:
+  2020-09-01: 26575
+  2021-09-01: 27295
+  2022-09-01: 27295
+  2023-09-01: 27660
+  2024-09-01: 27660
+  2025-09-01: 28470
diff --git a/policyengine_uk/parameters/gov/hmrc/student_loans/interest_rates/plan_2/upper_threshold.yaml b/policyengine_uk/parameters/gov/hmrc/student_loans/interest_rates/plan_2/upper_threshold.yaml
@@ -0,0 +1,20 @@
+description: Plan 2 upper income threshold for interest rate tapering
+metadata:
+  label: Plan 2 interest upper threshold
+  unit: currency-GBP
+  period: year
+  reference:
+    - title: GOV.UK - Student loan interest rates
+      href: https://www.gov.uk/repaying-your-student-loan/interest
+  documentation: |
+    Upper income threshold for Plan 2 interest rate tapering.
+    Above this income, borrowers pay the maximum rate (RPI + 3%).
+    Between the lower and upper thresholds, the rate is tapered.
+
+values:
+  2020-09-01: 47835
+  2021-09-01: 49130
+  2022-09-01: 49130
+  2023-09-01: 49585
+  2024-09-01: 49585
+  2025-09-01: 51245
diff --git a/policyengine_uk/parameters/gov/hmrc/student_loans/interest_rates/plan_4.yaml b/policyengine_uk/parameters/gov/hmrc/student_loans/interest_rates/plan_4.yaml
@@ -0,0 +1,20 @@
+description: Plan 4 student loan interest rate
+metadata:
+  label: Plan 4 interest rate
+  unit: /1
+  period: year
+  reference:
+    - title: GOV.UK - Student loan interest rates
+      href: https://www.gov.uk/repaying-your-student-loan/interest
+  documentation: |
+    Interest rate for Plan 4 student loans (Scotland).
+    Set at the lower of RPI or Bank of England base rate + 1%.
+    Same rate as Plan 1.
+
+values:
+  2020-09-01: 0.012  # 1.2%
+  2021-09-01: 0.013  # 1.3%
+  2022-09-01: 0.051  # 5.1%
+  2023-09-01: 0.071  # 7.1%
+  2024-09-01: 0.072  # 7.2%
+  2025-09-01: 0.032  # 3.2%
diff --git a/policyengine_uk/parameters/gov/hmrc/student_loans/interest_rates/plan_5.yaml b/policyengine_uk/parameters/gov/hmrc/student_loans/interest_rates/plan_5.yaml
@@ -0,0 +1,19 @@
+description: Plan 5 student loan interest rate
+metadata:
+  label: Plan 5 interest rate
+  unit: /1
+  period: year
+  reference:
+    - title: GOV.UK - Student loan interest rates
+      href: https://www.gov.uk/repaying-your-student-loan/interest
+    - title: House of Commons Library - Student loans and interest rates FAQs
+      href: https://commonslibrary.parliament.uk/student-loans-and-interest-rates-faqs/
+  documentation: |
+    Interest rate for Plan 5 student loans (from September 2023).
+    Set at RPI only - no additional percentage based on income.
+    This is simpler than Plan 2 which has income-contingent rates.
+
+values:
+  2023-09-01: 0.071  # 7.1%
+  2024-09-01: 0.072  # 7.2%
+  2025-09-01: 0.032  # 3.2%
diff --git a/policyengine_uk/parameters/gov/hmrc/student_loans/interest_rates/postgraduate.yaml b/policyengine_uk/parameters/gov/hmrc/student_loans/interest_rates/postgraduate.yaml
@@ -0,0 +1,19 @@
+description: Postgraduate loan interest rate
+metadata:
+  label: Postgraduate loan interest rate
+  unit: /1
+  period: year
+  reference:
+    - title: GOV.UK - Student loan interest rates
+      href: https://www.gov.uk/repaying-your-student-loan/interest
+  documentation: |
+    Interest rate for Postgraduate loans.
+    Set at RPI + 3%.
+
+values:
+  2020-09-01: 0.056  # 5.6%
+  2021-09-01: 0.042  # 4.2%
+  2022-09-01: 0.081  # 8.1%
+  2023-09-01: 0.101  # 10.1%
+  2024-09-01: 0.102  # 10.2%
+  2025-09-01: 0.062  # 6.2%
diff --git a/policyengine_uk/tests/policy/baseline/gov/hmrc/student_loans/test_interest_rates.py b/policyengine_uk/tests/policy/baseline/gov/hmrc/student_loans/test_interest_rates.py
@@ -0,0 +1,123 @@
+"""Tests for student loan interest rate variable.
+
+Tests the student_loan_interest_rate variable which calculates the
+applicable interest rate based on plan type and income.
+"""
+
+import pytest
+from policyengine_uk import Simulation
+
+
+class TestStudentLoanInterestRateVariable:
+    """Test the student_loan_interest_rate variable formula."""
+
+    def test_plan_1_rate(self):
+        """Plan 1 should use the fixed Plan 1 rate."""
+        sim = Simulation(
+            situation={
+                "people": {
+                    "person": {
+                        "student_loan_plan": {"2026": "PLAN_1"},
+                        "adjusted_net_income": {"2026": 40000},
+                    }
+                }
+            }
+        )
+        rate = sim.calculate("student_loan_interest_rate", 2026)
+        assert rate[0] == pytest.approx(0.032, abs=0.001)
+
+    def test_plan_2_low_income(self):
+        """Plan 2 below lower threshold should get base rate only."""
+        sim = Simulation(
+            situation={
+                "people": {
+                    "person": {
+                        "student_loan_plan": {"2026": "PLAN_2"},
+                        "adjusted_net_income": {"2026": 25000},
+                    }
+                }
+            }
+        )
+        rate = sim.calculate("student_loan_interest_rate", 2026)
+        # Base rate only (3.2%)
+        assert rate[0] == pytest.approx(0.032, abs=0.001)
+
+    def test_plan_2_high_income(self):
+        """Plan 2 above upper threshold should get base + full additional."""
+        sim = Simulation(
+            situation={
+                "people": {
+                    "person": {
+                        "student_loan_plan": {"2026": "PLAN_2"},
+                        "adjusted_net_income": {"2026": 60000},
+                    }
+                }
+            }
+        )
+        rate = sim.calculate("student_loan_interest_rate", 2026)
+        # Base (3.2%) + additional (3%) = 6.2%
+        assert rate[0] == pytest.approx(0.062, abs=0.001)
+
+    def test_plan_2_mid_income(self):
+        """Plan 2 between thresholds should get tapered rate."""
+        # Lower threshold: £28,470, Upper threshold: £51,245
+        # Midpoint income: (28470 + 51245) / 2 = 39857.5
+        sim = Simulation(
+            situation={
+                "people": {
+                    "person": {
+                        "student_loan_plan": {"2026": "PLAN_2"},
+                        "adjusted_net_income": {"2026": 39857.5},
+                    }
+                }
+            }
+        )
+        rate = sim.calculate("student_loan_interest_rate", 2026)
+        # Base (3.2%) + half of additional (1.5%) = 4.7%
+        assert rate[0] == pytest.approx(0.047, abs=0.001)
+
+    def test_plan_4_rate(self):
+        """Plan 4 should use the fixed Plan 4 rate (same as Plan 1)."""
+        sim = Simulation(
+            situation={
+                "people": {
+                    "person": {
+                        "student_loan_plan": {"2026": "PLAN_4"},
+                        "adjusted_net_income": {"2026": 40000},
+                    }
+                }
+            }
+        )
+        rate = sim.calculate("student_loan_interest_rate", 2026)
+        assert rate[0] == pytest.approx(0.032, abs=0.001)
+
+    def test_plan_5_rate(self):
+        """Plan 5 should use RPI only (no income-based component)."""
+        sim = Simulation(
+            situation={
+                "people": {
+                    "person": {
+                        "student_loan_plan": {"2026": "PLAN_5"},
+                        "adjusted_net_income": {"2026": 60000},
+                    }
+                }
+            }
+        )
+        rate = sim.calculate("student_loan_interest_rate", 2026)
+        # RPI only (3.2%) regardless of income
+        assert rate[0] == pytest.approx(0.032, abs=0.001)
+
+    def test_no_loan_zero_rate(self):
+        """No student loan should return zero rate."""
+        sim = Simulation(
+            situation={
+                "people": {
+                    "person": {
+                        "student_loan_plan": {"2026": "NONE"},
+                        "adjusted_net_income": {"2026": 50000},
+                    }
+                }
+            }
+        )
+        rate = sim.calculate("student_loan_interest_rate", 2026)
+        assert rate[0] == 0
diff --git a/policyengine_uk/variables/gov/hmrc/student_loans/student_loan_repayment.py b/policyengine_uk/variables/gov/hmrc/student_loans/student_loan_repayment.py
@@ -53,3 +53,56 @@ class has_student_loan(Variable):
     def formula(person, period, parameters):
         plan = person("student_loan_plan", period)
         return plan != StudentLoanPlan.NONE
+
+
+class student_loan_interest_rate(Variable):
+    value_type = float
+    entity = Person
+    label = "Student loan interest rate"
+    documentation = (
+        "Annual interest rate on student loan balance. "
+        "Plan 2 has income-contingent rates (RPI to RPI+3%). "
+        "Plans 1, 4, 5 and Postgraduate have fixed rates."
+    )
+    definition_period = YEAR
+    unit = "/1"
+
+    def formula(person, period, parameters):
+        plan = person("student_loan_plan", period)
+        income = person("adjusted_net_income", period)
+        interest = parameters(period).gov.hmrc.student_loans.interest_rates
+
+        # Plan 2 has income-contingent rates
+        plan_2_base = interest.plan_2.base_rate
+        plan_2_additional = interest.plan_2.additional_rate
+        plan_2_lower = interest.plan_2.lower_threshold
+        plan_2_upper = interest.plan_2.upper_threshold
+
+        # Calculate Plan 2 tapered rate
+        # Below lower threshold: base rate only
+        # Above upper threshold: base + full additional
+        # Between: linear taper
+        taper_fraction = np.clip(
+            (income - plan_2_lower) / (plan_2_upper - plan_2_lower), 0, 1
+        )
+        plan_2_rate = plan_2_base + (plan_2_additional * taper_fraction)
+
+        # Select rate based on plan type
+        rate = select(
+            [
+                plan == StudentLoanPlan.PLAN_1,
+                plan == StudentLoanPlan.PLAN_2,
+                plan == StudentLoanPlan.PLAN_4,
+                plan == StudentLoanPlan.PLAN_5,
+                # Postgraduate loans would need a separate plan type
+            ],
+            [
+                interest.plan_1,
+                plan_2_rate,
+                interest.plan_4,
+                interest.plan_5,
+            ],
+            default=0,
+        )
+
+        return rate
diff --git a/uv.lock b/uv.lock
