Reporting / postprocessing

ixmp.reporting provides features for computing derived values from the contents of a ixmp.Scenario, after it has been solved using a model and the solution data has been stored. It is built on the genno package, which has its own, separate documentation. This page provides only API documentation.

Top-level classes and functions

The following top-level objects from genno may also be imported from ixmp.reporting.


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

Key(name_or_value[, dims, tag, _fast])

A hashable key for a quantity that includes its dimensionality.


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


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

Quantity(*args, **kwargs)

A sparse data structure that behaves like xarray.DataArray.


Configure genno globally.

ixmp.reporting additionally defines:

Reporter(*args, **kwargs)

Class for describing and executing computations.

class ixmp.reporting.Reporter(*args, **kwargs)[source]

Class for describing and executing computations.

A Reporter extends a genno.Computer to postprocess data from one or more ixmp.Scenario objects.

Using the from_scenario(), a Reporter is automatically populated with:

  • Keys that retrieve the data for every ixmp item (parameter, variable, equation, or scalar) available in the Scenario.


Prepare the Reporter to act on scenario.

from_scenario(scenario, **kwargs)

Create a Reporter by introspecting scenario.


Apply filters ex ante (before computations occur).

The Computer class provides the following methods:

add(data, *args, **kwargs)

General-purpose method to add computations.

add_file(*args, **kwargs)


add_product(*args, **kwargs)


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[, ...])


apply(generator, *keys, **kwargs)

Add computations by applying generator to keys.

check_keys(*keys[, predicate, action])

Check that keys are in the Computer.

configure([path, fail, config])

Configure the Computer.

convert_pyam(*args, **kwargs)


describe([key, quiet])

Return a string describing the computations that produce key.

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



Return the full-dimensionality key for name_or_key.


Execute and return the result of the computation key.

infer_keys(key_or_keys[, dims])

Infer complete key_or_keys.


Return the keys of graph.

visualize(filename[, key, optimize_graph])

Generate an image describing the Computer structure.

write(key, path)

Compute key and write the result directly to path.

finalize(scenario: Scenario) None[source]

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: Scenario, **kwargs) Reporter[source]

Create a Reporter by introspecting scenario.

  • scenario (.Scenario) – Scenario to introspect in creating the Reporter.

  • kwargs (optional) – Passed to Scenario.configure().


A Reporter instance containing:

  • A ‘scenario’ key referring to the scenario object.

  • Each parameter, equation, and variable in the scenario.

  • All possible aggregations across different sets of dimensions.

  • Each set in the scenario.

Return type:


set_filters(**filters) None[source]

Apply filters ex ante (before computations occur).

See the description of filters() under Configuration.


ixmp.reporting adds handlers for two configuration sections, and modifies the behaviour of one from genno

reporting.filters(filters: dict)[source]

Handle the entire filters: config section.

Reporter-specific configuration.

Affects data loaded from a Scenario using data_for_quantity(), which filters the data before any other computation takes place. Filters are stored at Reporter.graph["config"]["filters"].

If no arguments are provided, all filters are cleared. Otherwise, filters is a mapping of str → (list of str or None. Keys are dimension IDs. Values are either lists of allowable labels along the respective dimension or None to clear any existing filters for that dimension.

This configuration can be applied through Reporter.set_filters(); Reporter.configure(), or in a configuration file:

  # Exclude a label "x2" on the "x" dimension, etc.
  x: [x1, x3, x4]
  technology: [coal_ppl, wind_ppl]
  # Clear existing filters for the "commodity" dimension
  commodity: null
reporting.rename_dims(info: dict)[source]

Handle the entire rename_dims: config section.

Reporter-specific configuration.

Affects data loaded from a Scenario using data_for_quantity(). Native dimension names are mapped; in the example below, the dimension “i” is present in the Reporter as “i_renamed” on all quantities/keys in which it appears.

  i: i_renamed
reporting.units(info: dict)[source]

Handle the entire units: config section.

The only difference from genno.config.units() is that this handler keeps the configuration values stored in Reporter.graph["config"]. This is so that data_for_quantity() can make use of ["units"]["apply"]


ixmp.reporting defines these computations:

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.

store_ts(scenario, *data[, strict])

Store time series data on scenario.

Basic computations are defined by genno.computation; and its compatibility modules; see there for details:


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)

