Add #451 to docs, whatsnew

Author: khaeru

doc/api/report/index.rst

@@ -139,13 +139,37 @@ API reference
 .. automodule:: message_ix_models.report
    :members:
 
+   General-purpose code:
+
    .. autosummary::
 
       Config
+      defaults
       prepare_reporter
       register
       report
 
+   The following submodules prepare reporting of specific measures or quantities:
+
+   .. autosummary::
+      :toctree: _autosummary
+      :template: autosummary-module.rst
+      :recursive:
+
+      extraction
+
+.. currentmodule:: message_ix_models.report.key
+
+Keys
+----
+
+.. automodule:: message_ix_models.report.key
+   :members:
+
+   Pre-set :class:`genno.Key` instances
+   and :class:`genno.Keys` in this module can be referenced across modules,
+   instead of hand-typing the same strings in multiple places.
+
 .. currentmodule:: message_ix_models.report.plot
 
 Plots
@@ -167,17 +191,25 @@ Operators
 
    .. autosummary::
 
+      broadcast_wildcard
+      call
       codelist_to_groups
       compound_growth
       exogenous_data
       filter_ts
       from_url
+      get_commodity_groups
       get_ts
       gwp_factors
       make_output_path
       model_periods
+      node_glb
+      nodes_world_agg
       remove_ts
+      select_allow_empty
+      select_expand
       share_curtailment
+      zeros_like
 
    The following functions, defined elsewhere,
    are exposed through :mod:`.operator`
@@ -186,6 +218,8 @@ Operators
    .. autosummary::
 
       message_ix_models.util.add_par_data
+      message_ix_models.util.merge_data
+      message_ix_models.util.nodes_ex_world
 
    Other operators or genno-compatible functions are provided by:
 
@@ -219,6 +253,7 @@ Utilities
 
    .. autosummary::
 
+      IAMCConversion
       add_replacements
       collapse
       collapse_gwp_info

doc/whatsnew.rst

@@ -11,6 +11,11 @@ Next release
   - New method :meth:`~.report.Config.iter_callbacks`.
 
 - New function :func:`.tools.iamc.compare` (:pull:`178`).
+- New module :mod:`.report.extraction` for reporting of resource extraction (:pull:`451`).
+- New reporting operators (:pull:`451`):
+  :func:`.get_commodity_groups`,
+  :func:`.node_glb`, and
+  :func:`.zeros_like`.
 - Expand :doc:`api/report/index` documentation (:pull:`178`)
   to cover features implemented/not implemented by :mod:`genno`-based reporting.
   Module globals :data:`.NOT_IMPLEMENTED_MEASURE` and :data:`.NOT_IMPLEMENTED_IAMC`

message_ix_models/report/__init__.py

@@ -29,6 +29,7 @@
     "NOT_IMPLEMENTED_IAMC",
     "NOT_IMPLEMENTED_MEASURE",
     "Config",
+    "defaults",
     "prepare_reporter",
     "register",
     "report",
