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>

Models and variants (model)

model.macro: MESSAGE-MACRO

model.structure: Model structure information

Models and variants (`model`)

`model.macro`: MESSAGE-MACRO

`model.structure`: Model structure information