Models and variants (model)

Submodules described on this page:

Submodules described on separate pages:

Code for constructing models/scenarios in the MESSAGEix-GLOBIOM model family.

class message_ix_models.model.Config(regions: str = 'R14', relations: str = 'A', years: str = 'B', res_with_dummies: bool = False, units: dict = <factory>)[source]

Settings and valid values for message_ix_models.model and submodules.

For backwards compatibility, it is possible to access these on a Context using:

c = Context()
c.regions = "R14"

…however, it is best to access them explicitly as:

c.model.regions = "R14"
check()[source]

Check the validity of regions, relations, years.

regions: str = 'R14'

The ‘node’ codelist (regional aggregation) to use. Must be one of the lists of nodes described at Node code lists.

relations: str = 'A'

The ‘relations’ codelist to use. Must be one of the lists of relations described at Relations (relation/*.yaml).

res_with_dummies: bool = False

Create the reference energy system with dummy commodities and technologies. See bare.get_spec().

units: dict

Default or preferred units for model quantities and reporting.

years: str = 'B'

The ‘year’ codelist (time periods) to use, Must be one of the lists of periods described at Years or time periods (year/*.yaml).

model.macro: MESSAGE-MACRO

Tools for calibrating MACRO for MESSAGEix-GLOBIOM.

See Calibrate and tune MESSAGE-MACRO for general documentation on MACRO and MESSAGE-MACRO. This module contains tools specifically for using these models with MESSAGEix-GLOBIOM.

message_ix_models.model.macro.COMMODITY = ['i_therm', 'i_spec', 'rc_spec', 'rc_therm', 'transport']

Default set of commodities to include in generate().

message_ix_models.model.macro.generate(parameter: Literal['aeei', 'config', 'depr', 'drate', 'lotol'], context: Context, commodities: List[str] | List[Code] = ['i_therm', 'i_spec', 'rc_spec', 'rc_therm', 'transport'], value: float | None = None) → DataFrame[source]

Generate uniform data for one message_ix.macro parameter.

message_ix.Scenario.add_macro() expects as its data parameter a dict that maps certain MACRO parameter names (or the special name “config”) to pandas.DataFrame. This function generates data for those data frames.

For the particular dimensions, generate automatically includes:

  • “node”: All nodes in the node code list given by nodes_ex_world(), for the node list indicated by model.Config.regions.

  • “year”: All periods from the period before the first model year.

  • “commodity”: The elements of commodities.

  • “sector”: If each entry of commodities is a Code and has an annotation with id=”macro-sector”, the value of that annotation. Otherwise, the same as commodity.

value supplies the parameter value, which is the same for all observations. The labels level=”useful” and unit=”-” are fixed.

Parameters:

  • parameter (str) – MACRO parameter for which to generate data.

  • context – Used with bare.get_spec().

  • commodities (list of str or Code) – Commodities to include in the MESSAGE-MACRO linkage.

  • value (float) – Parameter value.

Returns:

The columns vary according to parameter:

  • ”aeei”: node, sector, year, value, unit.

  • ”depr”, “drate”, or “lotol”: node, value, unit.

  • ”config”: node, sector, commodity, level, year.

Return type:

pandas.DataFrame

message_ix_models.model.macro.load(base_path: Path) → Mapping[str, DataFrame][source]

Load MACRO data from CSV files.

The function reads files in the simple/long CSV format understood by genno.operator.load_file(). For use with add_macro(), the dimension names should be given in full, for instance “node” or “sector”.

Parameters:

base_path (pathlib.Path) – Directory containing zero or more CSV files.

Returns:

Mapping from MACRO calibration parameter names to data; one entry for each file in base_path.

Return type:

dict of (str -> pandas.DataFrame)

model.structure: Model structure information

codelists(kind)

Return a valid IDs for code lists of kind.

generate_product(data, name, template)

Generates codes using a template by Cartesian product along ≥1 dimensions.

generate_set_elements(data, name)

Generate elements for set name.

get_codes(name)

Return codes for the dimension/set name in MESSAGE-GLOBIOM scenarios.

get_region_codes(codelist)

Return the codes that are children of "World" in the specified codelist.

process_units_anno(set_name, code[, quiet])

Process an annotation on code with id="units".

process_commodity_codes(codes)

Process a list of codes for commodity.

process_technology_codes(codes)

Process a list of codes for technology.
message_ix_models.model.structure.codelists(kind: str) → List[str][source]

Return a valid IDs for code lists of kind.

Parameters:

kind (str) – “node” or “year”.

message_ix_models.model.structure.generate_product(data: Mapping, name: str, template: Code) → Tuple[List[Code], Dict[str, DataArray]][source]

Generates codes using a template by Cartesian product along ≥1 dimensions.

generate_set_elements() is called for each of the dims, and these values are used to format base.

Parameters:

  • data – Mapping from dimension IDs to lists of codes.

  • name (str) – Name of the set.

  • template (Code) – Must have Python format strings for its its id and name attributes.

message_ix_models.model.structure.generate_set_elements(data: MutableMapping, name) → None[source]

Generate elements for set name.

This function converts lists of codes in data, calling generate_product() and process_units_anno() as appropriate.

Parameters:

  • data – Mapping from dimension IDs to lists of codes.

  • name (str) – Name of the set for which to generate elements e.g. “commodity” or “technology”.

message_ix_models.model.structure.get_codelist(name: str) → Codelist[source]

Return a Codelist for name in MESSAGEix-GLOBIOM scenarios.

message_ix_models.model.structure.get_region_codes(codelist: str) → List[Code][source]

Return the codes that are children of “World” in the specified codelist.

message_ix_models.model.structure.process_commodity_codes(codes)[source]

Process a list of codes for commodity.

The function warns for commodities missing units or with non-pint-compatible units.

message_ix_models.model.structure.process_technology_codes(codes)[source]

Process a list of codes for technology.

This function ensures every code has an annotation with id “vintaged”, default False.

message_ix_models.model.structure.process_units_anno(set_name: str, code: Code, quiet: bool = False) → None[source]

Process an annotation on code with id=”units”.

The annotation text is wrapped as 'registry.Unit("{text}")', such that it can be retrieved with eval_anno() or ScenarioInfo.units_for(). If code has direct children, the annotation is also copied to those codes.

Parameters:

  • set_name (str) – Used in logged messages when quiet is False.

  • quiet (bool, optional) –

    If False (the default), log on level WARNING if:

    • the annotation is missing, or

    • its text is not parseable with the pint application registry, i.e. iam_units.registry.

    Otherwise, log on DEBUG.

message_ix_models.model.structure.get_codes(name: str) → List[Code][source]

Return codes for the dimension/set name in MESSAGE-GLOBIOM scenarios.

The information is read from data/name.yaml, e.g. data/technology.yaml.

When name includes “node”, then child codes are automatically populated from the ISO 3166 database via pycountry. For instance:

myregion:
  name: Custom region
  child: [AUT, SCG]

…results in a region with child codes for Austria (a current country) and the formerly-existing country Serbia and Montenegro.

Parameters:

name (str) – Any .yaml file in the folder message_ix_models/data/.

Returns:

Every Code has id, name, description, and annotations attributes. Calling str() on a code returns its id.

Return type:

list of Code

The available code lists are reproduced as part of this documentation. The returned code objects have annotations that vary by set. See:

Also available is cd_links/unit.yaml. This is a project-specific list of units appearing in CD-LINKS scenarios.

Example:

>>> from message_ix_models.model.structure import get_codes
>>> codes = get_codes("node/R14")

# Show the codes
>>> codes
[<Code ABW: Aruba>,
 <Code AFG: Afghanistan>,
 <Code AGO: Angola>,
 ...
 <Code ZWE: Zimbabwe>,
 <Code World: World>,
 ...
 <Code R11_PAS: Other Pacific Asia>,
 <Code R11_SAS: South Asia>,
 <Code R11_WEU: Western Europe>]

# Retrieve one code matching a certain ID
>>> world = codes[codes.index("World")]

# Get its children's IDs strings, e.g. for a "node" dimension
>>> [str(c) for c in world.child]
['R11_AFR',
 'R11_CPA',
 'R11_EEU',
 'R11_FSU',
 'R11_LAM',
 'R11_MEA',
 'R11_NAM',
 'R11_PAO',
 'R11_PAS',
 'R11_SAS',
 'R11_WEU']

# Navigate from one ISO 3166-3 country code to its parent
>>> AUT = codes[codes.index("AUT")]
>>> AUT.parent
<Code R11_WEU: Western Europe>

See also

adapt_R11_R14