Document long-run economic projections (#1379) (#1701)

The 2031+ growth values in yoy_growth.yaml had a one-line header comment
naming the steady-state assumptions but didn't explain where the year-by-
year ramp values came from (e.g. RPI 2.30% in 2031 -> 2.39% by 2035). #1379
asked for that to be documented.

- Expand the file header to describe how each long-run series is built
  (CPI pinned to BoE target, RPI/CPIH/earnings ramp linearly from the last
  EFO value to a stated steady state, then flat through 2073) and the OBR
  publications the steady-state numbers come from.
- Add a parameters/gov/economic_assumptions/README.md tabulating every
  growth series with its OBR/ONS source and giving a refresh procedure
  for when a new EFO is published, including the call to
  create_economic_assumption_indices.py.

Author: vahid-ahmadi

changelog.d/1379.md

@@ -0,0 +1 @@
+- Document the methodology and sources for the 2031+ long-run values in `yoy_growth.yaml` (CPI pinned to the BoE 2% target; RPI/CPIH ramp to 2.39% via the OBR long-run wedge; average earnings ramp to 3.83%) and add a `parameters/gov/economic_assumptions/README.md` listing each series, its source, and a refresh procedure for new EFO releases.

policyengine_uk/parameters/gov/economic_assumptions/README.md

@@ -0,0 +1,72 @@
+# Economic assumptions
+
+Year-on-year growth series for the UK economy used to uprate parameters and
+calibrate the input dataset. The single source of truth is
+[`yoy_growth.yaml`](./yoy_growth.yaml); downstream cumulative indices are
+generated from it by
+[`create_economic_assumption_indices.py`](./create_economic_assumption_indices.py).
+
+## Series
+
+| Series                  | What it measures                                         | OBR/ONS source          |
+|-------------------------|----------------------------------------------------------|-------------------------|
+| `consumer_price_index`  | CPI year-on-year growth                                  | EFO Table 1.7           |
+| `cpih`                  | CPI including owner-occupiers' housing costs             | EFO Table 1.7           |
+| `consumer_price_index_ahc` | CPI excluding rents/maintenance/water (AHC measure)   | ONS adhoc 2863          |
+| `rpi`                   | Retail Price Index year-on-year growth                   | EFO Table 1.7           |
+| `average_earnings`      | Average weekly earnings growth                           | EFO Table 1.6           |
+| `non_labour_income`     | Non-labour household income growth                       | derived from EFO        |
+| `road_fuel_volume`      | Petrol + diesel road-fuel clearances                     | HMRC Hydrocarbon Oils + OBR fuel-duty forecast |
+| `petrol_spending_litre_proxy` | Spending growth that preserves road-fuel litres    | HMRC + OBR              |
+| `diesel_spending_litre_proxy` | Same, for diesel                                   | HMRC + OBR              |
+
+## Time horizons
+
+Three horizons are stitched together for each series:
+
+1. **Outturn** (history through 2024): ONS published data, copied from OBR
+   detailed forecast tables.
+2. **EFO forecast** (2025-2030): latest OBR Economic and Fiscal Outlook
+   supplementary tables. The version currently checked in is **March 2026**;
+   refresh after each new EFO.
+3. **Long-run equilibrium** (2031-2073): constructed from OBR's long-run
+   assumptions (Fiscal Risks and Sustainability report) and the long-run
+   RPI-CPI wedge methodology.
+
+## How the 2031+ values were constructed
+
+Issue [#1379](https://github.com/PolicyEngine/policyengine-uk/issues/1379)
+flagged that the year-by-year 2031+ values weren't documented. They are
+constructed as follows:
+
+- **CPI** is pinned to the Bank of England's 2.0% target from 2031-01-01
+  onwards.
+- **RPI** and **CPIH** linearly interpolate from the final EFO value
+  (2030-01-01) up to a 2.39% steady state by 2035-01-01, then hold flat
+  through 2073-01-01. The 0.39 pp gap above CPI is the OBR's published
+  long-run wedge to account for housing-cost growth ([long-run difference
+  between RPI and CPI inflation][rpi-cpi]).
+- **Average earnings** linearly interpolate from the final EFO value
+  (2030-01-01) up to a 3.83% steady state by 2036-01-01, then hold flat.
+  This is consistent with the OBR's long-run productivity assumption
+  (1.8%) added to CPI (2.0%).
+- **`road_fuel_volume`** is held flat at 0% after the OBR forecast ends —
+  i.e. the final EFO forecast volume is held constant in real terms.
+
+These steady-state assumptions are reviewed each time the OBR publishes a
+new Fiscal Risks and Sustainability report. The convergence path itself
+is conservative interpolation and is not load-bearing for short-horizon
+analysis.
+
+## Refreshing after a new EFO
+
+1. Replace the 2025-2030 block in each series with values from the new EFO
+   detailed forecast tables (note the EFO release month in the header comment).
+2. Recompute the 2031-2073 convergence path so the first long-run year
+   continues smoothly from the new last forecast year (no jump).
+3. Run `python policyengine_uk/parameters/gov/economic_assumptions/create_economic_assumption_indices.py`
+   to regenerate the cumulative `indices/` parameters that uprating depends
+   on.
+4. Update the EFO reference in each series' `metadata.reference`.
+
+[rpi-cpi]: https://obr.uk/box/the-long-run-difference-between-rpi-and-cpi-inflation/

policyengine_uk/parameters/gov/economic_assumptions/yoy_growth.yaml

@@ -1,15 +1,37 @@
 # OBR Economic Projections
 #
-# Data sources:
-# - 2009-2024: OBR outturn data from detailed forecast tables
-# - 2025-2030: OBR forecast from latest Economic and Fiscal Outlook (EFO, March 2026)
-# - 2031+: OBR long-run equilibrium assumptions:
-#   - CPI: 2.0% (Bank of England target)
-#   - RPI/CPIH: ~2.4% (CPI + 0.4pp wedge, reflecting housing costs growth)
-#   - Average earnings: ~3.8% (productivity growth + inflation)
-#   Note: RPI will align with CPIH methodology from February 2030 per ONS plans
+# Data sources by horizon:
+# - 2009-2024: OBR outturn data from detailed forecast tables.
+# - 2025-2030: OBR forecast from the latest Economic and Fiscal Outlook
+#   (EFO, March 2026). Values come from the EFO economy supplementary
+#   tables — RPI/CPI/CPIH from Table 1.7, average earnings from Table 1.6.
+# - 2031-2073: OBR long-run equilibrium assumptions, taken from the OBR
+#   Fiscal Risks and Sustainability report and the long-run RPI-CPI wedge
+#   methodology. Steady-state values:
+#     * consumer_price_index: 2.00%  (Bank of England target)
+#     * rpi:                  2.39%  (CPI + 0.39pp long-run wedge)
+#     * cpih:                 2.39%  (CPI + 0.39pp housing-costs wedge,
+#                                     converges with RPI once RPI adopts
+#                                     CPIH methodology from Feb 2030 per ONS)
+#     * average_earnings:     3.83%  (productivity growth + CPI)
 #
-# See: https://obr.uk/box/the-long-run-difference-between-rpi-and-cpi-inflation/
+# How the 2031+ series are constructed:
+# - CPI hits its 2% target on 2031-01-01 and is held flat.
+# - RPI, CPIH and average earnings ramp linearly from the final EFO value
+#   (2030-01-01) to the steady-state value, converging by 2035-2036. After
+#   convergence the series are held flat through 2073-01-01.
+# - This convergence path is consistent with the OBR's Fiscal Risks and
+#   Sustainability long-run assumptions and is regenerated when a new EFO
+#   is released; the helper module
+#   `policyengine_uk/parameters/gov/economic_assumptions/create_economic_assumption_indices.py`
+#   refreshes downstream indices from these growth rates.
+#
+# References:
+#   https://obr.uk/efo/                                  (latest EFO)
+#   https://obr.uk/frltp/                                (Fiscal risks and
+#                                                          long-term projections)
+#   https://obr.uk/box/the-long-run-difference-between-rpi-and-cpi-inflation/
+#   https://www.bankofengland.co.uk/monetary-policy/inflation
 
 obr:
   rpi: