The region codelist

Each region must be part of a hierarchy, which means that the following nested list structure is required:

- Hierarchy 1:
  - Region 1:
      description: Some short explanation
      countries: [Country 1, Country 2, ...]
  - Region 2:
      description: Some short explanation
      iso3_codes: ABC
- Hierarchy 2:
  - ...

Regions can have attributes, for example a description, a list of countries, or ISO3 codes. If the attributes countries and/or iso3_codes are provided, the item(s) are validated against a list of valid ISO3 country names/codes adapted from the pycountry package. More details on the list of countries can be found here.

Common regions

In model-comparison projects, it is useful to define common regions that can be computed consistently from original model results. Widely used examples are the R5, R9 and R10 regions, see here.

Naming conventions for native model regions

In contrast to common regions used for comparison or scenario analysis across models, each model has a “native region” resolution.

Models with a coarse spatial resolution should add a model-specific prefix to the native model regions (e.g., MESSAGEix-GLOBIOM 1.1|North America) to avoid confusion when comparing results to other models with similar-but-different regions.

- Model A v1.0:
  - Model A v1.0|Region 1:
      description: Some short explanation

The renaming from (short) region-names as reported by a modelling framework to such more verbose region names for use in model-comparison projects can be implemented by the Region processing using model mappings.

If a model has a country-level resolution where disambiguation is not a concern, we recommend to not add a model identifier.

Connections between regions

For reporting of connections (e.g., trade flows), “directional regions” can be defined using a > separator. The region before the separator is the origin, the region after the separator is the destination.

- Trade Connections:
  - China>Europe

Both the origin and destination regions must be defined in the region codelist.

For model-specific directional connections, the prefix must be added as well.

- Model A v1.0 [Connection]:
  - Model A v1.0|Region 1>Region 2

Both origin and destination Model A v1.0|Region 1 and Model A v1.0|Region 2 must be defined in the region codelist.