Command line interface

The nomenclature package offers a command line interface (CLI) to ensure that the definitions (i.e., codelists) and model mappings for a project are valid. This can be useful to ensure that all yaml files can be parsed correctly and that definitions and mappings are internally consistent.

Standard usage

Run the following in a command line to ensure that a project folder is a valid configuration for the nomenclature package.

nomenclature validate-project /project/folder/

Documentation

nomenclature

nomenclature [OPTIONS] COMMAND [ARGS]...

check-region-aggregation

Perform region processing and compare aggregated and original data

Parameters

input_data_filePath

Location of input data

workflow_directoryPath

Location of the workflow directory containing codelists and model mappings, by default .

definitionsstr

Definitions folder inside workflow_directory, by default “definitions”

mappingsstr

Model mapping folder inside workflow_directory, by default “mappings”

processed_dataOptional[Path]

If given, exports the results from region processing to a file called processed_data, by default “results.xlsx”

differencesOptional[Path]

If given, exports the differences between aggregated and model native data to a file called differences, by default None

Example

This example runs the region processing for input data located in input_data.xlsx based on a workflow directory called workflow_directory. The results of the aggregation will be exported to results.xlsx and the differences to differences.xlsx.

$ nomenclature check-region-processing input_data.xlsx -w workflow_directory

–processed_data results.xlsx –differences differences.xlsx

nomenclature check-region-aggregation [OPTIONS] INPUT_DATA_FILE

Options

-w, --workflow-directory <workflow_directory>

-d, --definitions <definitions>

-m, --mappings <mappings>

--processed-data <processed_data>

--differences <differences>

Arguments

INPUT_DATA_FILE

Required argument

export-definitions

Assert that path is a valid project nomenclature

Parameters

pathPath

Project directory to be exported

targetPath

Path and file name for the exported file

nomenclature export-definitions [OPTIONS] PATH TARGET

Arguments

PATH

Required argument

TARGET

Required argument

validate-project

Assert that path is a valid project nomenclature

Parameters

pathPath

Project directory to be validated

definitionsstr, optional

Name of the definitions folder, defaults to “definitions”

mappingsstr, optional

Name of the mappings folder, defaults to “mappings” (if this folder exists)

required_data: str, optional

Name of the required data folder, default to “required_data” (if folder exists)

dimensionsList[str], optional

Dimensions to be checked, defaults to all sub-folders of definitions

Example

$ nomenclature validate-project .

–definitions <def-folder> –mappings <map-folder> –dimension <folder1> –dimension <folder2> –dimension <folder3>

Note

This test includes three steps:

1. Test that all yaml files in definitions/ and mappings/ can be correctly read as yaml files. This is a formal check for yaml syntax only.

2. Test that all files in definitions/ can be correctly parsed as a DataStructureDefinition object comprised of individual codelists.

3. Test that all model mappings in mappings/ can be correctly parsed as a RegionProcessor object. This includes a check that all regions mentioned in a model mapping are defined in the region codelist.

nomenclature validate-project [OPTIONS] PATH

Options

--definitions <definitions>

Optional name for definitions folder

--mappings <mappings>

Optional name for mappings folder

--required-data <required_data>

Optional name for required data folder

--dimension <dimensions>

Optional list of dimensions

Arguments

PATH

Required argument

validate-yaml

Assert that all yaml files in path are syntactically valid.

nomenclature validate-yaml [OPTIONS] PATH

Arguments

PATH

Required argument