PolicyEngine-UK 2.131.0__tar.gz → 2.131.2__tar.gz

{policyengine_uk-2.131.0 → policyengine_uk-2.131.2}/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [2.131.2] - 2026-10-14
+
+### Fixed
+
+- - Fixed HBAI household income after housing costs to deduct ground rent and housing service charges, so equivalised AHC income and poverty measures include these costs.
+
+
+## [2.131.1] - 2026-10-14
+
+### Fixed
+
+- A bare-year reform key, or a key dated 1 January, on the economic growth rates, the indices built from them and the household parameters now names that calendar year. A bare year used to name the fiscal year from 6 April, which moved the next year: a 2027 earnings growth rate showed as 2027's but moved the 2028 index and the April 2029 triple lock. A 1 January key used to override that one day after processing, which nothing built from the parameter read. A change to an uprated household parameter past its last stated value now leaves the years around it on their projected path instead of freezing them. Reforms to series built during processing (the triple lock rate, the indices, the lagged series) now uprate what is built from them. Deprecated `labor_supply_responses` paths in reform dicts reach the parameters formulas read, and changes to a parameter given by both its path and its alias are merged in order instead of one being silently dropped.
+
+
 ## [2.131.0] - 2026-10-14
 
 ### Added

{policyengine_uk-2.131.0 → policyengine_uk-2.131.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: policyengine-uk
-Version: 2.131.0
+Version: 2.131.2
 Summary: PolicyEngine tax and benefit system for the UK.
 Project-URL: Homepage, https://github.com/PolicyEngine/policyengine-uk
 Project-URL: Repository, https://github.com/PolicyEngine/policyengine-uk

{policyengine_uk-2.131.0 → policyengine_uk-2.131.2}/policyengine_uk/parameters/gov/economic_assumptions/create_economic_assumption_indices.py

@@ -10,9 +10,11 @@ def create_economic_assumption_indices(
 ) -> ParameterNode:
     econ_assumptions: ParameterNode = parameters.gov.economic_assumptions
     yoy_growth: ParameterNode = econ_assumptions.yoy_growth
+    # Index levels dated 1 January, one per calendar year, so a bare-year
+    # reform key names the calendar year (policyengine_uk.utils.dated_reforms).
     indices = ParameterNode(
         name="gov.economic_assumptions.indices",
-        data={},
+        data={"metadata": {"calendar_year_series": True}},
     )
     econ_assumptions.add_child(
         "indices",

{policyengine_uk-2.131.0 → policyengine_uk-2.131.2}/policyengine_uk/parameters/gov/economic_assumptions/yoy_growth.yaml

@@ -33,6 +33,12 @@
 #   https://obr.uk/box/the-long-run-difference-between-rpi-and-cpi-inflation/
 #   https://www.bankofengland.co.uk/monetary-policy/inflation
 
+metadata:
+  # Each value is the growth over a calendar year, dated 1 January, and
+  # processing reads it there, so a bare-year reform key names the calendar
+  # year (policyengine_uk/utils/dated_reforms.py).
+  calendar_year_series: true
+
 obr:
   rpi:
     description: Retail price index year-on-year growth.

{policyengine_uk-2.131.0 → policyengine_uk-2.131.2}/policyengine_uk/parameters/gov/hmrc/create_threshold_indexation.py

@@ -65,13 +65,17 @@ including a scenario's overrides, keep their own dates, so that copy read at
 parameters carry no ``uprating`` metadata, so core uprating does not extend
 them.
 
-The values are computed when the parameters are processed. A reform passed as
-a dict edits the processed parameters, so changing one of these parameters
-does not move the others. A scenario whose ``parameter_changes`` edit the raw
-parameters, or a simulation modifier that resets and reprocesses them (as
-``no_economic_assumptions`` does), rebuilds the values. So a changed CPI
-forecast moves all seven, and a raw edit to the personal allowance or basic
-rate limit after 2030-31 also moves the aligned NICs thresholds.
+The values are computed when the parameters are processed. Every reform route
+(a reform dict, ``parameter_changes``, ``Reform.from_dict``) writes its changes
+onto the parameters before they are processed, as does a simulation modifier
+that resets and reprocesses them (as ``no_economic_assumptions`` does), so the
+values are rebuilt with the change: a changed CPI forecast moves all seven,
+and a change to the personal allowance or basic rate limit after 2030-31 also
+moves the aligned NICs thresholds (see ``policyengine_uk.utils.dated_reforms``).
+The exceptions edit the processed parameters, so they do not move the others:
+``Scenario.apply`` on an already-built simulation, and a reform-dict key naming
+a single day or month (other than 1 January on a calendar-year series, such as
+a CPI growth rate, which is a dated change and so does move them).
 """
 
 from decimal import ROUND_CEILING, ROUND_HALF_UP, Decimal

{policyengine_uk-2.131.0 → policyengine_uk-2.131.2}/policyengine_uk/parameters/gov/simulation/labour_supply_responses/aliases.py

@@ -24,6 +24,27 @@ def canonicalize_lsr_parameter_path(path: str) -> str:
     return path
 
 
+def canonicalize_parameter_changes(changes: dict) -> dict:
+    """Changes keyed by canonical parameter paths.
+
+    A deprecated alias path names the parameter it copies, the one formulas
+    read. Where a path and its alias both appear (two scenarios spelling it
+    differently, say), their changes are merged in order, as two changes to
+    one path are: dated keys from both are kept, a later key for the same
+    period wins, and a value with no period replaces what came before.
+    """
+    canonical = {}
+    for path, value in changes.items():
+        name = canonicalize_lsr_parameter_path(path)
+        if name not in canonical:
+            canonical[name] = value
+        elif isinstance(canonical[name], dict) and isinstance(value, dict):
+            canonical[name] = {**canonical[name], **value}
+        else:
+            canonical[name] = value
+    return canonical
+
+
 def add_lsr_deprecation_aliases(parameters: ParameterNode) -> ParameterNode:
     simulation = parameters.gov.simulation
     canonical = simulation.labour_supply_responses

{policyengine_uk-2.131.0 → policyengine_uk-2.131.2}/policyengine_uk/simulation.py

@@ -61,17 +61,19 @@ from policyengine_uk.utils.supplied_inputs import (
 )
 from policyengine_uk.reforms import create_structural_reforms_from_parameters
 from policyengine_uk.parameters.gov.simulation.labour_supply_responses.aliases import (
-    canonicalize_lsr_parameter_path,
+    canonicalize_parameter_changes,
 )
 
-from .tax_benefit_system import CountryTaxBenefitSystem, DEFAULT_DATASET_ENV_VAR
+from .tax_benefit_system import (
+    CountryTaxBenefitSystem,
+    DEFAULT_DATASET_ENV_VAR,
+    parameter_reads_calendar_years,
+)
 
 
 def _canonical_parameter_paths(changes: dict) -> dict:
     """Changes keyed by canonical parameter paths (labour supply aliases)."""
-    return {
-        canonicalize_lsr_parameter_path(path): value for path, value in changes.items()
-    }
+    return canonicalize_parameter_changes(changes)
 
 
 from microdf import MicroDataFrame
@@ -620,7 +622,10 @@ class Simulation(CoreSimulation):
         read) and the parameters are processed as current law is.
         """
         self.apply_parameter_assignments(
-            read_parameter_changes(_canonical_parameter_paths(changes))
+            read_parameter_changes(
+                _canonical_parameter_paths(changes),
+                calendar_years=parameter_reads_calendar_years(),
+            )
         )
 
     def apply_scenario_parameters(self, scenario: Scenario) -> None:
@@ -635,7 +640,8 @@ class Simulation(CoreSimulation):
         assignments = []
         if scenario.parameter_changes:
             assignments += read_parameter_changes(
-                _canonical_parameter_paths(scenario.parameter_changes)
+                _canonical_parameter_paths(scenario.parameter_changes),
+                calendar_years=parameter_reads_calendar_years(),
             )
         assignments += scenario.dated_assignments(order_start=len(assignments))
         self.apply_parameter_assignments(assignments)

{policyengine_uk-2.131.0 → policyengine_uk-2.131.2}/policyengine_uk/tax_benefit_system.py

@@ -7,7 +7,7 @@ from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional, Tuple
 
 # PolicyEngine core imports
-from policyengine_core.parameters import ParameterNode
+from policyengine_core.parameters import Parameter, ParameterNode
 from policyengine_core.parameters.operations.propagate_parameter_metadata import (
     propagate_parameter_metadata,
 )
@@ -50,9 +50,11 @@ from policyengine_uk.parameters.gov.economic_assumptions.lag_cpi import (
 )
 from policyengine_uk.parameters.gov.simulation.labour_supply_responses.aliases import (
     add_lsr_deprecation_aliases,
+    canonicalize_lsr_parameter_path,
 )
 from policyengine_uk.utils.dated_reforms import (
     BACKDATED_FROM,
+    CALENDAR_YEAR_SERIES,
     LegacyOverride,
     ParameterAssignment,
     Timeline,
@@ -83,22 +85,50 @@ _processed_parameters_cache = None
 # parameter's statutory values at their legal dates. Reforms are written
 # onto a copy of this tree.
 _statutory_parameters_cache = None
-# Each gov parameter's timeline in the cached processed tree after
-# projection (uprating, indexation and the other generated series) and
-# before fiscal-year annualisation, by name.
+# Each parameter's timeline in the cached processed tree after projection
+# (uprating, indexation and the other generated series) and, for gov
+# parameters, before fiscal-year annualisation, by name.
 _projected_timelines_cache = None
 
 
-def _add_generated_parameters(parameters: ParameterNode) -> ParameterNode:
-    parameters = add_private_pension_uprating_factor(parameters)
-    parameters = add_lagged_earnings(parameters)
-    parameters = add_lagged_cpi(parameters)
-    parameters = add_statutory_uprating_inputs(parameters)
-    parameters = add_triple_lock(parameters)
-    parameters = add_september_cpi_uprating(parameters)
-    parameters = create_economic_assumption_indices(parameters)
-    parameters = add_threshold_indexation(parameters)
-    parameters = add_lsr_deprecation_aliases(parameters)
+# The steps that generate parameters from others, in order. Each may read
+# what the steps before it generate.
+GENERATION_STEPS = (
+    add_private_pension_uprating_factor,
+    add_lagged_earnings,
+    add_lagged_cpi,
+    add_statutory_uprating_inputs,
+    add_triple_lock,
+    add_september_cpi_uprating,
+    create_economic_assumption_indices,
+    add_threshold_indexation,
+    add_lsr_deprecation_aliases,
+)
+
+
+def _add_generated_parameters(
+    parameters: ParameterNode,
+    generated: Optional[List[ParameterAssignment]] = None,
+) -> ParameterNode:
+    """Run the generation steps, writing changes to generated parameters.
+
+    Each change in ``generated`` is written onto its parameter just after
+    the step that generates it, so the later steps, and uprating, read it.
+    """
+    pending = list(generated or [])
+    for step in GENERATION_STEPS:
+        parameters = step(parameters)
+        if pending:
+            defines = tree_defines(parameters)
+            for assignment in [a for a in pending if defines(a.path)]:
+                write_assignment(parameters.get_child(assignment.path), assignment)
+                pending.remove(assignment)
+    if pending:
+        raise ValueError(
+            "Could not find the parameter "
+            + ", ".join(sorted({assignment.path for assignment in pending}))
+            + "."
+        )
     return parameters
 
 
@@ -106,6 +136,7 @@ def process_parameter_tree(
     parameters: ParameterNode,
     unreformed: Optional[ParameterNode] = None,
     annualise: bool = True,
+    generated: Optional[List[ParameterAssignment]] = None,
 ) -> Tuple[ParameterNode, Dict[str, Timeline]]:
     """Project and annualise a statutory parameter tree.
 
@@ -120,8 +151,9 @@ def process_parameter_tree(
     - parameter uprating and backdating
     - conversion to fiscal year parameters
 
-    Returns the tree and each gov parameter's timeline just before the
-    conversion to fiscal years.
+    Returns the tree and each parameter's timeline after projection (for gov
+    parameters, just before the conversion to fiscal years), leaving out the
+    ``baseline`` copy.
 
     ``parameters.baseline`` is the copy of the parameters without reforms
     that ``baseline_vat`` and the budget adjustments compare against, taken
@@ -129,8 +161,11 @@ def process_parameter_tree(
     tree carrying dated reform changes passes ``unreformed``, the same tree
     without them, which the copy is taken from instead (#2188).
     ``annualise=False`` stops after the projection and adds no copy.
+    ``generated`` holds the reform's changes to generated parameters, each
+    written just after the step that generates it (see
+    ``_add_generated_parameters``).
     """
-    parameters = _add_generated_parameters(parameters)
+    parameters = _add_generated_parameters(parameters, generated)
 
     # Create baseline parameters for reform comparisons
     if annualise:
@@ -145,7 +180,14 @@ def process_parameter_tree(
     parameters = propagate_parameter_metadata(parameters)
     parameters = uprate_parameters(parameters)
     parameters = backdate_parameters(parameters, BACKDATED_FROM)
+    # Prior law's projected path for every parameter a reform can change: the
+    # gov tree, before annualisation, and the trees outside it (household),
+    # which are not annualised. ``baseline`` is a copy, whose parameters
+    # keep the names of the ones it copies.
     projected = snapshot_timelines(parameters.gov)
+    for key, child in parameters.children.items():
+        if key not in ("gov", "baseline") and isinstance(child, ParameterNode):
+            projected.update(snapshot_timelines(child))
     if not annualise:
         return parameters, projected
     parameters.gov = convert_to_fiscal_year_parameters(parameters.gov)
@@ -201,7 +243,7 @@ class CountryTaxBenefitSystem(TaxBenefitSystem):
         """Process and transform parameters with UK-specific adjustments.
 
         See ``process_parameter_tree``, which this runs on the system's
-        parameters. ``projected_timelines`` keeps each gov parameter's
+        parameters. ``projected_timelines`` keeps each parameter's
         timeline from before the conversion to fiscal years.
 
         The system's dated reform changes (``dated_assignments``) are written
@@ -350,7 +392,7 @@ class CountryTaxBenefitSystem(TaxBenefitSystem):
 
     @property
     def projected_timelines(self) -> Dict[str, Timeline]:
-        """Each gov parameter's timeline before fiscal-year annualisation.
+        """Each parameter's projected timeline (gov: before annualisation).
 
         A copy: the timelines of an unreformed system, and of a rebuild
         taken from the memo, are shared with later systems.
@@ -370,12 +412,22 @@ class CountryTaxBenefitSystem(TaxBenefitSystem):
         if not assignments:
             self.parameters, self._projected_timelines = process_parameter_tree(raw)
             return
+        # Changes to parameters processing generates are written as each is
+        # generated; the rest go on the statutory timeline first.
+        defines = tree_defines(raw)
+        on_timeline = [a for a in assignments if defines(a.path)]
+        generated = [a for a in assignments if not defines(a.path)]
+        generates = generated_parameter_defines()
+        for assignment in generated:
+            if not generates(assignment.path):
+                # Not generated either: the error the lookup gives.
+                raw.get_child(assignment.path)
         unreformed = raw.clone()
-        projected = prior_law_projection(assignments, unreformed, statutory)
-        for assignment in assignments:
+        projected = prior_law_projection(on_timeline, unreformed, statutory, generated)
+        for assignment in on_timeline:
             write_assignment(raw.get_child(assignment.path), assignment, projected)
         self.parameters, self._projected_timelines = process_parameter_tree(
-            raw, unreformed
+            raw, unreformed, generated=generated
         )
 
     def _apply_legacy_overrides(self) -> None:
@@ -476,8 +528,85 @@ def statutory_parameter_defines() -> Callable[[str], bool]:
     return tree_defines(_statutory_parameters_cache)
 
 
+# The paths of the parameters the generation steps add to the statutory tree,
+# other than the deprecated labour supply aliases.
+_generated_paths_cache: Optional[frozenset] = None
+
+
+def _leaf_paths(node: ParameterNode, prefix: str = "") -> List[str]:
+    paths = []
+    for key, child in node.children.items():
+        path = f"{prefix}.{key}" if prefix else key
+        if isinstance(child, Parameter):
+            paths.append(path)
+        elif isinstance(child, ParameterNode):
+            paths += _leaf_paths(child, path)
+        else:
+            for index, bracket in enumerate(getattr(child, "brackets", [])):
+                paths += _leaf_paths(bracket, f"{path}[{index}]")
+    return paths
+
+
+def generated_parameter_defines() -> Callable[[str], bool]:
+    """Whether processing generates a parameter at a path.
+
+    The deprecated labour supply aliases are left out: a change to one is a
+    change to the parameter it copies (``canonicalize_lsr_parameter_path``).
+    """
+    global _generated_paths_cache
+    if _generated_paths_cache is None:
+        _ensure_caches()
+        statutory = tree_defines(_statutory_parameters_cache)
+        generated = _add_generated_parameters(statutory_parameters())
+        _generated_paths_cache = frozenset(
+            path
+            for path in _leaf_paths(generated)
+            if not statutory(path) and canonicalize_lsr_parameter_path(path) == path
+        )
+    return _generated_paths_cache.__contains__
+
+
+def reform_parameter_defines() -> Callable[[str], bool]:
+    """Whether a reform's change to a path is written on the timeline.
+
+    True for the parameters in the statutory tree and those processing
+    generates; changes to any other path (one a structural reform adds) are
+    legacy overrides of the annualised parameters.
+    """
+    statutory = statutory_parameter_defines()
+    generated = generated_parameter_defines()
+    return lambda path: statutory(path) or generated(path)
+
+
+def parameter_reads_calendar_years() -> Callable[[str], bool]:
+    """Whether a parameter's values are for calendar years.
+
+    So a bare-year reform key names the calendar year, not the fiscal year
+    (see ``policyengine_uk.utils.dated_reforms``). True for a parameter
+    outside ``gov``, which is never annualised and is read at 1 January, and
+    for one with ``calendar_year_series`` metadata on it or an ancestor node.
+    """
+    _ensure_caches()
+    tree = _processed_parameters_cache
+
+    def reads(path: str) -> bool:
+        try:
+            node = tree.get_child(path)
+        except Exception:
+            return False
+        if path.split(".")[0] != "gov":
+            return True
+        while node is not None:
+            if (getattr(node, "metadata", None) or {}).get(CALENDAR_YEAR_SERIES):
+                return True
+            node = getattr(node, "parent", None)
+        return False
+
+    return reads
+
+
 def projected_timelines() -> Dict[str, Timeline]:
-    """Current law's projected timeline for each gov parameter, by name.
+    """Current law's projected timeline for each parameter, by name.
 
     Shared: do not change them. ``CountryTaxBenefitSystem.projected_timelines``
     returns a copy.
@@ -497,6 +626,7 @@ def prior_law_projection(
     assignments: List[ParameterAssignment],
     unreformed: ParameterNode,
     statutory: bool = True,
+    generated: Optional[List[ParameterAssignment]] = None,
 ) -> Callable[[str], Optional[Timeline]]:
     """Prior law's projected timeline, by parameter name, for a reform.
 
@@ -510,7 +640,8 @@ def prior_law_projection(
     that still change after that depend on each other in a cycle, which is
     an error. ``unreformed`` is the tree the changes are written onto;
     ``statutory`` says it is the YAML as loaded, whose projection without
-    changes is cached.
+    changes is cached. ``generated`` holds the reform's changes to generated
+    parameters, which every pass makes too.
     """
     needing = sorted(
         {
@@ -523,8 +654,10 @@ def prior_law_projection(
         return lambda name: None
     start = (
         projected_timelines()
-        if statutory
-        else process_parameter_tree(unreformed.clone(), annualise=False)[1]
+        if statutory and not generated
+        else process_parameter_tree(
+            unreformed.clone(), annualise=False, generated=generated
+        )[1]
     )
     environment = {path: start.get(path) for path in needing}
 
@@ -541,7 +674,9 @@ def prior_law_projection(
                     write_assignment(
                         tree.get_child(assignment.path), assignment, lookup
                     )
-            updated[path] = process_parameter_tree(tree, annualise=False)[1].get(path)
+            updated[path] = process_parameter_tree(
+                tree, annualise=False, generated=generated
+            )[1].get(path)
         if _same_timelines(updated, environment):
             return lookup
         environment = updated

policyengine_uk-2.131.2/policyengine_uk/tests/policy/baseline/household/income/hbai_housing_costs.yaml

@@ -0,0 +1,71 @@
+# HBAI FYE 2025's housing-cost definition includes ground rent and service
+# charges: https://www.gov.uk/government/statistics/households-below-average-income-for-financial-years-ending-1995-to-2025/households-below-average-income-background-information-and-methodology-report-fye-2025#glossary
+# Input BHC income directly so these housing-cost cases remain independent
+# of how income before housing costs is calculated or floored.
+
+- name: Renters deduct service charges in addition to rent and water
+  period: 2026
+  absolute_error_margin: 0.01
+  input:
+    age: 40
+    tenure_type: RENT_PRIVATELY
+    hbai_household_net_income: 30_000
+    rent: 12_000
+    water_and_sewerage_charges: 400
+    mortgage_interest_repayment: 0
+    structural_insurance_payments: 0
+    housing_service_charges: 1_200
+    household_equivalisation_ahc: 0.58
+  output:
+    # 30,000 - 12,000 - 400 - 1,200.
+    hbai_household_net_income_ahc: 16_400
+    # 16,400 / 0.58.
+    equiv_hbai_household_net_income_ahc: 28_275.862069
+
+- name: Owner-occupiers deduct ground rent with mortgage interest and insurance
+  period: 2025
+  absolute_error_margin: 0.01
+  input:
+    age: 40
+    tenure_type: OWNED_WITH_MORTGAGE
+    hbai_household_net_income: 30_000
+    rent: 0
+    water_and_sewerage_charges: 400
+    mortgage_interest_repayment: 3_000
+    structural_insurance_payments: 200
+    housing_service_charges: 600
+  output:
+    # 30,000 - 400 - 3,000 - 200 - 600.
+    hbai_household_net_income_ahc: 25_800
+
+- name: Without ground rent or service charges the other deductions are unchanged
+  period: 2024
+  absolute_error_margin: 0.01
+  input:
+    age: 40
+    tenure_type: RENT_PRIVATELY
+    hbai_household_net_income: 30_000
+    rent: 12_000
+    water_and_sewerage_charges: 400
+    mortgage_interest_repayment: 0
+    structural_insurance_payments: 0
+    housing_service_charges: 0
+  output:
+    # 30,000 - 12,000 - 400.
+    hbai_household_net_income_ahc: 17_600
+
+- name: Housing costs above BHC income leave negative AHC income
+  period: 2026
+  absolute_error_margin: 0.01
+  input:
+    age: 40
+    tenure_type: RENT_PRIVATELY
+    hbai_household_net_income: 5_000
+    rent: 6_000
+    water_and_sewerage_charges: 400
+    mortgage_interest_repayment: 0
+    structural_insurance_payments: 0
+    housing_service_charges: 1_200
+  output:
+    # 5,000 - 6,000 - 400 - 1,200, without an AHC zero floor.
+    hbai_household_net_income_ahc: -2_600

{policyengine_uk-2.131.0 → policyengine_uk-2.131.2}/policyengine_uk/tests/test_dated_reform_routes.py

@@ -877,7 +877,7 @@ def test_prior_law_that_never_settles_is_an_error(monkeypatch):
 
     calls = {"n": 0}
 
-    def unsettled(tree, unreformed=None, annualise=True):
+    def unsettled(tree, unreformed=None, annualise=True, generated=None):
         calls["n"] += 1
         entry = ParameterAtInstant(
             UC_SINGLE_OLD, "2026-04-01", data={"value": float(calls["n"])}