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_dataPath, optional

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

differencesPath, optional

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

list-missing-variables

Create a list of variables that are not part of the variable codelist

Parameters
dataPath

path to the IAMC data file, can be .xlsx or .csv

workflow_directoryPath, default current working directory

Path to the workflow directory that contains the variable codelist

target_filePath | None

Name of the target variable definition file, optional, defaults to ‘variables.yaml’

Example

The following command will add all the missing variables to the file new_variables.yaml located in my_workflow/definitions/variable:

$ nomenclature list-missing-variables input_data.xlsx –workflow-directory

my_workflow

nomenclature list-missing-variables [OPTIONS] DATA

Options

--workflow-directory <workflow_directory>
--target-file <target_file>

Arguments

DATA

Required argument

run-workflow

Run a given input file through a workflow function defined in a workflow.py

Parameters
input_filePath

Input data file, must be IAMC format, .xlsx or .csv

workflow_filePath

Path to the workflow file, default: current working directory / “workflow.py”

workflow_functionstr

Name of the workflow function inside the workflow file, default: main

output_filePath | None

Path to the output file where the processing results is saved, nothing is saved if None is given, default: None

Raises
ValueError

If the workflow_file does not have the specified workflow_function

nomenclature run-workflow [OPTIONS] INPUT_FILE

Options

--workflow-file <workflow_file>
--workflow-function <workflow_function>
--output-file <output_file>

Arguments

INPUT_FILE

Required argument

validate-project

Assert that path is a valid project nomenclature

Parameters
pathPath

Project directory to be validated

definitionsstr, optional

Name of ‘definitions’ folder, defaults to “definitions”

mappingsstr, optional

Name of ‘mappings’ folder, defaults to “mappings”

required_data: str, optional

Name of folder for ‘required data’ criteria, default to “required_data”

validate_data: str, optional

Name of folder for data validation criteria, default to “validate_data”

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 parsed 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.

  4. Test that all required-data and data-validation files can be parsed correctly and are consistent with the definitions.

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

--validate_data <validate_data>

Optional name for validation folder

--dimension <dimensions>

Optional list of dimensions

Arguments

PATH

Required argument

validate-scenarios

Validate a scenario file against the codelists of a project

Example
$ nomenclature validate-scenarios <input-file>

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

Parameters
input_filePath

Input data file, must be IAMC format, .xlsx or .csv

definitionsPath

Definitions folder with codelists, by default “definitions”

dimensionslist[str], optional

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

Raises
ValueError

If input_file validation fails against specified codelist(s).

nomenclature validate-scenarios [OPTIONS] INPUT_FILE

Options

--definitions <definitions>

Optional name for definitions folder

--dimension <dimensions>

Optional list of dimensions

Arguments

INPUT_FILE

Required argument

validate-yaml

Assert that all yaml files in path are syntactically valid.

nomenclature validate-yaml [OPTIONS] PATH

Arguments

PATH

Required argument