Postprocessing and reporting

The MESSAGEix framework provides zero-configuration reporting of models built on the framework. The word “reporting” refers to calculations and other post-processing performed after a Scenario has been solved by the associated optimization model: first the model solution is obtained, and then things are “reported” based on that solution.

message_ix.reporting is developed on the basis of ixmp.reporting and genno. It provides a basis for other code and packages—such as message_ix_models—that perform reporting calculations tailored to specific model structures. Each layer of this “stack” builds on the features in the level below:

Package

Role

Core features

Reporting features

message_ix_models

MESSAGEix-GLOBIOM models

Specific model structure (coal_ppl in t)

Calculations for specific technologies

message_ix

Energy model framework

Common sets/parameters (output)

Derived quantities (tom)

ixmp

Optimization models & data

Scenario with sets, parameters, variables

Reporter auto-populated with sets etc.

genno

Structured calculations

Computer, Key, Quantity

These features are accessible through Reporter, which can produce multiple reports from one or more Scenarios. A report is identified by a key (usually a string), and may…

  • perform arbitrarily complex calculations while intelligently handling units;

  • read and make use of data that is ‘exogenous’ to (not included in) a Scenario;

  • produce output as Python or R objects (in code), or to files or databases;

  • calculate only a requested subset of quantities; and

  • much, much more!

Contents:

Concepts

See Concepts and usage in the genno documentation for an introduction to concepts including quantity, key, computation, task, and graph. In message_ix.reporting:

  • The message_ix.Reporter class is an extended version of the genno.Computer class.

  • ixmp parameters, scalars, equations, and time-series data all become quantities for the purpose of reporting.

  • For example, the MESSAGEix parameter resource_cost, defined with the dimensions (node n, commodity c, grade g, year y) is identified by the key resource_cost:n-c-g-y. When summed across the grade/g dimension, it has dimensions n, c, y and is identified by the key resource_cost:n-c-y.

  • Reporter.from_scenario() automatically sets up keys and tasks (such as resource_cost:n-c-g-y) that simply retrieve raw/unprocessed data from a Scenario and return it as a genno.Quantity.

  • Computations are defined as functions in modules including: message_ix.reporting.computations, ixmp.reporting.computations, and genno.computations. These are documented below.

Usage

A MESSAGEix reporting workflow has the following steps:

  1. Obtain a Scenario object from an Platform.

  2. Use Reporter.from_scenario() to prepare a Reporter object with many calculations automatically prepared.

  3. (optionally) Use the built-in features of Reporter to describe additional calculations.

  4. Use get() 1 or more times to execute tasks, including all the calculations on which they depend:

from ixmp import Platform
from message_ix import Scenario, Reporter

mp = Platform()
scen = Scenario(scen)
rep = Reporter.from_scenario(scen)
rep.get("all")

Note that keys and tasks are described in steps (2–3), but they are not executed until get() is called—or the results of one task are required by another. This design allows the Reporter to skip unneeded (and potentially slow) computations and deliver good performance. The Reporter’s Computer.graph may contain thousands of tasks for retrieving model quantities and calculating derived quantities, but a particular call to get() may only execute a few of these.

Customization

A Reporter prepared with from_scenario() always contains a key scenario, referring to the Scenario to be reported.

The method Reporter.add() can be used to add arbitrary Python code that operates directly on the Scenario object:

def my_custom_report(scenario):
    """Function with custom code that manipulates the `scenario`."""
    print("Model name:", scenario.model)

# Add a task at the key "custom". The task executes my_custom_report().
# The key "scenario" means that the Scenario object is retrieved and
# passed as an argument to the function.
rep.add("custom", (my_custom_report, "scenario"))
rep.get("custom")

In this example, the function my_custom_report() could run to thousands of lines; read to and write from multiple files; invoke other programs or Python scripts; etc. In order to take advantage of the performance-optimizing features of the Reporter, such calculations can instead be composed from atomic (i.e. small, indivisible) computations. See the genno documentation for more.

API reference

Top-level classes and functions

message_ix.reporting provides:

Reporter(**kwargs)

MESSAGEix Reporter.

The following objects from genno may also be imported from message_ix.reporting. Their documentation is repeated below for convenience.

ComputationError(exc)

Wrapper to print intelligible exception information for Computer.get().

Key(name[, dims, tag])

A hashable key for a quantity that includes its dimensionality.

