message_ix_models.model.material.report.config.Config

class message_ix_models.model.material.report.config.Config(iamc_prefix: str, unit: ~typing.Literal['Mt/yr', 'GWa', 'Mt CH4/yr', 'GW'], var: ~typing.Literal['out', 'in', 'ACT', 'emi', 'CAP'], mapping: ~pandas.core.frame.DataFrame = <factory>)[source]

Bases: object

Configuration for reporting of a subset of material data.

__init__(iamc_prefix: str, unit: ~typing.Literal['Mt/yr', 'GWa', 'Mt CH4/yr', 'GW'], var: ~typing.Literal['out', 'in', 'ACT', 'emi', 'CAP'], mapping: ~pandas.core.frame.DataFrame = <factory>) → None

Methods

__init__(iamc_prefix, unit, var[, mapping])

check_mapping()

Assert that mapping has the correct structure and is complete.

from_files(category)

Create a Config instance from 1 or 2 YAML files.

use_aggregates_dict(data)

Update mapping from data.

use_vars_dict(data)

Update mapping using data.

Attributes

iamc_prefix

Prefix or initial fragment of IAMC ‘variable’ name.

unit

Units of measure for the reported data.

var

message_ix.report key from which to retrieve the data.

mapping

Data frame with:
check_mapping() → None[source]

Assert that mapping has the correct structure and is complete.

classmethod from_files(category: str) → Config[source]

Create a Config instance from 1 or 2 YAML files.

A file like message_ix_models/data/material/reporting/category.yaml is read and used to populate a new instance. The file must have:

If a file exists in the same directory named like category_aggregates.yaml, it is also read, and its contents passed to use_aggregates_dict().

iamc_prefix: str

Prefix or initial fragment of IAMC ‘variable’ name.

mapping: DataFrame

Data frame with:

  • MultiIndex levels including 1 or more of \((c, l, m, t)\).

  • 3 columns: - “iamc_name”: a (fragment of) an IAMC ‘variable’ name. This is appended to

    to iamc_prefix to construct a complete name.

    • “short_name”: …

    • “unit”: units of measure.

This expresses a mapping between the index entries (=indices of reported data) and the information in the 3 columns.

unit: Literal['Mt/yr', 'GWa', 'Mt CH4/yr', 'GW']

Units of measure for the reported data.

use_aggregates_dict(data: dict) → None[source]

Update mapping from data.

This method handles data with structure equivalent to the following YAML content:

level_1:
  Chemicals|Liquids|Other:
    short: fe_pe_chem_oth
    components: [ fe_pe_hvc_oth ]
  Chemicals|Liquids|Biomass:
    short: fe_pe_chem_bio
    components: [ fe_pe_hvc_bio_eth ]
  # Any number of similar entries
level_2:
  Heat:
    short: fe_pe_heat
    components:
    - fe_pe_cement_heat
    - fe_pe_aluminum_heat
    - fe_pe_steel_heat
    - fe_pe_other_heat
  # Any number of similar entries

In general:

  • Top-level keys may be “level_1”, “level_2”, etc. Additional top-level keys like “iamc_prefix”, “unit”, and “var” are checked against the corresponding attributes.

  • Second-level keys are fragments of IAMC ‘variable’ names

  • Third level keys must be:

    • “short”: A single string. See the description of the “short_name” column in mapping. This is the aggregate to be produced.

    • “components”: A list of strings. These are the components of the aggregation. Components referenced under “level_1” must already be present in mapping. Components referenced under “level_2” may include the aggregates described by “level_1”, etc.

use_vars_dict(data: dict) → None[source]

Update mapping using data.

This handles data with structure equivalent to the following YAML content:

Chemicals|High-Value Chemicals|Electricity|Steam Cracking:
  filter:
    commodity: electr
    level: final
    mode: [vacuum_gasoil, atm_gasoil, naphtha, ethane, propane]
    technology: steam_cracker_petro,
  short: fe_pe_hvc_el_sc
  unit: kg  # Optional

# Any number of similar entries

Within this:

  • Chemicals|High-Value Chemicals|Electricity|Steam Cracking is a (fragment of) an IAMC ‘variable’ name.

  • filter entries may have values that are strings or lists of strings. The subkeys may include the MESSAGEix sets [technology, mode, commodity, level].

var: Literal['out', 'in', 'ACT', 'emi', 'CAP']

message_ix.report key from which to retrieve the data.