Reporting API

ixmp.reporting is built on the genno package. 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.

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)

configure([path])

Configure genno globally.

ixmp.reporting additionally defines:

Reporter(**kwargs)

Class for describing and executing computations.
class ixmp.reporting.Reporter(**kwargs)

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.

finalize(scenario)

Prepare the Reporter to act on scenario.

from_scenario(scenario, **kwargs)

Create a Reporter by introspecting scenario.

set_filters(**filters)

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(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)

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.

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.

visualize(filename, **kwargs)

Generate an image describing the Computer structure.

write(key, path)

Write the result of key to the file path.
finalize(scenario: ixmp.core.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: ixmp.core.Scenario, **kwargs) → ixmp.reporting.reporter.Reporter

Create a Reporter by introspecting scenario.

Parameters

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

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

Returns

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

Reporter

set_filters(**filters) → None

Apply filters ex ante (before computations occur).

See the description of filters() under Configuration.

Configuration

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

reporting.filters(filters: dict)

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:

filters:
  # 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)

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.

rename_dims:
  i: i_renamed
reporting.units(info: dict)

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"]

Computations

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.

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

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.

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.
ixmp.reporting.computations.data_for_quantity(ix_type, name, column, scenario, config)

Retrieve data from scenario.

Parameters

  • 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.

Returns

Data for name.

Return type

Quantity

ixmp.reporting.computations.map_as_qty(set_df: pandas.core.frame.DataFrame, full_set)

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

broadcast_map

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

Update scenario with computed data from reporting quantities.

Parameters

  • 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.

Utilities

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

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

ixmp.reporting.util.dims_for_qty(data)

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)

Return keys for name in scenario.