Model registration

This guide presents instructions for “registering a model” for a project.

Model registration for a nomenclature-based project requires two specifications:

  • a list of region names as they should appear in the processed scenario data
    (e.g., after processing as part of the upload to a Scenario Explorer instance)

  • a model mapping to perform region aggregation from native_regions to common_regions and renaming of model native regions (optional)

Please read the detailed explanations of The region codelist and Region processing using model mappings before proceeding with model registration.

Option 1) Registration using an Excel template

Please use the Excel template and send it to the project managers by email.

Converting Excel template to YAML

If you have filled out the Excel model registration template and need to convert it to YAML format, you can use the Command line interface command parse-model-registration:

nomenclature parse-model-registration registration.xlsx

This command reads the Excel file and generates two sets of YAML files:

  • Region definitions: Created in definitions/region/ (default location)

  • Model mappings: Created in mappings/ (default location)

You can specify custom output folders using the --definition-path and --mappings-path options:

nomenclature parse-model-registration registration.xlsx \
    --definition-path ./custom/definitions/region \
    --mappings-path ./custom/mappings

The command automatically:

  • Parses the “Common-Region-Mapping” sheet to generate model mapping YAML files

  • Parses the “Region-Country-Mapping” sheet (if present) to generate region definitions with country lists

  • Adds an aggregation to “World” from R5 regions (if present)

Option 2) Registration using a GitHub pull request

The preferred approach for model registration is starting a GitHub pull request. Please contact the administrators if permissions for the project repository are required.

A model-registration pull request adds the following files (if required).

Native-region definitions

If the model reports results at a model-specific regional resolution (e.g., other than national countries), add a file <your-model_vX.X>.yaml in the folder definitions/region/model_native_regions/.

This file should follow the region-naming conventions of The region codelist. The hierarchy property should be the model name inluding the version number.

Model mapping for region processing

If the scenario-processing workflow should execute a region-processing step, add a file <your-model_vX.X>.yaml in the folder mappings/.

This file should follow the region-naming conventions of Region processing using model mappings.

Continuous integration

When registering a model via a pull request to a GitHub project repository, a GitHub Actions workflow is executed for ensuring that the model mapping is valid. This serves to ensure that there are no typos or inconsistencies in the mapping or region names. For example, only regions defined in the region codelist can be used as targets for renaming or aggregation in the region-aggregation.

You can run the validation locally using the function assert_valid_structure() of the Command line interface.