Merge pull request #333 from iiasa/project/ssp/transport/2025-04-10

Improve aviation emissions postprocessing

Author: khaeru

doc/whatsnew.rst

@@ -70,6 +70,13 @@ SSP :ref:`ssp-2024`/ScenarioMIP
   - Add :func:`~.ssp.transport.process_df` (:pull:`303`);
     handle data frames containing :py:`np.NaN` (:pull:`330`).
   - Adapt to revised ‘variable’ codes (:pull:`309`, :issue:`304`).
+- Add :func:`~.ssp.transport.method_B` and make this the default (:pull:`259`, :pull:`330`).
+- Add :func:`~.ssp.transport.method_C` (:issue:`305`, :pull:`325`, :pull:`330`).
+- Add :func:`~.ssp.transport.process_df` (:pull:`303`);
+  handle data frames containing :py:`np.NaN` (:pull:`330`).
+- Adapt to revised ‘variable’ codes (:pull:`309`, :issue:`304`).
+- Expand covered emission species (:pull:`333`, :issue:`307`)
+  with values derived from `CEDS <https://www.pnnl.gov/projects/ceds>`_.
 
 Transport
 ---------

message_ix_models/data/emission.yaml

@@ -1,6 +1,14 @@
+# Annotations appearing in this code list:
+#
+# - report: label used in IAMC 'variable' names. Default: the code ID.
+# - unit: mass units only for reporting. Default: "Mt".
+# - unit-species: species used in a IAMC 'unit' expression such as "Mt XX/yr".
+#   Default: the code ID.
+
 BCA:
   name: Black carbon
   report: BC
+  unit-species: BC
 
 CH4:
   name: Methane
@@ -20,10 +28,12 @@ NH3:
 
 NOx:
   name: Nitrogen oxides
+  # unit-species: NO2
 
 OCA:
   name: Organic carbon
   report: OC
+  unit-species: OC
 
 SO2:
   name: Sulfur dioxide

message_ix_models/data/transport/emi-intensity.csv

@@ -1,70 +1,82 @@
 # Emissions intensity of energy use
 #
-# Sources
-# - Group 1: e-mail text from Shaohui Zhang 2024-10-09
-#   Originally supplied with units [g / kg].
-# - Group 2: e-mail attachment from Shaohui Zhang 2024-10-09
-#   "EMEP_EEA Emission factor.xlsx". These all have the following
-#   dimensions/metadata in other columns:
-#   - NFR: 1.A.3.a.ii.(i)
-#   - Sector: Civil aviation (domestic, LTO)
-#     → technology=AIR
-#   - Table: Table_3-3
-#   - Type: Tier 1 Emission Factor
-#   - Technology: NA
-#   - Fuel: Jet Gasoline and Aviation Gasoline
-#   - Abatement: (empty)
-#   - Region: NA
-#   - Pollutant → emission
-#   - CI_lower, CI_upper, Reference → preserved as comments
-#   - Unit: kg/tonne fuel, which is equivalent to g / kg fuel.
-# - Group 3: e-mail from Lena Höglund-Isaksson 2024-10-06.
-#   The units for these are kt/petajoule gasoline with [=] g / MJ.
+# Sources:
+#
+# 1. e-mail text from Shaohui Zhang 2024-10-09
+#    Originally supplied with units [g / kg].
+# 2. e-mail attachment from Shaohui Zhang 2024-10-09
+#    "EMEP_EEA Emission factor.xlsx". These all have the following
+#    dimensions/metadata in other columns:
+#    - NFR: 1.A.3.a.ii.(i)
+#    - Sector: Civil aviation (domestic, LTO)
+#      → technology=AIR
+#    - Table: Table_3-3
+#    - Type: Tier 1 Emission Factor
+#    - Technology: NA
+#    - Fuel: Jet Gasoline and Aviation Gasoline
+#    - Abatement: (empty)
+#    - Region: NA
+#    - Pollutant → emission
+#    - CI_lower, CI_upper, Reference → preserved as comments
+#    - Unit: kg/tonne fuel, which is equivalent to g / kg fuel.
+# 3. e-mail from Lena Höglund-Isaksson 2024-10-06.
+#    The units for these are kt/petajoule gasoline with [=] g / MJ.
+# 4. Estimated as the ratio of CEDS data for y=2019 and MESSAGEix-Transport
+#    final energy use. The CEDS data use:
+#    - the code “Sulfur” with units “Mt SO2/yr”.
+#    - the code “NOx” with units “Mt NO2/yr”.
+#
+#    See https://iiasa-ece.slack.com/archives/CCFHDNA6P/p1744277852653529
 #
 # Units: g / MJ
 #
 technology, commodity, emission, value
