Update docs, docstrings for #259; add to whatsnew

Author: khaeru

doc/api/util.rst

@@ -10,10 +10,12 @@ Submodules:
 
    click
    context
+   genno
    importlib
    _logging
    node
    pooch
+   pycountry
    scenarioinfo
    sdmx
 
@@ -158,6 +160,13 @@ Commonly used:
 
       If no base scenario can be loaded, :func:`.bare.create_res` is called to generate a base scenario.
 
+:mod:`.util.genno`
+==================
+
+.. currentmodule:: message_ix_models.util.genno
+
+.. automodule:: message_ix_models.util.genno
+   :members:
 
 :mod:`.util.importlib`
 ======================

doc/project/ssp.rst

@@ -54,3 +54,20 @@ Transport
    :members:
 
    Use :program:`mix-models ssp transport --help in.xlsx out.xlsx` to invoke :func:`.main`.
+   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.
+
+   For example:
+
+   .. code-block:: shell
+
+      mix-models ssp transport --method=B \
+        SSP_SSP2_v2.1_baseline.xlsx
+
+   …produces a file :file:`SSP_SSP2_v2.1_baseline_out.xlsx` in the same directory.
+
+   As of 2025-01-25:
+
+   - 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`.

doc/transport/index.rst

@@ -142,7 +142,7 @@ Run the entire workflow
    The options result in the following behaviour:
 
    - :program:`--platform=ixmp-dev`: store MESSAGEix-Transport scenarios on the :mod:`ixmp` platform named "ixmp-dev".
-   - :program:`--base=auto`: identify the base scenario URLs using :func:`.base_scenario_url` / the file :file:`base-scenario-url.json`, according to other config settings.
+   - :program:`--base=auto`: identify the base scenario URLs using :func:`.base_scenario_url` / the file :ref:`CL_TRANSPORT_SCENARIO`, according to other config settings.
    - :program:`--model-extra="ci nightly"`: append the string " ci nightly" to the model name of any created Scenario.
      This avoids accidentally producing new versions of ‘production’ (model name, scenario name) combinations.
    - :program:`--from=""`: start from the very first step in the workflow—load the identified base scenario—and perform all subsequent workflow steps, up to and including…

doc/transport/input.rst

@@ -20,8 +20,8 @@ This value is retrieved from the :attr:`.model.Config.regions` setting on a :cla
 
 .. _transport-config:
 
-Configuration
-=============
+Configuration and model structure
+=================================
 
 General (:file:`config.yaml`, required)
 ---------------------------------------
@@ -50,13 +50,45 @@ This file gives code lists for other MESSAGE concepts/sets/dimensions.
 
 → View :source:`message_ix_models/data/transport/set.yaml` on GitHub
 
+.. _CL_TRANSPORT_SCENARIO:
+
+Code list ``CL_TRANSPORT_SCENARIO``
+-----------------------------------
+
+This code list, stored in the file :file:`message_ix_models/data/sdmx/IIASA_ECE_CL_TRANSPORT_SCENARIO(1.0.0).xml`, contains an SDMX code list for distinct MESSAGEix-Transport scenarios.
+The codes have IDs like ``LED-SSP1`` that give a short identifier used in :mod:`.transport.workflow` and elsewhere, and names that give a complete, human-readable description.
+Every code has all of following annotations:
+
+``SSP-URN``
+   Complete URN of a code in ``ICONICS:SSP(2024)`` or another code list for the SSP used for sociodemographic input data and to control other settings in :mod:`.transport.build`.
+
+   Example annotation text: ``'urn:sdmx:org.sdmx.infomodel.codelist.Code=ICONICS:SSP(2024).1'``
+
+``is-LED-Scenario``
+   Example annotation text: ``True``
+
+   :func:`repr` of Python :any:`True` or :any:`False`, the former indicating that "Low Energy Demand (LED)" settings should be used.
+   See also :attr:`Config.project <.transport.config.Config.project>`.
+
+``EDITS-activity-id``
+   Example annotation text: ``'HA'``
+
+   For :doc:`/project/edits`, the identity of an ITF PASTA scenario providing exogenous transport activity.
+
+``base-scenario-URL``
+   Example annotation text: ``'ixmp://ixmp-dev/SSP_SSP1_v1.1/baseline_DEFAULT_step_13'``
+
+   URL of a base scenario used to build the corresponding MESSAGEix-Transport scenario.
+
+
 .. _transport-data-files:
 
 Input data files
 ================
 
 :data:`.transport.files.FILES` gives a list of all data files.
-Through :func:`.transport.build.main` (ultimately, :func:`.transport.build.add_exogenous_data`), each of these files is connected to a :class:`genno.Computer` used for model-building, and its contents appear at the key given in the list below.
+Through :func:`.transport.build.main` (ultimately, :func:`.transport.build.add_exogenous_data`), each of these files is connected to a :class:`genno.Computer` used for model-building.
+Its content are available at the corresponding key, which is used as an input for further model-building computations.
 
 .. admonition:: Example
 
@@ -67,9 +99,22 @@ Through :func:`.transport.build.main` (ultimately, :func:`.transport.build.add_e
 Not all files are currently or always used in model-building computations.
 Some submodules of :mod:`~.model.transport` use additional data files via other mechanisms.
 Most of the files have a header comment including a precise description of the quantity, source of the data, and units of measurement.
-In some cases extended information is below (where a header comment would be too long).
+In some cases—where a header comment would be too long—extended information is below.
 The :program:`git` history of files, or the GitHub "blame" view can also be used to inspect the edit history of each file, line by line.
 