KeyExistsError

Raised by Computer.add() when the target key exists.

MissingKeyError

Raised by Computer.add() when a required input key is missing.

Quantity(*args, **kwargs)

A sparse data structure that behaves like xarray.DataArray.

configure([path])

Configure genno globally.

ixmp.Reporter.from_scenario automatically adds keys based on the contents of the Scenario argument. message_ix.Reporter.from_scenario extends this to add additional keys for derived quantities specific to the MESSAGEix model framework. These include:

  • out - output × ACT; that is, the product of output (output efficiency) and ACT (activity)

  • out_hist = output × ref_activity (historical reference activity)

  • in = input × ACT

  • in_hist = input × ref_activity

  • emi = emission_factor × ACT

  • emi_hist = emission_factor × ref_activity

  • inv = inv_cost × CAP_NEW

  • inv_hist = inv_cost × ref_new_capacity

  • fom = fix_cost × CAP

  • fom_hist = fix_cost × ref_capacity

  • vom = var_cost × ACT

  • vom_hist = var_cost × ref_activity

  • tom = fom + vom

  • land_out = land_output × LAND

  • land_use_qty = land_use × LAND

  • land_emi = land_emission × LAND

  • addon conversion, the model parameter addon_conversion (note space versus underscore), except broadcast across individual add-on technologies (ta) rather than add-on types (type_addon).

  • addon up, which is addon_up similarly broadcast.

  • addon ACT = addon conversion × ACT

  • addon in = input × addon ACT

  • addon out = output × addon ACT

  • addon potential = addon up × addon ACT, the maximum potential activity by add-on technology.

  • price emission, the model variable PRICE_EMISSION broadcast across emission species (e) and technologies (t) rather than types (type_emission, type_tec).

Tip

Use full_key() to retrieve the full-dimensionality Key for any of these quantities.

Other added keys include:

  • message_ix adds the standard short symbols for MESSAGEix dimensions (sets) based on DIMS. Each of these is also available in a Reporter: for example rep.get("n") returns a list with the elements of the MESSAGEix set named “node”. These keys can be used as input

  • Computations to convert internal Quantity() data format to the IAMC data format, i.e. as pyam.IamDataFrame objects. These include:

    • <name>:pyam for most of the above derived quantities.

    • CAP:pyam (from CAP)

    • CAP_NEW:pyam (from CAP_NEW)

  • map_<name> as “one-hot” or indicator quantities for the respective MESSAGEix mapping sets cat_<name>.

  • Standard reports message:system, message:costs, and message:emissions per REPORTS.

  • The report message:default, collecting all of the above reports.

These automatic contents are prepared using:

DERIVED

Automatic quantities derived by other calculations.

DIMS

Short names for dimensions (sets) in the MESSAGEix framework.

MAPPING_SETS

MESSAGE mapping sets, converted to reporting quantities via map_as_qty().

PRODUCTS

Automatic quantities that are the product() of two others.

PYAM_CONVERT

Quantities to automatically convert to IAMC format using as_pyam().

REPORTS

Automatic reports that concat() quantities converted to IAMC format.

class message_ix.reporting.Reporter(**kwargs)

Bases: ixmp.reporting.reporter.Reporter

MESSAGEix Reporter.

add(data, *args, **kwargs)

General-purpose method to add computations.

add_file(path[, key])

Add exogenous quantities from path.

add_product(key, *quantities[, sums])

Add a computation that takes the product of quantities.

add_queue(queue[, max_tries, fail])

Add tasks from a list or queue.

add_single(key, *computation[, strict, index])

Add a single computation at key.

aggregate(qty, tag, dims_or_groups[, ...])

Add a computation that aggregates qty.

apply(generator, *keys, **kwargs)

Add computations by applying generator to keys.

check_keys(*keys[, action, _permute])

Check that keys are in the Computer.

configure([path, fail])

Configure the Computer.

convert_pyam(quantities[, tag])

Add conversion of one or more quantities to IAMC format.

describe([key, quiet])

Return a string describing the computations that produce key.

disaggregate(qty, new_dim[, method, args])

Add a computation that disaggregates qty using method.

finalize(scenario)

Prepare the Reporter to act on scenario.

from_scenario(scenario, **kwargs)

Create a Reporter by introspecting scenario.

full_key(name_or_key)

Return the full-dimensionality key for name_or_key.

get([key])