-#
-# Group 1
-#
-AIR,        lightoil,  SO2,   0.0279  #    1.2  g/kg
-# AIR,      lightoil,  NOx,   0.3284  #   14.12 g/kg, lower end of confidence interval
-# AIR,      lightoil,  NOx,   0.3521  #   15.14 g/kg, upper end of confidence interval
-#
-# Group 2
-#
-# “Calculated using Tier 2 method”
-# - These values are used because the above are too large and produce negative totals.
-#
-# AIR,      lightoil,  NOx,   0.0465  #    2    g/kg
-AIR,        lightoil,  NOx,   0.0930  #    4    g/kg
-# AIR,      lightoil,  NOx,   0.1860  #    8    g/kg
-#
-# “Calculated using Tier 2 method”
-# - The low end of the range is used because the midpoint value produces negative totals.
-#
-AIR,        lightoil,  CO,    0.5     # Placeholder value for debugging
-# AIR,      lightoil,  CO,   13.95    #  600    g/kg
-# AIR,      lightoil,  CO,   27.90    # 1200    g/kg
-# AIR,      lightoil,  CO,   55.81    # 2400    g/kg
-#
-# “Calculated using Tier 2 method”
-# - These data were provided with the code 'NMVOC', but we use the label 'VOC' to
-#   align with MESSAGEix-GLOBIOM, even though these are not strictly the same.
-# - The low end of the range is used because the midpoint value produces negative totals.
-#
-AIR,        lightoil,  VOC,   0.1     # Placeholder value for debugging
-# AIR,      lightoil,  VOC,   0.2209  #    9.5  g/kg
-# AIR,      lightoil,  VOC,   0.4419  #   19    g/kg
-# AIR,      lightoil,  VOC,   0.8837  #   38    g/kg
-#
-# “Assuming 0.05% S by mass”
-#
-# AIR,      lightoil,  SOx,   0.0116  #    0.5  g/kg
-AIR,        lightoil,  SOx,   0.0233  #    1    g/kg
-# AIR,      lightoil,  SOx,   0.0465  #    2    g/kg
-#
-# Group 3
-#
-AIR,        lightoil,  CH4,   0.0005
-AIR,        lightoil,  N2O,   0.0031
+
+AIR,        lightoil,  BC,       0.001430 # (4)
+
+# (3) is used because the (4) is (nearly) zero.
+AIR,        lightoil,  CH4,      0.0005   # (3)
+# AIR,      lightoil,  CH4,      0.000000 # (4)
+
+# (4) is used because (2) values are too large and yield negative totals.
+#
+# AIR,      lightoil,  CO,      13.95     # (2)  600    g/kg “Calculated using Tier 2 method”
+# AIR,      lightoil,  CO,      27.90     # (2) 1200    g/kg “Calculated using Tier 2 method”
+# AIR,      lightoil,  CO,      55.81     # (2) 2400    g/kg “Calculated using Tier 2 method”
+AIR,        lightoil,  CO,       0.088798 # (4)
+
+AIR,        lightoil,  CO2,    111.053342 # (4)
+
+AIR,        lightoil,  N2O,      0.0031   # (3)
+# AIR,      lightoil,  N2O,      3.635365 # (4)
+
+AIR,        lightoil,  NH3,      0.005857 # (4)
+
+# NOx:
+# - (2) is used because (1) and (4) values are too large and yield negative totals.
+#
+# AIR,      lightoil,  NOx,      0.3284   # (1)   14.12 g/kg, lower end of confidence interval
+# AIR,      lightoil,  NOx,      0.3521   # (1)   15.14 g/kg, upper end of confidence interval
+# AIR,      lightoil,  NOx,      0.0465   # (2)    2    g/kg “Calculated using Tier 2 method”
+AIR,        lightoil,  NOx,      0.0930   # (2)    4    g/kg “Calculated using Tier 2 method”
+# AIR,      lightoil,  NOx,      0.1860   # (2)    8    g/kg “Calculated using Tier 2 method”
+# AIR,      lightoil,  NOx,      0.456715 # (4)
+
+AIR,        lightoil,  OC,       0.000709 # (4)
+
+AIR,        lightoil,  Sulfur,   0.0279   # (1)    1.2  g/kg
+# AIR,      lightoil,  Sulfur,   0.040058 # (4) “Sulfur” in upstream data with “SO2” in units
+
+# AIR,      lightoil,  SOx,      0.0116   # (2)    0.5  g/kg “Assuming 0.05% S by mass”
+AIR,        lightoil,  SOx,      0.0233   # (2)    1    g/kg “Assuming 0.05% S by mass”
+# AIR,      lightoil,  SOx,      0.0465   # (2)    2    g/kg “Assuming 0.05% S by mass”
+
+# VOC:
+# - (2) were provided with the code 'NMVOC', but we use the label 'VOC' to align with
+#   MESSAGEix-GLOBIOM, even though these are not strictly the same.
+# - (4) is used because (2) values are too large and yield negative totals.
+#
+# AIR,      lightoil,  VOC,      0.2209   # (2)    9.5  g/kg “Calculated using Tier 2 method”
+# AIR,      lightoil,  VOC,      0.4419   # (2)   19    g/kg “Calculated using Tier 2 method”
+# AIR,      lightoil,  VOC,      0.8837   # (2)   38    g/kg “Calculated using Tier 2 method”
+AIR,        lightoil,  VOC,      0.013246 # (4)

