Add #225 to doc/whatsnew

Author: khaeru

doc/api/util.rst

@@ -101,9 +101,9 @@ Commonly used:
 
    A Context instance always has the following members:
 
-   1. :attr:`core``: an instance of :class:`message_ix_models.Config`.
-   2. :attr:`model``: an instance of :class:`message_ix_models.model.Config`.
-   3. :attr:`report``: an instance of :class:`message_ix_models.report.Config`.
+   1. :attr:`core`: an instance of :class:`message_ix_models.Config`.
+   2. :attr:`model`: an instance of :class:`message_ix_models.model.Config`.
+   3. :attr:`report`: an instance of :class:`message_ix_models.report.Config`.
 
    Attributes of (1) and (2) **may** be accessed by shorthand/aliases.
    For instance, :py:`context.regions` is an alias for :py:`context.model.regions`.
@@ -215,3 +215,11 @@ Commonly used:
 
 .. automodule:: message_ix_models.util.sdmx
    :members:
+
+:mod:`.types`
+=============
+
+.. currentmodule:: message_ix_models.types
+
+.. automodule:: message_ix_models.types
+   :members:

doc/pkg-data/codelists.rst

@@ -25,6 +25,8 @@ These codes have the following annotations:
 .. literalinclude:: ../../message_ix_models/data/commodity.yaml
    :language: yaml
 
+.. _emission-yaml:
+
 Emission species (:file:`emission.yaml`)
 ========================================
 

doc/whatsnew.rst

@@ -7,6 +7,7 @@ Next release
 - :mod:`message_ix_models` is tested and compatible with `Python 3.13 <https://www.python.org/downloads/release/python-3130/>`__ (:pull:`250`).
 - Support for Python 3.8 is dropped (:pull:`250`), as it has reached end-of-life.
 - Expand :doc:`repro` with sections on :ref:`repro-doc` and :ref:`versioning`, including :ref:`a list of external model names and ‘versions’ <model-names>` like “MESSAGEix-GLOBIOM 2.0” (:issue:`224`, :pull:`226`).
+- New code list :ref:`emission-yaml` (:pull:`225`).
 
 By topic:
 
@@ -23,7 +24,23 @@ Materials
 Transport
 ---------
 
-- Update :doc:`/transport/index` (:pull:`213`).
+- Update :doc:`/transport/index` (:pull:`213`, :pull:`225`).
+- Rework :mod:`~.transport.freight`, :mod:`~.transport.ldv`, and :mod:`~.transport.non_ldv` to use :mod:`genno` consistently.
+- Adopt consistent terms "F RAIL" and "F ROAD" for freight service/modes.
+- New technologies: "f rail {electr,lightoil}", "f road electr".
+- Extend unit annotations to all transport commodities.
+- New input :doc:`files </transport/input>` :file:`pdt-cap.csv` and :file:`load-factor-ldv.csv`.
+- Add :program:`mix-models ssp transport` CLI command to postprocess aviation emissions data.
+- New SDMX Codelist ``IIASA:CL_TRANSPORT_SCENARIO`` to distinguish “Low energy demand (LED)” and :doc:`/project/edits` scenarios from :doc:`/project/ssp` baseline scenarios.
+- Adjust R12 baseline settings:
+
+  - :file:`mode-share/default.csv`: adjust ``R12_NAM`` values for AIR and LDV.
+  - :file:`pdt-cap-ref.csv`: adjust ``R12_NAM`` value.
+- Implement LED scenarios via :file:`load-factor-ldv.csv` and :file:`pdt-cap.csv`.
+- Use y=2019 data from IEA EWEB 2024 edition to align MESSAGEix-Transport with base model calibration.
+- New :mod:`genno` operators: :func:`~.transport.operator.broadcast`,  :func:`~.transport.operator.broadcast_wildcard`,  :func:`~.transport.operator.broadcast_t_c_l`, :func:`~.transport.operator.freight_usage_output`.
+- New utility methods :func:`~.transport.config.get_cl_scenario`, :func:`~.transport.util.wildcard`.
+- Replace :class:`DataSourceConfig.LDV <.transport.config.DataSourceConfig>` setting with :attr:`Config.dummy_LDV <.transport.config.Config.dummy_LDV>`.
 
 Water/Nexus
 -----------
@@ -51,6 +68,39 @@ Others
 
 - Add "LED", "SSP4", and "SSP5" as values for the :program:`--ssp=…` option in :func:`.common_params` (:pull:`233`).
 - Add :doc:`/project/circeular` project code and documentation (:pull:`232`).