@@ -327,6 +328,9 @@ def prepare_reporter(
 ) -> tuple[Reporter, "KeyLike | None"]:
     """Return a :class:`.Reporter` and `key` prepared to report a :class:`.Scenario`.
 
+    Every function returned by :attr:`.Config.iter_callbacks` is called, in order, to
+    allow each to populate the `reporter` with additiona tasks.
+
     Parameters
     ----------
     context : .Context
@@ -342,8 +346,8 @@ def prepare_reporter(
     Returns
     -------
     .Reporter
-        Reporter prepared with MESSAGEix-GLOBIOM calculations; if `reporter` is given,
-        this is a reference to the same object.
+        Reporter prepared with tasks for reporting a MESSAGEix-GLOBIOM scenario; if
+        `reporter` is given, this is a reference to the same object.
 
         If :attr:`.cli_output` is given, a task with the key "cli-output" is added that
         writes the :attr:`.Config.key` to that path.
@@ -430,6 +434,16 @@ def prepare_reporter(
 
 
 def defaults(rep: Reporter, context: Context) -> None:
+    """Prepare default contents and configuration of `rep` for MESSAGEix-GLOBIOM.
+
+    This includes:
+
+    - Populate :data:`.key.coords` and :data:`.key.groups`.
+    - Add a :func:`genno.operator.concat` task with no arguments at
+      :data:`.key.all_iamc`.
+    - Call :func:`.add_replacements` for members of the :ref:`commodity-yaml` and
+      :ref:`technology-yaml` code lists
+    """
     from message_ix_models.model.structure import get_codes
 
     from . import key as k

message_ix_models/report/config.py

@@ -28,6 +28,7 @@ def _default_callbacks() -> list[Callback]:
 
     from . import defaults, extraction
 
+    # NB When updating this list, also update the docstring of Config.callback
     return [defaults, extraction.callback, plot.callback]
 
 
@@ -45,13 +46,17 @@ class Config(ConfigHelper):
     #: Shorthand to set :py:`legacy["use"]` on a new instance.
     _legacy: InitVar[bool | None] = False
 
-    #: List of callbacks for preparing the :class:`.Reporter`.
+    #: List of callback functions for preparing the :class:`.Reporter`.
     #:
     #: Each registered function is called by :func:`~.report.prepare_reporter` in order
     #: to add or modify the task graph. Specific model variants and projects can
-    #: register a callback to extend the reporting graph.
+    #: register a callback to extend the reporting graph. The default list is:
     #:
-    #: Callback functions **must** take two arguments: the Computer/Reporter, and a
+    #: 1. :func:`.report.defaults`
+    #: 2. :func:`.report.extraction.callback`
+    #: 3. :func:`.report.plot.callback`
+    #:
+    #: A callback function **must** take two arguments: the Computer/Reporter, and a
     #: :class:`.Context`:
     #:
     #: .. code-block:: python
@@ -63,7 +68,7 @@ class Config(ConfigHelper):
     #:         # Modify `rep` by calling its methods ...
     #:         pass
     #:
-    #:     # Register this callback on an existing Context instance
+    #:     # Register this callback on an existing Context/report.Config instance
     #:     context.report.register(cb)
     #:
     #: See also :attr:`modules`.
@@ -78,7 +83,7 @@ class Config(ConfigHelper):
     #: Key for the Quantity or computation to report.
     key: "KeyLike | None" = None
 
-    #: Names of modules with reporting callbacks. See also :attr:`callbacks` and
+    #: Names of modules with reporting callbacks. See also :attr:`callback` and
     #: :meth:`iter_callbacks`.
     modules: list[str] = field(default_factory=list)
 
@@ -106,8 +111,8 @@ def iter_callbacks(self) -> Generator[Callback, None, None]:
         """Iterate over callback functions.
 
         1. All module names in :attr:`modules` are passed to :meth:`register`, such that
-           their callback functions are appended to :attr:`callbacks`.
-        2. The :attr:`callbacks` are yielded iteratively.
+           their callback functions are appended to :attr:`callback`.
+        2. The :attr:`callback` are yielded iteratively.
         """
         for name in self.modules:
             self.register(name)

message_ix_models/report/extraction.py

@@ -1,3 +1,5 @@
+"""Report resource extraction."""
+
 from typing import TYPE_CHECKING
 
 from genno import Keys

message_ix_models/report/key.py

@@ -2,20 +2,28 @@
 
 from genno import Key, Keys
 
+#: Gross domestic product.
 GDP = Key("GDP", "ny")
 
-# NB genno ≤ 1.27.1 is sensitive to the order
+#: Commodity price.
+#:
+#:  .. note:: genno ≤ 1.27.1 is sensitive to the dimension order; more recent versions
+#:     are not.
 PRICE_COMMODITY = Key("PRICE_COMMODITY", "nclyh")
 
 #: All IAMC-structured data.
 all_iamc = Key("all", (), "iamc")
 
-#: Identifiers for coordinates.
+#: Identifiers for coordinates, including:
+#:
+#: - :py:`.n_glb`: the output of :func:`.node_glb`.
 coords = Keys(
     n_glb="n::glb",
 )
 
-#: Identifiers for grouping/aggregation mappings.
+#: Identifiers for grouping/aggregation mappings, including:
+#:
+#: - :py:`.c`: the output of :func:`.get_commodity_groups`.
 groups = Keys(
     c="c::groups",
 )