Execute and return the result of the computation key.

infer_keys(key_or_keys[, dims])

Infer complete key_or_keys.

keys()

Return the keys of graph.

set_filters(**filters)

Apply filters ex ante (before computations occur).

visualize(filename, **kwargs)

Generate an image describing the Computer structure.

write(key, path)

Write the result of key to the file path.

add(data, *args, **kwargs)

General-purpose method to add computations.

add() can be called in several ways; its behaviour depends on data; see below. It chains to methods such as add_single(), add_queue(), and/or apply(); each can also be called directly.

Returns

Some or all of the keys added to the Computer.

Return type

list of Key-like

add_aggregate(qty, tag, dims_or_groups, weights=None, keep=True, sums=False)

Add a computation that aggregates qty.

Parameters
  • qty (Key or str) – Key of the quantity to be aggregated.

  • tag (str) – Additional string to add to the end the key for the aggregated quantity.

  • dims_or_groups (str or iterable of str or dict) – Name(s) of the dimension(s) to sum over, or nested dict.

  • weights (xarray.DataArray, optional) – Weights for weighted aggregation.

  • keep (bool, optional) – Passed to computations.aggregate.

  • sums (bool, optional) – Passed to add().

Returns

The key of the newly-added node.

Return type

Key

add_as_pyam(quantities, tag='iamc', **kwargs)

Add conversion of one or more quantities to IAMC format.

Parameters
  • quantities (str or Key or list of (str, Key)) – Keys for quantities to transform.

  • tag (str, optional) – Tag to append to new Keys.

  • kwargs – Any keyword arguments accepted by as_pyam().

Returns

Each task converts a Quantity into a pyam.IamDataFrame.

Return type

list of Key

See also

as_pyam

add_file(path, key=None, **kwargs)

Add exogenous quantities from path.

Computing the key or using it in other computations causes path to be loaded and converted to Quantity.

Parameters
  • path (os.PathLike) – Path to the file, e.g. ‘/path/to/foo.ext’.

  • key (str or Key, optional) – Key for the quantity read from the file.

  • dims (dict or list or set) – Either a collection of names for dimensions of the quantity, or a mapping from names appearing in the input to dimensions.

  • units (str or pint.Unit) – Units to apply to the loaded Quantity.

Returns

Either key (if given) or e.g. file:foo.ext based on the path name, without directory components.

Return type

Key

add_load_file(path, key=None, **kwargs)

Add exogenous quantities from path.

Computing the key or using it in other computations causes path to be loaded and converted to Quantity.

Parameters
  • path (os.PathLike) – Path to the file, e.g. ‘/path/to/foo.ext’.

  • key (str or Key, optional) – Key for the quantity read from the file.

  • dims (dict or list or set) – Either a collection of names for dimensions of the quantity, or a mapping from names appearing in the input to dimensions.

  • units (str or pint.Unit) – Units to apply to the loaded Quantity.

Returns

Either key (if given) or e.g. file:foo.ext based on the path name, without directory components.

Return type

Key

add_product(key, *quantities, sums=True)

Add a computation that takes the product of quantities.

Parameters
  • key (str or Key) – Key of the new quantity. If a Key, any dimensions are ignored; the dimensions of the product are the union of the dimensions of quantities.

  • sums (bool, optional) – If True, all partial sums of the new quantity are also added.

Returns

The full key of the new quantity.

Return type

Key

add_queue(queue: Iterable[Tuple[Tuple, Mapping]], max_tries: int = 1, fail: Optional[Union[str, int]] = None) Tuple[Union[genno.core.key.Key, Hashable], ...]

Add tasks from a list or queue.

Parameters
  • queue (iterable of 2-tuple) – The members of each tuple are the arguments (e.g. list or tuple) and keyword arguments (e.g dict) to add().

  • max_tries (int, optional) – Retry adding elements up to this many times.

  • fail (“raise” or str or logging level, optional) – Action to take when a computation from queue cannot be added after max_tries: “raise” an exception, or log messages on the indicated level and continue.

add_single(key, *computation, strict=False, index=False)

Add a single computation at key.

Parameters
  • key (str or Key or hashable) – A string, Key, or other value identifying the output of computation.

  • computation (object) – Any computation. See graph.

  • strict (bool, optional) – If True, key must not already exist in the Computer, and any keys referred to by computation must exist.

  • index (bool, optional) – If True, key is added to the index as a full-resolution key, so it can be later retrieved with full_key().