Apply units to qty.


Return a pyam.IamDataFrame containing the data from 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)

Deprecated: Disaggregate quantity by shares.

div(numerator, denominator)

Compute the ratio numerator / denominator.

group_sum(qty, group, sum)

Group by dimension group, then sum across dimension sum.

interpolate(qty[, coords, method, ...])

Interpolate qty.


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


Compute the product of any number of quantities.

pow(a, b)

Compute a raised to the power of b.


Alias of mul(), for backwards compatibility.

relabel(qty[, labels])

Replace specific labels along dimensions of qty.

rename_dims(qty[, new_name_or_name_dict])

Rename the dimensions of qty.

ratio(numerator, denominator)

Alias of div(), for backwards compatibility.

select(qty, indexers, *[, inverse, drop])

Select from qty based on indexers.


Sum quantity over dimensions, with optional weights.

write_report(quantity, path)

Write a quantity to a file.

ixmp.reporting.computations.data_for_quantity(ix_type, name, column, scenario, config)[source]

Retrieve data from scenario.

  • ix_type ('equ' or 'par' or 'var') – Type of the ixmp object.

  • name (str) – Name of the ixmp object.

  • column ('mrg' or 'lvl' or 'value') – Data to retrieve. ‘mrg’ and ‘lvl’ are valid only for ix_type='equ',and ‘level’ otherwise.

  • scenario (ixmp.Scenario) – Scenario containing data to be retrieved.

  • config (dict of (str -> dict)) – The key ‘filters’ may contain a mapping from dimensions to iterables of allowed values along each dimension. The key ‘units’/’apply’ may contain units to apply to the quantity; any such units overwrite existing units, without conversion.


Data for name.

Return type:


ixmp.reporting.computations.map_as_qty(set_df: DataFrame, full_set)[source]

Convert set_df to a Quantity.

For the MESSAGE sets named cat_* (see Category types and mappings) ixmp.Scenario.set() returns a DataFrame with two columns: the category set (S1) elements and the category member set (S2, also required as the argument full_set) elements.

map_as_qty converts such a DataFrame (set_df) into a Quantity with two dimensions. At the coordinates (s₁, s₂), the value is 1 if s₂ is mapped from s₁; otherwise 0.

A category named ‘all’, containing all elements of full_set, is added automatically.

See also


ixmp.reporting.computations.store_ts(scenario, *data, strict: bool = False) None[source]

Store time series data on scenario.

The data is stored using add_timeseries(); scenario is checked out and then committed.

  • scenario – Scenario on which to store data.

  • data (pandas.DataFrame or pyam.IamDataFrame) – 1 or more objects containing data to store. If pandas.DataFrame, the data are passed through to_iamc_layout().

  • strict (bool) – If True (default False), raise an exception if any of data are not successfully added. Otherwise, log on level ERROR and continue.

ixmp.reporting.computations.update_scenario(scenario, *quantities, params=[])[source]

Update scenario with computed data from reporting quantities.

  • scenario (.Scenario) –

  • quantities (.Quantity or pd.DataFrame) – If DataFrame, must be valid input to Scenario.add_par().

  • params (list of str, optional) – For every element of quantities that is a pd.DataFrame, the element of params at the same index gives the name of the parameter to update.


ixmp.reporting.util.RENAME_DIMS: Dict[str, str] = {}[source]

Dimensions to rename when extracting raw data from Scenario objects. Mapping from Scenario dimension name -> preferred dimension name.


Return the list of dimensions for data.

If data is a pandas.DataFrame, its columns are processed; otherwise it must be a list.

genno.RENAME_DIMS is used to rename dimensions.

ixmp.reporting.util.keys_for_quantity(ix_type, name, scenario)[source]

Return keys for name in scenario.