Clarify bottled gas coverage and fuel levelling requirements

changelog.d/2642.changed.md

@@ -0,0 +1 @@
+Clarified bottled gas coverage and ONS levelling requirements for liquid and solid heating fuel inputs.

policyengine_uk/tests/test_heating_fuel_inputs.py

@@ -1,10 +1,10 @@
 """Liquid and solid heating fuel inputs (#2572).
 
-Homes off the gas grid heat with oil, LPG, coal or wood: COICOP 04.5.3 and
-04.5.4. Their spending is part of housing_water_and_electricity_consumption,
-so the inputs default to zero and add nothing to consumption. Ofgem's price
-cap does not cover them, so dataset projection uprates them by CPI like other
-LCFS spending.
+Homes off the gas grid heat with oil (COICOP 04.5.3), LPG (04.5.2), coal or
+wood (04.5.4). Their spending is part of
+housing_water_and_electricity_consumption, so the inputs default to zero and
+add nothing to consumption. Ofgem's price cap does not cover them, so dataset
+projection uprates them by CPI like other LCFS spending.
 """
 
 from pathlib import Path

policyengine_uk/variables/input/consumption/liquid_fuel_consumption.py

@@ -1,21 +1,32 @@
 from policyengine_uk.model_api import *
 
-# COICOP 04.5.3 (liquid fuels). A sub-component of
-# housing_water_and_electricity_consumption (COICOP 04), so not added into the
-# `consumption` total, which already counts it.
+# Heating oil, paraffin and bottled gas (COICOP 04.5.3 and part of 04.5.2).
+# A sub-component of housing_water_and_electricity_consumption (COICOP 04),
+# so not added into the `consumption` total, which already counts it.
 
 
 class liquid_fuel_consumption(Variable):
     label = "Liquid fuel consumption"
     documentation = (
-        "Annual household spending on liquid fuels such as heating oil and "
-        "liquefied petroleum gas (COICOP 04.5.3), mostly for heating homes off "
-        "the gas grid. Already included in "
+        "Annual household spending on heating oil, paraffin and bottled gas, "
+        "mostly for heating homes off the gas grid. COICOP puts bottled gas "
+        "(liquefied petroleum gas) under 04.5.2, gas, so a dataset that includes "
+        "it is wider than ONS's 04.5.3. Microcosm releases built from "
+        "https://github.com/PolicyEngine/microcosm/pull/1383 include bottled "
+        "gas in this column and do not level it to ONS Consumer Trends "
+        "04.5.3. A costing using this input needs levelling to ONS first, "
+        "accounting for the bottled gas separately. No model formula reads "
+        "this input yet. "
+        "Already included in "
         "housing_water_and_electricity_consumption; do not add it to "
         "consumption again. Dataset projection uprates it by CPI from the data "
         "year, like other LCFS spending: Ofgem's price cap, which prices the "
         "electricity and gas inputs, does not cover it."
     )
+    reference = (
+        "https://unstats.un.org/unsd/classifications/Econ/Structure/Detail/EN/2094/04_5_2",
+        "https://unstats.un.org/unsd/classifications/Econ/Structure/Detail/EN/2094/04_5_3",
+    )
     entity = Household
     definition_period = YEAR
     value_type = float

policyengine_uk/variables/input/consumption/solid_fuel_consumption.py

@@ -10,11 +10,17 @@ class solid_fuel_consumption(Variable):
     documentation = (
         "Annual household spending on solid fuels such as coal, smokeless fuel "
         "and wood (COICOP 04.5.4), mostly for heating homes off the gas grid. "
+        "Microcosm releases built from "
+        "https://github.com/PolicyEngine/microcosm/pull/1383 provide this column "
+        "without levelling it to ONS Consumer Trends 04.5.4. A costing using "
+        "this input needs levelling to ONS first. No model formula reads this "
+        "input yet. "
         "Already included in housing_water_and_electricity_consumption; do not "
         "add it to consumption again. Dataset projection uprates it by CPI from "
         "the data year, like other LCFS spending: Ofgem's price cap, which "
         "prices the electricity and gas inputs, does not cover it."
     )
+    reference = "https://unstats.un.org/unsd/classifications/Econ/Structure/Detail/EN/2094/04_5_4"
     entity = Household
     definition_period = YEAR
     value_type = float