Add #325 to doc/whatsnew

Author: khaeru

doc/project/ssp.rst

@@ -72,18 +72,21 @@ Transport
    1. To process data from file, use :program:`mix-models ssp transport --help in.xlsx out.xlsx` to invoke :func:`.process_file`.
       Data are read from PATH_IN, in :file:`.xlsx` or :file:`.csv` format.
       If :file:`.xlsx`, the data are first temporarily converted to :file:`.csv`.
-      Data are written to PATH_OUT; if not given, this defaults to the same path and suffix as PATH_IN, with "_out" added to the stem.
+      Data are written to PATH_OUT;
+      if not given, this defaults to the same path and suffix as PATH_IN with "_out" added to the stem.
 
       For example:
 
       .. code-block:: shell
 
-         mix-models ssp transport --method=B \
+         mix-models --platform=ixmp-dev \
+           ssp transport --method=C \
            SSP_SSP2_v2.1_baseline.xlsx
 
       …produces a file :file:`SSP_SSP2_v2.1_baseline_out.xlsx` in the same directory.
 
-   2. To process an existing :class:`pandas.DataFrame` from other code, call :func:`.process_df`, passing the input dataframe and the `method` parameter.
+   2. To process an existing :class:`pandas.DataFrame` from other code, call :func:`.process_df`,
+      passing the input dataframe and the `method` parameter.
 
    As of 2025-03-07 / :pull:`309`, the set of required "variable" codes handled includes::
 
@@ -92,15 +95,13 @@ Transport
        Emissions|.*|Energy|Demand|Transportation
        Emissions|.*|Energy|Demand|Transportation|Road Rail and Domestic Shipping
 
-   The previous set is no longer supported.
-
-   As of 2025-01-25:
-
-   - The set of "variable" codes modified includes::
+   The previous set, supported as of 2025-01-25 but no longer supported, included::
 
        Emissions|.*|Energy|Demand|Transportation|Aviation
        Emissions|.*|Energy|Demand|Transportation|Aviation|International
        Emissions|.*|Energy|Demand|Transportation|Road Rail and Domestic Shipping
 
-   - Method 'B' (that is, :func:`.prepare_method_B`; see its documentation) is the preferred method.
-   - The code is tested on :file:`.xlsx` files in the (internal) directories under `SharePoint > ECE > Documents > SharedSocioeconomicPathways2023 > Scenario_Vetting <https://iiasahub.sharepoint.com/sites/eceprog/Shared%20Documents/Forms/AllItems.aspx?csf=1&web=1&e=APKv0Z&CID=23fa0a51%2Dc303%2D4381%2D8c6d%2D143305cbc5a1&FolderCTID=0x012000AA9481BF7BE9264E85B14105F7F082FF&id=%2Fsites%2Feceprog%2FShared%20Documents%2FSharedSocioEconomicPathways2023%2FScenario%5FVetting&viewid=956acd8a%2De1e7%2D4ae9%2Dab1b%2D0506911bae11>`_, for example :file:`v2.1_Internal_version_Dec13_2024/Reporting_output/SSP_SSP2_v2.1_baseline.xlsx`.
+   - Method 'C' (that is, :func:`.method_C`; see its documentation) is the preferred method.
+   - The code is tested on :file:`.xlsx` files in the (internal) directories under `SharePoint > ECE > Documents > SharedSocioeconomicPathways2023 > Scenario_Vetting <https://iiasahub.sharepoint.com/sites/eceprog/Shared%20Documents/Forms/AllItems.aspx?csf=1&web=1&e=APKv0Z&CID=23fa0a51%2Dc303%2D4381%2D8c6d%2D143305cbc5a1&FolderCTID=0x012000AA9481BF7BE9264E85B14105F7F082FF&id=%2Fsites%2Feceprog%2FShared%20Documents%2FSharedSocioEconomicPathways2023%2FScenario%5FVetting&viewid=956acd8a%2De1e7%2D4ae9%2Dab1b%2D0506911bae11>`_,
+     for example :file:`v2.1_Internal_version_Dec13_2024/Reporting_output/SSP_SSP2_v2.1_baseline.xlsx`
+     or :file:`v2.3_v2.4_Submission_Mar01_2025/Scenario_Reporting_Files/SSP_LED_v2.3.1_baseline.xlsx`