+.. _transport-input-emi-intensity:
+
+:file:`emi-intensity.csv` → ``emissions intensity:t-c-e:transport``
+-------------------------------------------------------------------
+
+Measure
+   Emissions intensity of energy use
+Units
+   g (of emissions species) / MJ (of input energy)
+
+See the file :source:`on GitHub <message_ix_models/data/transport/emi-intensity.csv>` for inline comments and commit history.
+Currently only used in :mod:`.ssp.transport`.
+
 :file:`ldv-activity.csv` → ``ldv activity:n:exo``
 -------------------------------------------------
 

doc/whatsnew.rst

@@ -1,8 +1,20 @@
 What's new
 **********
 
-.. Next release
-.. ============
+Next release
+============
+
+- Update :class:`.IEA_EWEB` to support :py:`transform="B"` / :func:`.transform_B` (:issue:`230`, :pull:`259`).
+- Update :doc:`/transport/index` (:pull:`259`).
+
+  - Adjust constraints on :py:`t="conm_ar"`.
+  - Recompute :attr:`.minimum_activity` for transport technologies.
+  - Adjust freight activity, freight and passenger mode shares for some regions.
+  - Drop :file:`base-scenario-url.json`; store base scenario URLs in :ref:`CL_TRANSPORT_SCENARIO`.
+  - Simplify and consolidate tests.
+
+- Add :func:`.prepare_method_B` to :mod:`.ssp.transport` (:pull:`259`).
+- New utility :class:`.sdmx.AnnotationsMixIn` (:pull:`259`).
 
 v2025.1.10
 ==========

message_ix_models/model/transport/files.py

@@ -1,3 +1,8 @@
+"""Input data flows for MESSAGEix-Transport, read from CSV files.
+
+See :ref:`transport-data-files` for documentation of the data flows in :data:`FILES`.
+"""
+
 import logging
 from functools import lru_cache
 from pathlib import Path

message_ix_models/project/ssp/transport.py

@@ -338,17 +338,20 @@ def prepare_method_B(
     1. From the :class:`.IEA_EWEB` 2024 edition, select data for :math:`y = 2019` and
        the :data:`FLOWS`.
     2. Aggregate IEA EWEB to align with MESSAGEix-GLOBIOM |c|.
-    3. Reverse the sign of flow=AVBUNK; these values are negative in the source data.
+    3. Reverse the sign of values for flow=AVBUNK. These are negative in the source
+       data, but their absolute value must be added to values for flow=DOMESAIR.
     4. Compute the ratio :math:`(AVBUNK + DOMESAIR) / TOTTRANS`, the share of aviation
        in final energy.
     5. From the input data (`k_input`), select the values matching :data:`EXPR_FE`, that
        is, final energy use by aviation.
-    6. Load emissions intensity of aviation final energy use :file:`emi-intensity.csv` /
-       :data:`emi_intensity`.
+    6. Load emissions intensity of aviation final energy use from the file
+       :ref:`transport-input-emi-intensity`.
     7. Multiply (4) × (5) × (6) to compute the estimate of
        ``Emissions|*|Energy|Demand|Transportation|Aviation``.
-    8. Subtract (7) from:
-       ``Emissions|*|Energy|Demand|Transportation|Road Rail and Domestic Shipping``.
+    8. Estimate
+       ``Emissions|*|Energy|Demand|Transportation|Road Rail and Domestic Shipping`` as
+       the negative of (7).
+    9. Adjust `k_emi_in` by adding (7) and (8).
     """
     from message_ix_models.model.transport import build
     from message_ix_models.model.transport import files as exo

message_ix_models/types.py

@@ -24,6 +24,8 @@
 
 
 class MaintainableArtefactArgs(TypedDict):
+    """Some keyword arguments to :class:`sdmx.model.common.MaintainableArtefact`."""
+
     is_external_reference: Optional[bool]
     is_final: Optional[bool]
     maintainer: Any

message_ix_models/util/genno.py

@@ -30,7 +30,7 @@ def insert(c: "Computer", key: "KeyLike", operation, tag: str = "pre") -> "KeyLi
 
     It is also possible to insert `operation` that mutates its input in certain ways.
 
-    .. todo:: Migrate to :py:`genno.Computer.insert()`.
+    .. todo:: Migrate to :py:`genno.Computer.insert()` or similar.
 
     Returns
     -------

message_ix_models/util/sdmx.py

@@ -37,6 +37,17 @@ class AnnotationsMixIn:
 
     # TODO Type with overrides: list → list
     def get_annotations(self, _rtype: Union[type[list], type[dict]]):
+        """Return a collection of :class:`.Annotation` for the fields of the object.
+
+        Returns
+        -------
+        list of :class:`Annotation <sdmx.model.common.Annotation>`
+            if `_rtype` is :class:`list`.
+        dict
+            if `_rtype` is :class:`dict`. The dict has the one key "annotations", mapped
+            to a :class:`list` of Annotations. This can be used as a keyword argument
+            to the constructor of a :class:`.AnnotableArtefact` subclass.
+        """
         result = []
         for f in fields(self):
             anno_id = f.name.replace("_", "-")
@@ -51,6 +62,7 @@ def get_annotations(self, _rtype: Union[type[list], type[dict]]):
 
     @classmethod
     def from_obj(cls: type["Self"], obj: common.AnnotableArtefact) -> "Self":
+        """Return a new instance of `cls` given an AnnotableArtefact `obj`."""
         args = []
         for f in fields(cls):
             anno_id = f.name.replace("_", "-")