message_ix_models/project/ssp/transport.py

@@ -157,17 +157,19 @@ def e_UNIT(cl_emission: "sdmx.model.common.Codelist") -> "AnyQuantity":
         Values are everywhere 1.0, except for species such as ``N2O`` that must be
         reported in kt rather than Mt.
     """
+    # Iterate over codes in the codelist
     data = []
     for e in cl_emission:
-        try:
-            label = str(e.get_annotation(id="report").text)
-        except KeyError:
-            label = e.id
-        try:
-            unit = str(e.get_annotation(id="units").text)
-        except KeyError:
-            unit = "Mt"
-        data.append([e.id, f"{unit} {label}/yr", 1.0 if unit == "Mt" else 1e3])
+        # Retrieve info from annotations
+        i = {}
+        for k, default in {"report": e.id, "unit-species": e.id, "units": "Mt"}.items():
+            try:
+                i[k] = str(e.get_annotation(id=k).text)
+            except KeyError:
+                i[k] = default
+
+        scale_factor = 1.0 if i["units"] == "Mt" else 1e3
+        data.append([i["report"], f"{i['units']} {i['unit-species']}/yr", scale_factor])
 
     dims = "e UNIT value".split()
     return genno.Quantity(
@@ -285,9 +287,22 @@ def get_computer(
     # - Update it using the `sc`.
     # - Retrieve a 'label' used to construct a target scenario URL.
     label_full = TransportConfig.from_context(context).use_scenario_code(sc)[1]
-    # - Construct the target scenario URL.
-    # - Use it to update context.core.scenario_info.
+    # Construct the target scenario URL
     url = workflow.scenario_url(context, label_full)
+    # Optionally apply a regex substitution
+    URL_SUB = {
+        "LED-SSP1": ("$", "#102"),  # Point to a specific version
+        "LED-SSP2": ("$", "#108"),
+        "SSP1": ("$", "#652"),
+        "SSP2": ("$", "#695"),
+        "SSP3": ("$", "#569"),
+        "SSP4": ("$", "#525"),
+        "SSP5": ("$", "#522"),  # Other scenario name
+        # "SSP5": ("(SSP_2024.5) baseline$", r"\1 baseline#525"),  # Other scenario name
+    }
+    if pattern_repl := URL_SUB.get(sc.id):
+        url = re.sub(pattern_repl[0], pattern_repl[1], url)
+    # Use the URL to update context.core.scenario_info
     context.handle_cli_args(url=url)
 
     log.info(f"method 'C' will use data from {url}")

message_ix_models/tests/project/ssp/test_transport.py

@@ -1,4 +1,5 @@
 from collections.abc import Callable, Hashable
+from functools import cache
 from typing import TYPE_CHECKING
 
 import numpy as np
@@ -60,13 +61,7 @@ def input_xlsx_path(tmp_path_factory, input_csv_path) -> "pathlib.Path":
 SPECIES = {"CH4", "BC", "CO", "CO2", "N2O", "NH3", "NOx", "OC", "Sulfur", "VOC"}
 
 #: Species for which no aviation-specific emission factor values are available.
-SPECIES_WITHOUT_EF = {
-    "BC",  # No emissions factor data for e=BCA
-    "CO2",
-    "NH3",
-    "OC",  # No emissions factor data for e=OCA
-    "Sulfur",  # No emissions factor data for e=SO2; only SOx
-}
+SPECIES_WITHOUT_EF: set[str] = set()
 
 
 def check(df_in: pd.DataFrame, df_out: pd.DataFrame, method: METHOD) -> None:
@@ -123,10 +118,10 @@ def _to_long(df):
     N_exp = {
         (METHOD.A, False): 10280,
         (METHOD.A, True): 10280,
-        (METHOD.B, False): 5060,
-        (METHOD.B, True): 3860,
-        (METHOD.C, False): 3500,
-        (METHOD.C, True): 3500,
+        (METHOD.B, False): 10120,
+        (METHOD.B, True): 7720,
+        (METHOD.C, False): 7000,
+        (METHOD.C, True): 7000,
     }[(method, iea_eweb_test_data)]
 
     if N_exp != len(df):
@@ -145,6 +140,7 @@ def _to_long(df):
         assert iea_eweb_test_data, msg  # Negative values → fail if NOT using test data
 
 
+@cache
 def expected_variables(flag: int, method: METHOD) -> set[str]:
     """Set of expected ‘Variable’ codes according to `flag` and `method`."""
     # Shorthand