doc/whatsnew.rst

@@ -44,7 +44,8 @@ SSP :ref:`ssp-2024`/ScenarioMIP
 
 Improve :mod:`.ssp.transport`:
 
-- Add :func:`.prepare_method_B` and make this the default (:pull:`259`).
+- Add :func:`~.ssp.transport.method_B` and make this the default (:pull:`259`).
+- Add :func:`~.ssp.transport.method_C` (:issue:`305`, :pull:`325`).
 - Add :func:`~.ssp.transport.process_df` (:pull:`303`).
 - Adapt to revised ‘variable’ codes (:pull:`309`, :issue:`304`).
 

message_ix_models/project/ssp/transport.py

@@ -28,13 +28,13 @@
 #: Dimensions of several quantities.
 DIMS = "e n t y UNIT".split()
 
-#: Expression used to extract :math:`(e, t)` dimension coordinates from variable codes
-#: in :func:`v_to_emi_coords`.
+#: Expression used to select and extract :math:`(e, t)` dimension coordinates from
+#: variable codes in :func:`v_to_emi_coords`.
 EXPR_EMI = re.compile(
     r"^Emissions\|(?P<e>[^\|]+)\|Energy\|Demand\|(?P<t>(Bunkers|Transportation).*)$"
 )
-#: Expression used to extract :math:`(c)` dimension coordinates from variable codes in
-#: :func:`v_to_fe_coords`.
+#: Expression used to select and extract :math:`(c)` dimension coordinates from variable
+#: codes in :func:`v_to_fe_coords`.
 EXPR_FE = re.compile(r"^Final Energy\|Transportation\|(?P<c>Liquids\|Oil)$")
 
 #: Keywords for :func:`.iamc_like_data_for_query` / :func:`.to_quantity`.
@@ -321,8 +321,8 @@ def get_computer(
 def get_scenario_code(model_name: str, scenario_name: str) -> "sdmx.model.common.Code":
     """Return a specific code from ``CL_TRANSPORT_SCENARIO``.
 
-    This function handles (`model_name`, `scenario_name`) combinations seen in base
-    model outputs as of 2025-04-02.
+    See :func:`.get_cl_scenario`. This function handles (`model_name`, `scenario_name`)
+    combinations seen in base model outputs as of 2025-04-02.
     """
     from message_ix_models.model.transport.config import get_cl_scenario
 
@@ -371,9 +371,9 @@ def method_B(c: "Computer") -> None:
     """Prepare calculations up to :data:`K.emi` using :data:`METHOD.B`.
 
     This method uses the |y0| share of aviation in total transport final energy as
-    indicated by :class:`.IEA_EWEB` (with dimensions :math:`(c, n)`) to disaggregate
-    total final energy from the input data, then applies emission factors to compute
-    aviation emissions.
+    indicated by :class:`.IEA_EWEB`, with dimensions :math:`(c, n)`, to disaggregate
+    total final energy from the input data, then applies emission intensity data to
+    compute aviation emissions.
 
     Excluding data transformations, units, and other manipulations for alignment:
 
@@ -505,7 +505,7 @@ def method_C(c: "Computer") -> None:
     """Prepare calculations up to :data:`K.emi` using :data:`METHOD.C`.
 
     This method uses a solved MESSAGEix-Transport scenario to compute the share of
-    aviation in total transport final energy (with dimensions :math:`(c, n, y)`), and
+    aviation in total transport final energy, with dimensions :math:`(c, n, y)`, and
     the proceeds similarly to :func:`method_B`.
 
     Excluding data transformations, units, and other manipulations for alignment: