Reporting (:mod:`~.message_ix_models.report`) ********************************************* On this page: .. contents:: :local: Elsewhere: - ``global.yaml``, the :doc:`default-config`. - Documentation for :mod:`genno` (:doc:`genno:index`), :mod:`ixmp.report`, and :mod:`message_ix.report`. - Reporting for specific model variants: - :mod:`.water.reporting` - :doc:`transport/output` of :mod:`.model.transport` - :doc:`‘Legacy’ reporting `. .. toctree:: :hidden: default-config legacy .. _report-intro: Introduction ============ See :doc:`the discussion in the MESSAGEix docs ` about the stack. In short, for instance: - :mod:`message_ix` **must not** contain reporting code that references :py:`technology="coal_ppl"`, because not every model built on the MESSAGE framework will have a technology with this name. - Any model in the MESSAGEix-GLOBIOM family—built with :mod:`message_ix_models` and/or :mod:`message_data`—**should**, with few exceptions, have a :py:`technology="coal_ppl"`, since this appears in the common list of :ref:`technology-yaml`. Reporting specific to this technology ID, *as it is represented* in this model family, should be in :mod:`message_ix_models` or user code. The basic **design pattern** of :mod:`message_ix_models.report` is: - :func:`~.report.prepare_reporter` populates a new :class:`~.message_ix.Reporter` for a given :class:`.Scenario` with many keys to report all quantities of interest in a MESSAGEix-GLOBIOM–family model. - This function relies on *callbacks* defined in multiple submodules to add keys and tasks for general or tailored reporting calculations and actions. Additional modules **should** define callback functions and register them with :func:`~report.register` when they are to be used. For example: 1. The module :mod:`message_ix_models.report.plot` defines :func:`.plot.callback` that adds standard plots to the Reporter. 2. The module :mod:`message_data.model.transport.report` defines :func:`~.message_data.model.transport.report.callback` that adds tasks specific to MESSAGEix-Transport. 3. The module :mod:`message_data.projects.navigate.report` defines :func:`~.message_data.projects.navigate.report.callback` that add tasks specific to the ‘NAVIGATE’ research project. The callback (1) is always registered, because these plots are always applicable and can be expected to function correctly for all models in the family. In contrast, (2) and (3) **should** only be registered and run for the specific model variants for which they are developed/intended. Modules with tailored reporting configuration **may** also be indicated on the :ref:`command line ` by using the :program:`-m/--modules` option: :program:`mix-models report -m model.transport`. - A file :file:`global.yaml` file (in `YAML `_ format) contains a description of some of the reporting computations needed for a MESSAGE-GLOBIOM model. :func:`~.report.prepare_reporter` uses the :doc:`configuration handlers ` built into :mod:`genno` (and some extensions specific to :mod:`message_ix_models`) to handle the different sections of the file. Features ======== By combining these genno, ixmp, message_ix, and message_ix_models features, the following functionality is provided. .. note:: If any of this does not appear to work as advertised, file a bug! Units ----- - Are read automatically for ixmp parameters. - Pass through calculations/are derived automatically. - Are recognized based on the definitions of non-SI units from `IAMconsortium/units `_. - Are discarded when inconsistent. - Can be overridden for entire parameters: .. code-block:: yaml units: apply: inv_cost: USD - Can be set explicitly when converting data to IAMC format: .. code-block:: yaml iamc: # 'value' will be in kJ; 'units' will be the string 'kJ' - variable: Variable Name base: example_var:a-b-c units: kJ API reference ============= .. currentmodule:: message_ix_models.report .. automodule:: message_ix_models.report :members: .. autosummary:: Config prepare_reporter register report .. currentmodule:: message_ix_models.report.plot Plots ----- .. automodule:: message_ix_models.report.plot :members: .. currentmodule:: message_ix_models.report.operator Operators --------- .. automodule:: message_ix_models.report.operator :members: :exclude-members: add_par_data :mod:`message_ix_models.report.operator` provides the following: .. autosummary:: codelist_to_groups compound_growth exogenous_data filter_ts from_url get_ts gwp_factors make_output_path model_periods remove_ts share_curtailment The following functions, defined elsewhere, are exposed through :mod:`.operator` and so can also be referenced by name: .. autosummary:: message_ix_models.util.add_par_data Other operators or genno-compatible functions are provided by: - Upstream packages: - :mod:`message_ix.report.operator` - :mod:`ixmp.report.operator` - :mod:`genno.operator` - Other submodules: - :mod:`.model.emissions`: :func:`.get_emission_factors`. Any of these can be made available for a :class:`.Computer` instance using :meth:`~.genno.Computer.require_compat`, for instance: .. code-block:: # Indicate that a certain module contains functions to # be referenced by name c.require_compat("message_ix_models.model.emissions") # Add computations to the graph by referencing functions c.add("ef:c", "get_emission_factors", units="t C / kWa") Utilities --------- .. currentmodule:: message_ix_models.report.util .. automodule:: message_ix_models.report.util :members: .. autosummary:: add_replacements collapse collapse_gwp_info copy_ts .. currentmodule:: message_ix_models.report.compat Compatibility with :mod:`.report.legacy` ---------------------------------------- .. automodule:: message_ix_models.report.compat :members: :mod:`.report.compat` prepares a Reporter to perform the same calculations as :mod:`.report.legacy`, except using :mod:`genno`. .. warning:: This code is **under development** and **incomplete**. It is not yet a full or exact replacement for :mod:`.report.legacy`. Use with caution. Main API: .. autosummary:: TECH_FILTERS callback prepare_techs get_techs Utility functions: .. autosummary:: inp eff emi out .. _report-cli: Command-line interface ====================== .. currentmodule:: message_ix_models.report.cli .. automodule:: message_ix_models.report.cli :members: .. code-block:: $ mix-models report --help Usage: mix-models report [OPTIONS] [KEY] Postprocess results. KEY defaults to the comprehensive report 'message::default', but may also be the name of a specific model quantity, e.g. 'output'. --config can give either the absolute path to a reporting configuration file, or the stem (i.e. name without .yaml extension) of a file in data/report. With --from-file, read multiple Scenario identifiers from FILE, and report each one. In this usage, --output-path may only be a directory. Options: --dry-run Only show what would be done. --config TEXT Path or stem for reporting config file. [default: global] -L, --legacy Invoke legacy reporting. -m, --module MODULES Add extra reporting for MODULES. -o, --output PATH Write output to file instead of console. --from-file FILE Report multiple Scenarios listed in FILE. --help Show this message and exit. Testing ======= .. currentmodule:: message_ix_models.report.sim .. automodule:: message_ix_models.report.sim :members: Continuous reporting -------------------- As part of the :ref:`test-suite`, reporting is run on the same events (pushes and daily schedule) on publicly-available :doc:`model snapshots `. One goal of these tests *inter alia* is to ensure that adjustments and improvements to the reporting code do not disturb manually-verified model outputs. As part of the (private) :mod:`message_data` test suite, multiple workflows run on regular schedules; some of these include a combination of :mod:`message_ix_models`-based and :ref:`‘legacy’ reporting `. These workflows: - Operate on specific scenarios within IIASA databases. - Create files in CSV, Excel, and/or PDF formats that are that are preserved and made available as 'build artifacts' via the GitHub Actions web interface and API.