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:
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.
Test that all files in definitions can be correctly parsed as a
DataStructureDefinition
object comprised of individual codelists.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.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