Raises
  • KeyExistsError – If strict is True and either (a) key already exists; or (b) sums is True and the key for one of the partial sums of key already exists.

  • MissingKeyError – If strict is True and any key referred to by computation does not exist.

aggregate(qty, tag, dims_or_groups, weights=None, keep=True, sums=False)

Add a computation that aggregates qty.

Parameters
  • qty (Key or str) – Key of the quantity to be aggregated.

  • tag (str) – Additional string to add to the end the key for the aggregated quantity.

  • dims_or_groups (str or iterable of str or dict) – Name(s) of the dimension(s) to sum over, or nested dict.

  • weights (xarray.DataArray, optional) – Weights for weighted aggregation.

  • keep (bool, optional) – Passed to computations.aggregate.

  • sums (bool, optional) – Passed to add().

Returns

The key of the newly-added node.

Return type

Key

apply(generator, *keys, **kwargs)

Add computations by applying generator to keys.

Parameters
  • generator (callable) – Function to apply to keys.

  • keys (hashable) – The starting key(s).

  • kwargs – Keyword arguments to generator.

cache(func)

Decorate func so that its return value is cached.

See also

Caching

check_keys(*keys: Union[str, genno.core.key.Key], action='raise', _permute=True) Optional[List[Union[str, genno.core.key.Key]]]

Check that keys are in the Computer.

If any of keys is not in the Computer and action is “raise” (the default) KeyError is raised. Otherwise, a list is returned with either the key from keys, or the corresponding full_key().

If action is “return” (or any other value), None is returned on missing keys.

configure(path: Optional[Union[pathlib.Path, str]] = None, fail: Union[str, int] = 'raise', **config)

Configure the Computer.

Accepts a path to a configuration file and/or keyword arguments. Configuration keys loaded from file are superseded by keyword arguments. Messages are logged at level logging.INFO if config contains unhandled sections.

See Configuration for a list of all configuration sections and keys, and details of the configuration file format.

Parameters
  • path (Path, optional) – Path to a configuration file in JSON or YAML format.

  • fail (“raise” or str or logging level, optional) – Passed to add_queue(). If not “raise”, then log messages are generated for config handlers that fail. The Computer may be only partially configured.

  • **config – Configuration keys/sections and values.

convert_pyam(quantities, tag='iamc', **kwargs)

Add conversion of one or more quantities to IAMC format.

Parameters
  • quantities (str or Key or list of (str, Key)) – Keys for quantities to transform.

  • tag (str, optional) – Tag to append to new Keys.

  • kwargs – Any keyword arguments accepted by as_pyam().

Returns

Each task converts a Quantity into a pyam.IamDataFrame.

Return type

list of Key

See also

as_pyam

describe(key=None, quiet=True)

Return a string describing the computations that produce key.

If key is not provided, all keys in the Computer are described.

Unless quiet, the string is also printed to the console.

Returns

Description of computations.

Return type

str

disaggregate(qty, new_dim, method='shares', args=[])

Add a computation that disaggregates qty using method.

Parameters
  • qty (hashable) – Key of the quantity to be disaggregated.

  • new_dim (str) – Name of the new dimension of the disaggregated variable.

  • method (callable or str) – Disaggregation method. If a callable, then it is applied to var with any extra args. If a string, then a method named ‘disaggregate_{method}’ is used.

  • args (list, optional) – Additional arguments to the method. The first element should be the key for a quantity giving shares for disaggregation.

Returns

The key of the newly-added node.

Return type

Key

finalize(scenario: ixmp.core.scenario.Scenario) None

Prepare the Reporter to act on scenario.

The TimeSeries (i.e. including ixmp.Scenario and message_ix.Scenario) object scenario is stored with the key 'scenario'. All subsequent processing will act on data from this Scenario.

classmethod from_scenario(scenario, **kwargs)

Create a Reporter by introspecting scenario.

Warnings are logged if scenario does not have a solution. In this case, any keys/computations based on model output (ixmp variables and equations) may return an empty Quantity, fail, or behave unpredictably. Keys/computations based only on model input (ixmp sets and parameters) should function normally.

Returns

A reporter for scenario.

Return type

message_ix.reporting.Reporter

full_key(name_or_key)

Return the full-dimensionality key for name_or_key.

