NUTS classification

The nomenclature package makes use of the pysquirrel package (link) to provide a utility for region names based on the NUTS classification.

This feature allows users to define an agreed list of territorial units with multiple levels of resolution, adding functionality to facilitate scenario analysis and model comparison.

The full list of NUTS regions is accessible via the Eurostat website (xlsx, 500kB).

from nomenclature import nuts

# Access NUTS region information
nuts.codes       # List of all NUTS codes
nuts.names       # List of all NUTS region names

# Query specific NUTS levels
nuts.get(level=3)            # Get all NUTS3 regions

# Query by country
nuts.get(country_code="AT")  # Get all NUTS regions in Austria

NutsProcessor

The NutsProcessor class provides automated aggregation of scenario data across NUTS regions. It performs hierarchical aggregation in the following order:

  1. NUTS3 → NUTS2

  2. NUTS2 → NUTS1

  3. NUTS1 → Country

  4. Country → European Union (if ≥ 23 of the 27 EU member states are present)

  5. Country + UK → European Union and United Kingdom (if the United Kingdom is also present)

The EU-level aggregations (steps 4-5) are only performed if the corresponding target regions (European Union and European Union and United Kingdom) are defined in the project’s region codelist. If fewer than 23 EU member states are present in the data, the EU aggregation is skipped silently.

The processor ensures that regional data is consistently aggregated and validated according to the configured NUTS regions and variable code lists.

Consider the example below for configuring a project using NUTS aggregation. The nomenclature.yaml in the project directory is as follows:

dimensions:
  - region
  - variable
definitions:
  region:
    nuts:nuts:
    nuts-1: [ AT ]
    nuts-2: [ AT ]
    nuts-3: [ AT ]
    country: true
processors:
  nuts: [ Model A ]

With this configuration, calling process() will automatically instantiate and apply the NutsProcessor.

import pyam
from nomenclature import DataStructureDefinition, process

df = pyam.IamDataFrame(data="path/to/file.csv")
dsd = DataStructureDefinition("definitions")
aggregated_data = process(df, dsd)

The data is aggregated for the applicable variables, creating the common region Austria (AT) from its constituent NUTS subregions. The country-level regions must be defined in a region definition file or by setting definitions.region.country as true in the configuration file (see Adding NUTS to the region codelist).

Note

Only NUTS regions explicitly listed under definitions.region.nuts are added to the output. The NutsProcessor always aggregates through all levels. The final output keeps the NUTS levels that are listed in the configuration; intermediate levels that are not listed are dropped from the result. In the example above, all three levels (NUTS1, NUTS2, NUTS3) are listed, so the final output includes the original NUTS3 data as well as the aggregated NUTS2 and NUTS1 regions alongside the country-level result. If only nuts-3 were listed, only the NUTS3 regions and the country total would be retained; the aggregated NUTS2 and NUTS1 regions would be discarded.

Note

Only models listed under processors.nuts in nomenclature.yaml are processed by NutsProcessor. Data for other models is passed through unchanged. If a NUTS region appears in the data for a listed model but the corresponding country is missing from definitions.region.nuts, a ValueError is raised.

class nomenclature.processor.nuts.NutsProcessor(*, input_data=None, input_meta=None, output_data=None, output_meta=None, fail_ok=False, variable_codelist, region_codelist, models)[source]

NUTS region aggregation mappings for scenario processing

Methods

apply(df)

Apply NUTS region aggregation.

from_definition(dsd[, models])

Instantiate from a DataStructureDefinition.
apply(df)[source]

Apply NUTS region aggregation.

Parameters:
dfIamDataFrame

Input data to be aggregated.

Returns:
IamDataFrame

Aggregated data.

Raises:
ValueError

If a NUTS region in df is not listed in definitions.region.nuts.

UnknownRegionError

If the result contains regions not defined in the region codelist.

classmethod from_definition(dsd, models=None)[source]

Instantiate from a DataStructureDefinition.

Parameters:
dsdDataStructureDefinition

Project data structure definition.

modelslist[str], optional

Models to apply NUTS aggregation to. Defaults to the list configured under config.processor.nuts in dsd.

Raises:
ValueError

If no models are configured for NUTS processing.