Merge origin/main into targets-registry

Resolve conflict in utils/loss.py (keep registry delegation).
Incorporate salary sacrifice headcount targets from PR #268 into
the structured registry (obr.py, compute/income.py, build_loss_matrix.py).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: vahid-ahmadi

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), 
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.37.0] - 2026-02-16 10:16:06
+
+### Added
+
+- Calibrate salary sacrifice population to HMRC/ASHE headcount targets (7.7mn total, 3.3mn above 2k cap, 4.3mn below 2k cap). Two-stage imputation in salary_sacrifice.py converts pension contributors to below-cap SS users, and three new headcount calibration targets in loss.py.
+
 ## [1.36.2] - 2026-01-21 19:06:42
 
 ### Fixed
@@ -592,6 +598,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 
 
+[1.37.0]: https://github.com/PolicyEngine/policyengine-us-data/compare/1.36.2...1.37.0
 [1.36.2]: https://github.com/PolicyEngine/policyengine-us-data/compare/1.36.1...1.36.2
 [1.36.1]: https://github.com/PolicyEngine/policyengine-us-data/compare/1.36.0...1.36.1
 [1.36.0]: https://github.com/PolicyEngine/policyengine-us-data/compare/1.35.1...1.36.0

changelog.yaml

@@ -517,3 +517,11 @@
     - Use region.values for Scotland comparisons in loss function to ensure consistent
       behavior with StringArray types
   date: 2026-01-21 19:06:42
+- bump: minor
+  changes:
+    added:
+    - Calibrate salary sacrifice population to HMRC/ASHE headcount targets (7.7mn
+      total, 3.3mn above 2k cap, 4.3mn below 2k cap). Two-stage imputation in salary_sacrifice.py
+      converts pension contributors to below-cap SS users, and three new headcount
+      calibration targets in loss.py.
+  date: 2026-02-16 10:16:06

policyengine_uk_data/datasets/imputations/salary_sacrifice.py

@@ -1,20 +1,19 @@
 """
 Salary sacrifice imputation for pension contributions.
 
-This module imputes salary sacrifice pension amounts using QRF trained on
-FRS respondents who were asked the SALSAC question. The model predicts
-the continuous amount (pension_contributions_via_salary_sacrifice), with
-non-participants naturally having 0.
+Two-stage imputation:
 
-Training data (FRS 2023-24):
-- SALSAC='1' (Yes): ~224 jobs with reported SPNAMT amounts
-- SALSAC='2' (No): ~3,803 jobs with SPNAMT=0
+1. QRF trained on FRS respondents who were asked SALSAC (~224 yes,
+   ~3,803 no). Predicts SS amounts for ~13,265 jobs where SALSAC was
+   not asked.
 
-Imputation candidates:
-- SALSAC=' ' (skip/not asked): ~13,265 jobs
+2. Headcount-targeted imputation: converts a fraction of pension
+   contributors without SS into below-cap (≤£2,000) SS users, moving
+   employee pension contributions to salary sacrifice. Targets the
+   OBR/ASHE estimate of ~4.3mn below-cap SS users.
 
-Targeting to HMRC totals (~24bn SS contributions) happens via weight
-calibration, not in this imputation step.
+Exact monetary totals (~£24bn SS contributions) and final headcount
+calibration happen via weight optimisation in a subsequent step.
 """
 
 import pandas as pd
@@ -124,13 +123,10 @@ def impute_salary_sacrifice(
     """
     Impute salary sacrifice pension amounts for FRS non-respondents.
 
-    For respondents not asked about salary sacrifice (SALSAC=' '), uses
-    a QRF model trained on those who were asked to predict the SS pension
-    contribution amount directly. The model naturally predicts 0 for
-    non-participants and positive amounts for likely participants.
-
-    Note: This imputation does NOT target any specific total. Targeting
-    to HMRC figures happens via weight calibration in a subsequent step.
+    Stage 1: QRF predicts SS amounts for respondents not asked SALSAC.
+    Stage 2: Converts a fraction of pension contributors to below-cap
+    SS users, targeting ~4.3mn (OBR/ASHE). Moves employee pension
+    contributions to salary sacrifice to keep total pension consistent.
 
     Args:
         dataset: PolicyEngine UK dataset with salary_sacrifice_asked
@@ -183,7 +179,46 @@ def impute_salary_sacrifice(
         imputed_ss,  # Use imputed for non-respondents
     )
 
-    # Update dataset
+    # Stage 2: Headcount-targeted imputation for below-cap SS users.
+    # ASHE data shows many more SS users than the FRS captures due to
+    # self-reporting bias in auto-enrolment. Impute additional SS users
+    # from pension contributors to create enough records for calibration
+    # to hit OBR headcount targets (7.7mn total, 4.3mn below £2,000).
+    person_weight = sim.calculate("person_weight").values
+    employee_pension = dataset.person[
+        "employee_pension_contributions"
+    ].values.copy()
+    has_ss = final_ss > 0
+    below_cap_ss = has_ss & (final_ss <= 2000)
+
+    # Donor pool: employed pension contributors not already SS users
+    is_donor = (employee_pension > 0) & ~has_ss & (employment_income > 0)
+
+    # Target ~4.3mn below-cap SS users (HMRC/ASHE estimate)
+    TARGET_BELOW_CAP = 4_300_000
+    current_below_cap = (person_weight * below_cap_ss).sum()
+    shortfall = max(0, TARGET_BELOW_CAP - current_below_cap)
+
+    if shortfall > 0:
+        donor_weighted = (person_weight * is_donor).sum()
+        if donor_weighted > 0:
+            imputation_rate = min(0.8, shortfall / donor_weighted)
+            rng = np.random.default_rng(seed=2024)
+            newly_imputed = is_donor & (
+                rng.random(len(final_ss)) < imputation_rate
+            )
+
+            # Move up to £2,000 of employee pension to SS
+            ss_new = np.minimum(employee_pension, 2000.0)
+            final_ss = np.where(newly_imputed, ss_new, final_ss)
+
+            # Reduce employee pension correspondingly
+            dataset.person["employee_pension_contributions"] = np.where(
+                newly_imputed,
+                employee_pension - ss_new,
+                employee_pension,
+            )
+
     dataset.person["pension_contributions_via_salary_sacrifice"] = final_ss
 
     return dataset

policyengine_uk_data/targets/build_loss_matrix.py

@@ -38,6 +38,7 @@
     compute_scotland_uc_child,
     compute_scottish_child_payment,
     compute_ss_contributions,
+    compute_ss_headcount,
     compute_ss_it_relief,
     compute_ss_ni_relief,
     compute_tenure,
@@ -341,6 +342,10 @@ def _compute_column(
     if name == "hmrc/salary_sacrifice_contributions":
         return compute_ss_contributions(target, ctx)
 
+    # Salary sacrifice headcount
+    if name.startswith("obr/salary_sacrifice_users_"):
+        return compute_ss_headcount(target, ctx)
+
     # Salary sacrifice NI relief
     if name in (
         "hmrc/salary_sacrifice_employee_nics_relief",

policyengine_uk_data/targets/compute/__init__.py

@@ -29,6 +29,7 @@
     compute_esa,
     compute_income_band,
     compute_ss_contributions,
+    compute_ss_headcount,
     compute_ss_it_relief,
     compute_ss_ni_relief,
 )
@@ -55,6 +56,7 @@
     "compute_scotland_uc_child",
     "compute_scottish_child_payment",
     "compute_ss_contributions",
+    "compute_ss_headcount",
     "compute_ss_it_relief",
     "compute_ss_ni_relief",
     "compute_tenure",

policyengine_uk_data/targets/compute/income.py

@@ -74,6 +74,19 @@ def compute_ss_ni_relief(target, ctx) -> np.ndarray:
     return ctx.household_from_person(ni_cf - ni_base)
 
 
+def compute_ss_headcount(target, ctx) -> np.ndarray:
+    """Compute salary sacrifice user headcounts."""
+    ss = ctx.sim.calculate("pension_contributions_via_salary_sacrifice")
+    name = target.name
+    if "below_cap" in name:
+        mask = (ss > 0) & (ss <= 2000)
+    elif "above_cap" in name:
+        mask = ss > 2000
+    else:
+        mask = ss > 0
+    return ctx.household_from_person(mask)
+
+
 def compute_esa(target, ctx) -> np.ndarray:
     """Compute ESA (combined income-related + contributory)."""
     return ctx.household_from_person(

policyengine_uk_data/targets/sources/obr.py

@@ -434,6 +434,22 @@ def _parse_tv_licence(wb: openpyxl.Workbook) -> list[Target]:
     y: 2.9e9 * 1.03 ** max(0, y - 2024) for y in range(2024, 2032)
 }
 
+# Salary sacrifice headcount: 7.7m total (3.3m above £2k, 4.3m below)
+# OBR para 1.7: SS population grows 0.9% faster than employees (~2.4%/yr)
+_SS_HEADCOUNT_GROWTH = 1.024
+_SS_TOTAL_USERS = {
+    y: 7_700_000 * _SS_HEADCOUNT_GROWTH ** max(0, y - 2024)
+    for y in range(2024, 2032)
+}
+_SS_BELOW_CAP_USERS = {
+    y: 4_300_000 * _SS_HEADCOUNT_GROWTH ** max(0, y - 2024)
+    for y in range(2024, 2032)
+}
+_SS_ABOVE_CAP_USERS = {
+    y: 3_300_000 * _SS_HEADCOUNT_GROWTH ** max(0, y - 2024)
+    for y in range(2024, 2032)
+}
+
 
 def get_targets() -> list[Target]:
     config = load_config()
@@ -487,4 +503,44 @@ def get_targets() -> list[Target]:
         )
     )
 
+    # Salary sacrifice headcount targets
+    _SS_REF = (
+        "https://www.gov.uk/government/publications/"
+        "salary-sacrifice-reform-for-pension-contributions"
+        "-effective-from-6-april-2029"
+    )
+    targets.append(
+        Target(
+            name="obr/salary_sacrifice_users_total",
+            variable="pension_contributions_via_salary_sacrifice",
+            source="obr",
+            unit=Unit.COUNT,
+            values=_SS_TOTAL_USERS,
+            is_count=True,
+            reference_url=_SS_REF,
+        )
+    )
+    targets.append(
+        Target(
+            name="obr/salary_sacrifice_users_below_cap",
+            variable="pension_contributions_via_salary_sacrifice",
+            source="obr",
+            unit=Unit.COUNT,
+            values=_SS_BELOW_CAP_USERS,
+            is_count=True,
+            reference_url=_SS_REF,
+        )
+    )
+    targets.append(
+        Target(
+            name="obr/salary_sacrifice_users_above_cap",
+            variable="pension_contributions_via_salary_sacrifice",
+            source="obr",
+            unit=Unit.COUNT,
+            values=_SS_ABOVE_CAP_USERS,
+            is_count=True,
+            reference_url=_SS_REF,
+        )
+    )
+
     return targets

policyengine_uk_data/tests/test_salary_sacrifice_headcount.py

@@ -0,0 +1,81 @@
+"""Test salary sacrifice headcount calibration targets.
+
+Source: HMRC, "Salary sacrifice reform for pension contributions"
+https://www.gov.uk/government/publications/salary-sacrifice-reform-for-pension-contributions-effective-from-6-april-2029
+7.7mn total SS users (3.3mn above 2k cap, 4.3mn below 2k cap)
+"""
+
+import pytest
+
+TOLERANCE = 0.15  # 15% relative tolerance
+
+
+@pytest.mark.xfail(
+    reason="Will pass after recalibration with new headcount targets"
+)
+def test_salary_sacrifice_total_users(baseline):
+    """Test that total SS user count is close to 7.7mn."""
+    ss = baseline.calculate(
+        "pension_contributions_via_salary_sacrifice",
+        map_to="person",
+        period=2025,
+    )
+    person_weight = baseline.calculate(
+        "person_weight", map_to="person", period=2025
+    ).values
+
+    total_users = (person_weight * (ss.values > 0)).sum()
+    TARGET = 7_700_000
+
+    assert abs(total_users / TARGET - 1) < TOLERANCE, (
+        f"Expected ~{TARGET/1e6:.1f}mn SS users, "
+        f"got {total_users/1e6:.1f}mn ({total_users/TARGET*100:.0f}% of target)"
+    )
+
+
+@pytest.mark.xfail(
+    reason="Will pass after recalibration with new headcount targets"
+)
+def test_salary_sacrifice_below_cap_users(baseline):
+    """Test that below-cap (<=2k) SS users are close to 4.3mn."""
+    ss = baseline.calculate(
+        "pension_contributions_via_salary_sacrifice",
+        map_to="person",
+        period=2025,
+    )
+    person_weight = baseline.calculate(
+        "person_weight", map_to="person", period=2025
+    ).values
+
+    below_cap = (ss.values > 0) & (ss.values <= 2000)
+    total_below_cap = (person_weight * below_cap).sum()
+    TARGET = 4_300_000
+
+    assert abs(total_below_cap / TARGET - 1) < TOLERANCE, (
+        f"Expected ~{TARGET/1e6:.1f}mn below-cap SS users, "
+        f"got {total_below_cap/1e6:.1f}mn ({total_below_cap/TARGET*100:.0f}% of target)"
+    )
+
+
+@pytest.mark.xfail(
+    reason="Will pass after recalibration with new headcount targets"
+)
+def test_salary_sacrifice_above_cap_users(baseline):
+    """Test that above-cap (>2k) SS users are close to 3.3mn."""
+    ss = baseline.calculate(
+        "pension_contributions_via_salary_sacrifice",
+        map_to="person",
+        period=2025,
+    )
+    person_weight = baseline.calculate(
+        "person_weight", map_to="person", period=2025
+    ).values
+
+    above_cap = ss.values > 2000
+    total_above_cap = (person_weight * above_cap).sum()
+    TARGET = 3_300_000
+
+    assert abs(total_above_cap / TARGET - 1) < TOLERANCE, (
+        f"Expected ~{TARGET/1e6:.1f}mn above-cap SS users, "
+        f"got {total_above_cap/1e6:.1f}mn ({total_above_cap/TARGET*100:.0f}% of target)"
+    )

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "policyengine_uk_data"
-version = "1.36.2"
+version = "1.37.0"
 description = "A package to create representative microdata for the UK."
 readme = "README.md"
 authors = [