An quantity ‘foo’ with dimensions (a, c, n, q, x) is available in the Computer as 'foo:a-c-n-q-x'. This Key can be retrieved with:

c.full_key("foo")
c.full_key("foo:c")
# etc.
get(key=None)

Execute and return the result of the computation key.

Only key and its dependencies are computed.

Parameters

key (str, optional) – If not provided, default_key is used.

Raises

ValueError – If key and default_key are both None.

get_comp(name) Optional[Callable]

Return a computation function.

get_comp() checks each of the modules for a function or callable with the given name. Modules at the end of the list take precedence over those earlier in the lists.

Returns

  • .callable

  • None – If there is no computation with the given name in any of modules.

infer_keys(key_or_keys, dims=[])

Infer complete key_or_keys.

Parameters

dims (list of str, optional) – Drop all but these dimensions from the returned key(s).

keys()

Return the keys of graph.

require_compat(pkg: str)

Load computations from genno.compat.{pkg} for use with get_comp().

The specified module is appended to modules.

Raises

ModuleNotFoundError – If the required packages are missing.

See also

get_comp

set_filters(**filters) None

Apply filters ex ante (before computations occur).

See the description of filters() under Configuration.

property unit_registry

The pint.UnitRegistry() used by the Computer.

visualize(filename, **kwargs)

Generate an image describing the Computer structure.

This is a shorthand for dask.visualize(). Requires graphviz.

write(key, path)

Write the result of key to the file path.

message_ix.reporting.DERIVED = [('tom:nl-t-yv-ya', (<function add>, 'fom:nl-t-yv-ya', 'vom:nl-t-yv-ya')), ('addon conversion:nl-t-yv-ya-m-h-ta', (functools.partial(<function broadcast_map>, rename={'n': 'nl'}), 'addon_conversion:n-t-yv-ya-m-h-type_addon', 'map_addon')), ('addon up:nl-t-ya-m-h-ta', (functools.partial(<function broadcast_map>, rename={'n': 'nl'}), 'addon_up:n-t-ya-m-h-type_addon', 'map_addon')), ('price emission:n-e-t-y', (<function broadcast_map>, (<function broadcast_map>, 'PRICE_EMISSION:n-type_emission-type_tec-y', 'map_emission'), 'map_tec'))]

Automatic quantities derived by other calculations.

message_ix.reporting.DIMS = {'commodity': 'c', 'emission': 'e', 'grade': 'g', 'land_scenario': 's', 'land_type': 'u', 'level': 'l', 'mode': 'm', 'node': 'n', 'node_dest': 'nd', 'node_loc': 'nl', 'node_origin': 'no', 'node_rel': 'nr', 'node_share': 'ns', 'rating': 'q', 'relation': 'r', 'technology': 't', 'technology_addon': 'ta', 'technology_primary': 'tp', 'time': 'h', 'time_dest': 'hd', 'time_origin': 'ho', 'year': 'y', 'year_act': 'ya', 'year_rel': 'yr', 'year_vtg': 'yv'}

Short names for dimensions (sets) in the MESSAGEix framework.

message_ix.reporting.MAPPING_SETS = [('addon', 't'), ('emission', 'e'), ('tec', 't'), ('year', 'y')]

MESSAGE mapping sets, converted to reporting quantities via map_as_qty().

For instance, the mapping set cat_addon is available at the reporting key map_addon, which produces a Quantity with the two dimensions type_addon and ta (short form of technology_addon). This Quantity contains the value 1 at every valid (type_addon, ta) location, and 0 elsewhere.

message_ix.reporting.PRODUCTS = (('out', ('output', 'ACT')), ('in', ('input', 'ACT')), ('rel', ('relation_activity', 'ACT')), ('emi', ('emission_factor', 'ACT')), ('inv', ('inv_cost', 'CAP_NEW')), ('fom', ('fix_cost', 'CAP')), ('vom', ('var_cost', 'ACT')), ('land_out', ('land_output', 'LAND')), ('land_use_qty', ('land_use', 'LAND')), ('land_emi', ('land_emission', 'LAND')), ('addon ACT', ('addon conversion', 'ACT')), ('addon in', ('input', 'addon ACT')), ('addon out', ('output', 'addon ACT')), ('addon potential', ('addon up', 'addon ACT')))

Automatic quantities that are the product() of two others.

