RegionProcessor

class nomenclature.processor.RegionProcessor(*, input_data=None, input_meta=None, output_data=None, output_meta=None, fail_ok=False, region_codelist, variable_codelist, mappings)

Region aggregation mappings for scenario processing

Methods

apply(df)	Apply region processing
check_region_aggregation(df[, rtol_difference])	Return region aggregation results and differences between aggregated and model native data
from_directory(path, dsd)	Initialize a RegionProcessor from a directory of model-aggregation mappings.
get_common_region_country_mapping(model)	Return a mapping from common region names to constituent countries for a model.
get_native_region_country_mapping(model)	Return a mapping from (renamed) native region names to countries for a model.
revert(df)	Revert region processing by removing common regions and applying inverse renaming.

apply(df)

Apply region processing

Parameters:

dfIamDataFrame

Input data that the region processing is applied to

Returns:

IamDataFrame:

Processed data

Raises:

ValueError

• If df contains regions that are not listed in the model mapping, or

• If the region-processing results in an empty IamDataFrame.

check_region_aggregation(df, rtol_difference=0.01)

Return region aggregation results and differences between aggregated and model native data

Parameters:

dfIamDataFrame

Input data

rtol_differencefloat, optional

limit on the relative tolerance for differences, by default 0.01

Returns:

tuple[IamDataFrame, pd.DataFrame]

IamDataFrame containing aggregation results and pandas dataframe containing the differences

classmethod from_directory(path, dsd)

Initialize a RegionProcessor from a directory of model-aggregation mappings.

Parameters:

pathDirectoryPath

Directory which holds all the mappings.

dsdDataStructureDefinition

Instance of DataStructureDefinition used for validation of mappings and region aggregation.

Returns:

RegionProcessor

The resulting region processor object.

Raises:

ValueError

Raised in case there are multiple mappings defined for the same model or there is an issue with region the RegionAggregationMapping

AttributeError

Raised if the provided DataStructureDefinition does not contain the dimensions region and variable.

get_common_region_country_mapping(model)

Return a mapping from common region names to constituent countries for a model.

Parameters:

modelstr

Name of the model.

Returns:

dict[str, list[str]]

Dictionary mapping each common region name to the aggregated list of countries from all of its constituent native regions.

get_native_region_country_mapping(model)

Return a mapping from (renamed) native region names to countries for a model.

Parameters:

modelstr

Name of the model.

Returns:

dict[str, list[str]]

Dictionary mapping each native region name (after any renaming) to its list of countries.

revert(df)

Revert region processing by removing common regions and applying inverse renaming.

Country-to-region processor

CountryProcessor is a subclass of RegionProcessor. It includes a method to aggregate country-level data to common regional definitions in the region codelist.

One intended use case is standard regional hierarchies such as R5, R9 and R10 imported from common-definitions. Unlike the NutsProcessor, country aggregation is a single-step aggregation and does not require a nested hierarchy to be computed level by level.

The processor reads region definitions from the project’s region codelist and looks for entries with the specified hierarchy names (such as R5, R9, and R10). Constituent countries are taken from the countries attributes of those region definitions.

Minimal configuration

repositories:
  common-definitions:
    url: https://github.com/IAMconsortium/common-definitions.git/

definitions:
  region:
    repository:
      name: common-definitions
      include:
        - hierarchy: [R5, R9, R10]
    country: true

processors:
  country: [Model A, Model B]

In this setup, all country names are added to the region codelist, the R5/R9/R10 region definitions are imported from common-definitions, and the country processor is applied to the listed models.

Creating a country-to-region processor

The CountryProcessor.from_codelist() method is the core factory method that generates region aggregation mappings on-the-fly.

classmethod CountryProcessor.from_codelist(dsd, models, hierarchies={'R10', 'R5', 'R9'}, skip_patterns=None)

Create a processor for country-to-regional aggregation.

This factory method generates region aggregation mappings on-the-fly by extracting regions with constituent countries matching the specified hierarchies from the region codelist.

Parameters:

dsdDataStructureDefinition

Project data structure definition containing region and variable codelists.

modelslist[str]

Models for which to apply the aggregation.

hierarchieslist[str]

List of hierarchy values to match (e.g., [“R5”, “R9”, “R10”]). Regions with these exact hierarchy values will be used for aggregation.

skip_patternslist[str], optional

Optional regex patterns to skip certain regions from aggregation.

Returns:

CountryProcessor

A CountryProcessor instance with generated mappings.

Raises:

If regions with the specified hierarchies lack constituent country information.