‘Legacy’ reporting (report.legacy)

report.legacy contains ‘legacy’ reporting code transferred from message_data ().

This code:

• is only tested to run against the global model snapshot, specifically snapshot ID 1. This implies that the outputs—specific numerical values, labels, etc.—of the code are not tested or validated in any way. Users of the code should carefully validate output data, especially when the code is run against any scenario other than snapshot 1.

• is provided primarily for reference by users of snapshot 1.

• is not currently used in IIASA ECE program workflows or publications. As of 2024-04-04, all MESSAGEix-GLOBIOM outputs that appear in public and closed databases, associated with peer-reviewed works, etc. have been produced with other code from various branches of message_data.

• predates genno and the stack of tools built on it (described here); these were designed to avoid issues with performance and extensibility in the older code. [1] It is intended that report will eventually replace report.legacy, which in the meantime serves as a reference for that code (such as report.compat).

[1]

See a (non-public) “Reporting” project board on GitHub for details of the initial implementation of these features.

Usage

Set report.Config.legacy to include use=True and any other keyword arguments to iamc_report_hackathon.report(), then call message_ix_models.report.report():

from message_ix_models import Context
from message_ix_models.report import Config, report

# Configure to use .report.legacy
context = Context.get_instance()
context.report.legacy.update(
    use=True,
    # Only this exact set of keyword arguments is
    # tested and known to work:
    merge_hist=True,
    ref_sol="True",
    run_config="ENGAGE_SSP2_v417_run_config.yaml",
)

# Invoke
report(context)

Or, call iamc_report_hackathon.report() directly.

Reference

message_ix_models.report.legacy.iamc_report_hackathon.report(mp, scen, ref_sol=False, model_out=None, scenario_out=None, out_dir=None, merge_hist=False, merge_ts=False, aggr_def=None, var_def=None, unit_yaml=None, run_config=None, urban_perc=None, kyoto_hist=None, lu_hist=None, verbose=False, *, context: Context | None = None)

Main reporting function.

This function will run reporting for specific “tables” as specified in the configuration file run_config.

Outputs will be stored as an xlsx file in IAMC format for upload to a scenario database/explorer instance.

IMPORTANT!! If extending the variable template, please ensure NOT to overwrite the existing file as this is used for global model intercomparison projects.

Only variables defined in the variable template are reported. All other variables will be excluded.

Parameters:

• mp (ixmp.Platform) – Database connection where scenario object is located.

• scen (message_ix.Scenario) – Scenario object for which reporting should be run.

• ref_sol (boolean (default: False)) – Option whether to process historical results or optimization results.

• model_out (str (default: None)) – Model name of the scenario in the output file.

• scenario_out (str (default: None)) – Scenario name of the scenario in the output file.

• out_dir (str (default: None)) – Directory where the result file should be written to.

• merge_hist (boolean (default: False)) – Switch to determine whether the reporting results should be merged with already processed histroical results, which are then, additionally, stored as Timeseries with the scenario object.

• merge_ts (boolean (default: False)) – Switch to use data stored as TS to overwrite results from reporting.

• var_def (str (default: None)) – Name of file to be used to define allowed variables.

• aggr_def (str (default=None)) – Name of file to be used to define aggregate mapping.

• unit_yaml (str (default: None)) – Directory incl file name of unit conversion factors from model units to output units.

• run_config (str (default: None)) – Directory incl file name of which reporting tables are to be run.

• urban_perc (str (default: None)) – Regional urban shares in %.

• kyoto_hist (str (default: None)) – Historic Kyoto Gas emissions excl. land-use emissions for regions.

• lu_hist (str (default: None)) – Historic land-use GHG emissions for regions.

• verbose (str (default: False)) – Option whther to print onscreen messages.

• context (Context) – Only the dry_run setting is respected. If True, configuration is read, but nothing is done.