User GuideΒΆ

The nomenclature package is used as part of the data upload process for integrated assessment model comparison studies that use the IIASA Scenario Explorer infrastructure. As part of the data processing workflow, nomenclature is used to perform two tasks, input data validation against codelists and region aggregation based on information given in model mappings.

The three parts of the processing workflow: codelists, model mappings and the actual processing code are usually hosted in a GitHub repository.

As an example, in the openENTRANCE project (github.com/openENTRANCE/openentrance) these three parts are the definitions/ and mappings/ folders which contain codelists and model mappings, and workflow.py which contains the processing code using nomenclature.

The validation and region-processing for a specific can be run locally by any user. In order to do so, the corresponding GitHub repository needs to be cloned, nomenclature installed and the main function in workflow.py be given a pyam.IamDataFrame of the model data as input.

When working with nomenclature, there are two main classes that the user interacts with, DataStructureDefinition and RegionProcessor.

The DataStructureDefinition class parses codelist files which define allowed values for validation. The most commonly used dimensions for validation in a in a model comparison or scenario exercise are variable and region.

The RegionProcessor parses model mapping files which define the renaming of native regions and aggregation to common regions.

The top-level function process() takes both of the above classes as input along with data in form of a pyam.IamDataFrame. The input data is aggregated using the RegionProcessor and validated using DataStructureDefinition.