message_ix.reporting.PYAM_CONVERT = [('out:nl-t-ya-m-nd-c-l', 'ya', {'kind': 'ene', 'var': 'out'}), ('in:nl-t-ya-m-no-c-l', 'ya', {'kind': 'ene', 'var': 'in'}), ('CAP:nl-t-ya', 'ya', {'var': 'capacity'}), ('CAP_NEW:nl-t-yv', 'yv', {'var': 'new capacity'}), ('inv:nl-t-yv', 'yv', {'var': 'inv cost'}), ('fom:nl-t-ya', 'ya', {'var': 'fom cost'}), ('vom:nl-t-ya', 'ya', {'var': 'vom cost'}), ('tom:nl-t-ya', 'ya', {'var': 'total om cost'}), ('emi:nl-t-ya-m-e', 'ya', {'kind': 'emi', 'var': 'emis'})]

Quantities to automatically convert to IAMC format using as_pyam().

message_ix.reporting.REPORTS = {'message:costs': ['inv:pyam', 'fom:pyam', 'vom:pyam', 'tom:pyam'], 'message:emissions': ['emi:pyam'], 'message:system': ['out:pyam', 'in:pyam', 'CAP:pyam', 'CAP_NEW:pyam']}

Automatic reports that concat() quantities converted to IAMC format.

exception message_ix.reporting.ComputationError(exc)

Wrapper to print intelligible exception information for Computer.get().

In order to aid in debugging, this helper:

  • Omits the parts of the stack trace that are internal to dask, and

  • Gives the key in the Computer.graph and the computation/task that caused the exception.

class message_ix.reporting.Key(name: str, dims: Iterable[str] = [], tag: Optional[str] = None)

A hashable key for a quantity that includes its dimensionality.

add_tag(tag)

Return a new Key with tag appended.

append(*dims: str)

Return a new Key with additional dimensions dims.

property dims: Tuple[str, ...]

Dimensions of the quantity, tuple of str.

drop(*dims: Union[str, bool])

Return a new Key with dims dropped.

classmethod from_str_or_key(value: Union[str, genno.core.key.Key], drop: Union[Iterable[str], bool] = [], append: Iterable[str] = [], tag: Optional[str] = None)

Return a new Key from value.

Parameters
  • value (str or Key) – Value to use to generate a new Key.

  • drop (list of str or True, optional) – Existing dimensions of value to drop. See drop().

  • append (list of str, optional.) – New dimensions to append to the returned Key. See append().

  • tag (str, optional) – Tag for returned Key. If value has a tag, the two are joined using a ‘+’ character. See add_tag().

Returns

Return type

Key

iter_sums() Generator[Tuple[genno.core.key.Key, Callable, genno.core.key.Key], None, None]

Generate (key, task) for all possible partial sums of the Key.

property name: str

Name of the quantity, str.

permute_dims() Generator[genno.core.key.Key, None, None]

Generate variants of the Key with dimensions in all possible orders.

Examples

>>> k = Key("A", "xyz")
>>> list(k.permute_dims())
[<A:x-y-z>, <A:x-z-y>, <A:y-x-z>, <A:y-z-x>, <A:z-x-y>, <A:z-y-x>]
classmethod product(new_name: str, *keys, tag: Optional[str] = None) genno.core.key.Key

Return a new Key that has the union of dimensions on keys.

Dimensions are ordered by their first appearance:

  1. First, the dimensions of the first of the keys.

  2. Next, any additional dimensions in the second of the keys that were not already added in step 1.

  3. etc.

Parameters

new_name (str) – Name for the new Key. The names of keys are discarded.

property sorted: genno.core.key.Key

A version of the Key with its dims sorted alphabetically.

property tag: Optional[str]

Quantity tag, str or None.

exception message_ix.reporting.KeyExistsError

Raised by Computer.add() when the target key exists.

exception message_ix.reporting.MissingKeyError

Raised by Computer.add() when a required input key is missing.

class message_ix.reporting.Quantity(*args, **kwargs)

A sparse data structure that behaves like xarray.DataArray.

Depending on the value of CLASS, Quantity is either AttrSeries or SparseDataArray.

classmethod from_series(series, sparse=True)

Convert series to the Quantity class given by CLASS.

to_series() pandas.core.series.Series

Like xarray.DataArray.to_series().

property units

Retrieve or set the units of the Quantity.

Examples

Create a quantity without units:

>>> qty = Quantity(...)