+- :mod:`.iea.web` handles the 2024 edition and fixed-width file format published by the IEA directly (:pull:`225`).
+
+  - Code lists for the ``COUNTRY``, ``FLOW``, and ``PRODUCT`` concepts are included with :mod:`message_ix_models`.
+  - Add :data:`~.iea.web.COUNTRY_NAME` to map particular labels appearing in these data.
+  - Fuzzed data and tests for this functionality.
+
+- Add :any:`.types.ParameterData` and :any:`.types.MutableParameterData` to type the common internal data structure in which a :class:`dict` maps from MESSAGE parameter names to :mod:`message_ix`-structured :class:`pandas.DataFrame` (:pull:`225`).
+- :class:`message_ix_models.Config`—the “core” configuration class—gains methods specific to its settings (:pull:`225`).
+  These were formerly on :class:`.Context`.
+- :class:`.Context` is no longer a subclass of :class:`dict` (:pull:`225`).
+  This avoids its mishandling by :mod:`dask` version 2024.11.0 or later when Context is used with :class:`ixmp.Reporter`.
+
+  - Add :data:`.MODULE_WITH_CONFIG_DATACLASS`;
+    add attributes such as :attr:`.Context.model` that are typed to the respective class such as :class:`.model.Config`.
+  - Add :meth:`.Context.asdict` for serialization.
+  - Former methods such as :meth:`.Context.get_scenario` are aliased to their new locations, e.g. :meth:`.Config.get_scenario`.
+
+- Improve :class:`.ScenarioInfo` (:pull:`225`):
+
+  - Implement the :py:`|` (logical OR/union) operator: `si_a | si_b` is a new ScenarioInfo instance with the union of the contents of the operands.
+  - New method :meth:`.substitute_codes` to replace string codes (for instance, determined from a Scenario object) with Codes from the corresponding code list, including all annotations.
+
+- :class:`.MappingAdapter` skips missing labels in the input data without raising an exception (:pull:`225`).
+- :meth:`.Workflow.visualize` displays in left-to-right rank direction by default (:pull:`225`).
+- :func:`.convert_units` can handle MESSAGE-scheme :class:`pandas.DataFrame` (:pull:`225`).
+- :func:`.util.sdmx.make_enum` uses :class:`.URNLookupEnum` by default (:pull:`225`).
+  This allows to call, for instance, :py:`SSP_2024.by_urn("…Code=ICONICS:SSP(2024).2")` to retrieve an enumeration number.
+- :func:`.make_matched_dfs` accepts :class:`dict` for its :py:`par_value` arg, allowing replacement of values for particular dimensions of output data frames (:pull:`225`).
+- New reporting operator :func:`.quantity_from_iamc` (:pull:`225`).
+- :func:`.same_node` and :func:`.same_time` can handle :any:`.ParameterData` (:pull:`225`).
+- :func:`.report.register` becomes :meth:`.report.Config.register` which populates :attr:`.report.Config.callback` (:pull:`225`).
+  The set of callback functions used to configure a class:`.Reporter` instance is thus now particular to a :class:`.report.Config` instance attached to a :class:`.Context` instance.
+  This allows better isolation of code/tests that use different sets of callbacks.
 
 v2024.8.6
 =========

message_ix_models/project/ssp/structure.py

@@ -183,5 +183,8 @@ def generate(context: "Context", base_dir: Optional["PathLike"] = None):
         write(cl, base_dir)
 
 
+#: Enumeration of codes for SSP 2017 edition.
 SSP = SSP_2017 = make_enum("ICONICS:SSP(2017)")
+
+#: Enumeration of codes for SSP 2024 edition.
 SSP_2024 = make_enum("ICONICS:SSP(2024)")

message_ix_models/report/config.py

@@ -59,13 +59,13 @@ class Config(ConfigHelper):
     #:
     #:     from message_ix.report import Reporter
     #:     from message_ix_models import Context
-    #:     from message_ix_models.report import register
     #:
     #:     def cb(rep: Reporter, ctx: Context) -> None:
     #:         # Modify `rep` by calling its methods ...
     #:         pass
     #:
-    #: context.report.register(cb)
+    #:     # Register this callback on an existing Context instance
+    #:     context.report.register(cb)
     callback: list[Callback] = field(default_factory=_default_callbacks)
 
     #: Path to write reporting outputs when invoked from the command line.

message_ix_models/report/operator.py

@@ -38,6 +38,7 @@
     "make_output_path",
     "model_periods",
     "nodes_ex_world",
+    "quantity_from_iamc",
     "remove_ts",
     "share_curtailment",
 ]

message_ix_models/util/context.py

@@ -181,14 +181,17 @@ def set(self, key: str, value: Any) -> None:
     # These SHOULD include all the keys from MODULE_WITH_CONFIG_DATACLASS
     @property
     def core(self) -> "message_ix_models.util.config.Config":
+        """An instance of :class:`.util.config.Config`."""
         return self._values["core"]
 
     @property
     def model(self) -> "message_ix_models.model.config.Config":
+        """An instance of :class:`.model.config.Config`."""
         return self._values["model"]
 
     @property
     def report(self) -> "message_ix_models.report.config.Config":
+        """An instance of :class:`.report.config.Config`."""
         return self._values["report"]
 
     # Dict-like behaviour