From 80a0168fa93d611cbacc965ef4a98e59c087d261 Mon Sep 17 00:00:00 2001 From: Vahid Ahmadi Date: Mon, 1 Jun 2026 16:31:49 +0100 Subject: [PATCH 1/2] Revert "Add fiscal-year uprating planning docs page (#1437 #1436) (#1716)" This reverts commit c51a8d6e7120208f6593f5aa62032abac5a399b4. --- changelog.d/1437.md | 1 - .../assumptions/fiscal-year-uprating-plan.md | 120 ------------------ 2 files changed, 121 deletions(-) delete mode 100644 changelog.d/1437.md delete mode 100644 docs/book/assumptions/fiscal-year-uprating-plan.md diff --git a/changelog.d/1437.md b/changelog.d/1437.md deleted file mode 100644 index e53377dae..000000000 --- a/changelog.d/1437.md +++ /dev/null @@ -1 +0,0 @@ -- Add a planning docs page at `docs/book/assumptions/fiscal-year-uprating-plan.md` describing the proposed move from January-1 to April-6 dates for OBR growth indices (#1437) and how it relates to the on-the-fly conversion alternative (#1436); identifies the four pipeline changes needed (yoy_growth.yaml dates, create_economic_assumption_indices.py, policyengine-core's `uprate_parameters` assumptions, and removing `convert_to_fiscal_year_parameters`) and notes the user-visible correctness gain at mid-year queries. diff --git a/docs/book/assumptions/fiscal-year-uprating-plan.md b/docs/book/assumptions/fiscal-year-uprating-plan.md deleted file mode 100644 index 3dd8bfa2e..000000000 --- a/docs/book/assumptions/fiscal-year-uprating-plan.md +++ /dev/null @@ -1,120 +0,0 @@ -# Fiscal-year uprating: April-date alignment plan - -```{note} -**Planning page.** PolicyEngine UK currently stores OBR growth indices -at **January 1** dates and post-processes parameters to the fiscal year -via `convert_to_fiscal_year_parameters`. This page captures the proposed -move to **April 6** dates throughout, tracked under -[#1437](https://github.com/PolicyEngine/policyengine-uk/issues/1437), -and the on-the-fly alternative tracked under -[#1436](https://github.com/PolicyEngine/policyengine-uk/issues/1436). -This is a low-priority enhancement — the current approach is correct -for annual analysis after PR #1435 extended the fiscal-year-conversion -range out to 2040. -``` - -## Current pipeline - -The model currently does three things in sequence: - -1. **OBR indices** live at January 1 dates in - [`parameters/gov/economic_assumptions/yoy_growth.yaml`](../../../policyengine_uk/parameters/gov/economic_assumptions/yoy_growth.yaml) - (annual calendar-year growth rates) and the cumulative indices are - generated by - [`create_economic_assumption_indices.py`](../../../policyengine_uk/parameters/gov/economic_assumptions/create_economic_assumption_indices.py) - at January 1 dates (`f"{year}-01-01"`). -2. **`uprate_parameters`** in `policyengine-core` writes uprated - parameter values at the same dates as the uprating index, so all - uprated parameters land at January 1. -3. **`convert_to_fiscal_year_parameters`** in - [`utils/parameters.py`](../../../policyengine_uk/utils/parameters.py) - post-processes the parameter tree by sampling each parameter at - April 30 and overwriting the whole calendar year with that value. - This is what produces the fiscal-year-correct outputs PolicyEngine - ships today. - -This works for annual simulations but has three downsides: - -- **Intra-year queries are wrong.** `param("2026-03-15")` returns the - fiscal-year-2026 value when April 6 2026 hasn't happened yet; the - intended pre-April-6 value is the fiscal-year-2025 value. -- The fiscal-year conversion is a **post-process workaround**, not a - correct upstream model. -- Parameter `values_list` entries appear at January 1 dates even - though the legislative change usually takes effect on April 6. - -## Proposed change (#1437): store at April 6 throughout - -Update each step of the pipeline so it speaks fiscal years natively: - -1. Move the dates in `yoy_growth.yaml` from `YYYY-01-01` to - `YYYY-04-06` for every entry, ensuring the growth rate that applies - between fiscal year T and fiscal year T+1 sits at the start of T+1. -2. Update `create_economic_assumption_indices.py` to emit cumulative - indices at April 6 dates. -3. Confirm that `policyengine-core`'s `uprate_parameters` does not bake - any January-1 assumption — if it does, parametrise the date. -4. **Remove** `convert_to_fiscal_year_parameters` and its call site in - [`tax_benefit_system.py`](../../../policyengine_uk/tax_benefit_system.py). - Once steps 1-3 land, the natural answer at every date is already the - fiscal-year-correct value. - -### What changes for users - -| Query | Today | After April-date move | -|-------|-------|------------------------| -| `param("2026")` (year-string) | Fiscal year 2026/27 value (post-process) | Fiscal year 2026/27 value (direct) | -| `param("2026-03-15")` (pre-April 6) | Fiscal year 2025/26 value (correct) | Fiscal year 2025/26 value (correct) | -| `param("2026-05-15")` (post-April 6) | Fiscal year 2025/26 value (**wrong**) | Fiscal year 2026/27 value (correct) | -| `values_list` dates | January 1 | April 6 | - -The third row is the headline correctness gain. - -### Scope - -- Pure documentation/wiring change — **no household-impact values - should move** for any annual query. -- Regression tests must include both an annual-query and an - April-30-style mid-year-query case so the next refactor can't - reintroduce the off-by-three-months bug. -- Reform-side parameters (legislated rate changes) should already be - dated April 6 in their YAML files (most are); spot-check the - exceptions during the migration. - -## On-the-fly alternative (#1436) - -The complementary issue [#1436](https://github.com/PolicyEngine/policyengine-uk/issues/1436) -proposes the inverse: instead of moving every date to April 6, keep -indices at January 1 and resolve the fiscal-year conversion lazily at -query time. - -That would let the conversion stop being a 26-year pre-computation step -at startup (the `range(2015, 2041)` loop in -`convert_to_fiscal_year_parameters`) and remove the year-range -upper-bound altogether. - -The two approaches are mutually exclusive: either we change the data to -match the queries (#1437) or we change the resolver to translate -queries to the data (#1436). Recommendation: - -- Prefer **#1437 (April dates)** for correctness and ergonomics — the - underlying policy change happens on April 6, so the YAML should say - April 6. -- Consider **#1436 (on-the-fly)** if a refactor of - `convert_to_fiscal_year_parameters` becomes hot-path for any specific - user — it's primarily a startup-cost optimisation. - -## Sequencing - -1. Land #1437 first: it removes the post-process workaround and makes - the YAML files self-explanatory. -2. Once #1437 is live, evaluate whether the lazy approach in #1436 is - still worth doing — most of its benefit is already captured by step 4 - above ("remove `convert_to_fiscal_year_parameters`"). - -## References - -- Issue [#1437](https://github.com/PolicyEngine/policyengine-uk/issues/1437) — April-date alignment. -- Issue [#1436](https://github.com/PolicyEngine/policyengine-uk/issues/1436) — on-the-fly conversion exploration. -- PR [#1435](https://github.com/PolicyEngine/policyengine-uk/pull/1435) — extended the fiscal-year-conversion range to 2040. -- [`growthfactors.md`](./growthfactors.md) — the underlying OBR growth rates. From b9e130cb5783103f514798a574919d46c449529e Mon Sep 17 00:00:00 2001 From: Vahid Ahmadi Date: Mon, 1 Jun 2026 16:40:13 +0100 Subject: [PATCH 2/2] Add changelog entry for #1716 revert Co-Authored-By: Claude Opus 4.8 (1M context) --- changelog.d/1437-revert.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog.d/1437-revert.md diff --git a/changelog.d/1437-revert.md b/changelog.d/1437-revert.md new file mode 100644 index 000000000..4cc1b166f --- /dev/null +++ b/changelog.d/1437-revert.md @@ -0,0 +1 @@ +- Revert the fiscal-year uprating planning docs page (#1716) per maintainer request.