Set using a string; automatically converted to pint.Unit:

>>> qty.units = "kg"
>>> qty.units
<Unit('kilogram')>
message_ix.reporting.configure(path: Optional[Union[pathlib.Path, str]] = None, **config)

Configure genno globally.

Modifies global variables that affect the behaviour of all Computers and computations. Configuration keys loaded from file are superseded by keyword arguments. Messages are logged at level logging.INFO if config contains unhandled sections.

Parameters
  • path (Path, optional) – Path to a configuration file in JSON or YAML format.

  • **config – Configuration keys/sections and values.

Computations

message_ix.reporting only provides two computations, which are currently only used in the tutorials to produce simple plots. For custom plotting, genno.compat.plotnine is recommended.

plot_cumulative(x, y, labels)

Plot a supply curve.

stacked_bar(qty[, dims, units, title, cf, ...])

Plot qty as a stacked bar chart.

Other computations are provided by ixmp.reporting:

data_for_quantity(ix_type, name, column, ...)

Retrieve data from scenario.

map_as_qty(set_df, full_set)

Convert set_df to a Quantity.

update_scenario(scenario, *quantities[, params])

Update scenario with computed data from reporting quantities.

…and by genno.computation and its compatibility modules. See the package documentation for details.

Plot()

Class for plotting using plotnine.

add(*quantities[, fill_value])

Sum across multiple quantities.

aggregate(quantity, groups, keep)

Aggregate quantity by groups.

apply_units(qty, units[, quiet])

Simply apply units to qty.

as_pyam(scenario, quantity[, rename, ...])

Return a pyam.IamDataFrame containing quantity.

broadcast_map(quantity, map[, rename, strict])

Broadcast quantity using a map.

combine(*quantities[, select, weights])

Sum distinct quantities by weights.

concat(*objs, **kwargs)

Concatenate Quantity objs.

disaggregate_shares(quantity, shares)

Disaggregate quantity by shares.

group_sum(qty, group, sum)

Group by dimension group, then sum across dimension sum.

load_file(path[, dims, units, name])

Read the file at path and return its contents as a Quantity.

product(*quantities)

Compute the product of any number of quantities.

ratio(numerator, denominator)

Compute the ratio numerator / denominator.

select(qty, indexers[, inverse])

Select from qty based on indexers.

sum(quantity[, weights, dimensions])

Sum quantity over dimensions, with optional weights.

write_report(quantity, path)

Write a quantity to a file.

message_ix.reporting.computations.plot_cumulative(x, y, labels)

Plot a supply curve.

  • x and y must share the first two dimensions.

  • The first dimension must contain unique values.

  • One rectangle is plotted for each unique value in the second dimension.

Parameters
  • x (Quantity) – e.g. <resource_volume:n-g>.

  • y (Quantity) – e.g. <resource_cost:n-g-y>. The mean() is taken across the third dimension.

message_ix.reporting.computations.stacked_bar(qty, dims=['nl', 't', 'ya'], units='', title='', cf=1.0, stacked=True)

Plot qty as a stacked bar chart.

Parameters
  • qty (ixmp.reporting.Quantity) – Data to plot.

  • dims (3-tuple of str) –

    Dimensions for, respectively:

    1. The node/region.

    2. Dimension to stack.

    3. The ordinate (x-axis).

  • units (str) – Units to display on the plot.

  • title (str) – Title fragment; the plot title is “{node} {title}”.

  • cf (float, optional) – Conversion factor to apply to data.

Utilities

message_ix.reporting.pyam.collapse_message_cols(df: pandas.core.frame.DataFrame, var: Optional[str] = None, kind: Optional[str] = None, var_cols=[]) Callable

as_pyam() collapse=… callback for MESSAGEix quantities.

Wraps collapse() with arguments particular to MESSAGEix.

Parameters
  • var (str) – Name for ‘variable’ column.

  • kind (None or 'ene' or 'emi', optional) –

    Determines which other columns are combined into the ‘region’ and ‘variable’ columns:

    • ’ene’: ‘variable’ is '<var>|<level>|<commodity>|<technology>|<mode>' and ‘region’ is '<region>|<node_dest>' (if var=’out’) or '<region>|<node_origin>' (if ‘var=’in’).

    • ’emi’: ‘variable’ is '<var>|<emission>|<technology>|<mode>'.

    • Otherwise: ‘variable’ is '<var>|<technology>'.