Command-line Interface (CLI) Reference

The VISION Toolkit program header

.______________________________________________.
|   _     _  _   ______  _  _______  _______   |
|  (_)   (_)| | / _____)| |(_______)(_______)  |
|   _     _ | |( (____  | | _     _  _     _   |
|  | |   | || | \____ \ | || |   | || |   | |  |
|   \ \ / / | | _____) )| || |___| || |   | |  |
|    \___/  |_|(______/ |_| \_____/ |_|   |_|  |
|   _______             _   _      _           |
|  (_______)           | | | |    (_)   _      |
|      _   ___    ___  | | | |  _  _  _| |_    |
|     | | / _ \  / _ \ | | | |_/ )| |(_   _)   |
|     | || |_| || |_| || | |  _ ( | |  | |_    |
|     |_| \___/  \___/  \_)|_| \_)|_|   \__)   |
.______________________________________________.

Note

Default values for configuration items are only processed in once the CLI and configuration file are both processed, therefore default values are not attached via the Python argument parser, so not listed automatically here. For default values, consult the dictionary of defaults used as the canonical source of these, namely: visiontoolkit.constants.CONFIG_DEFAULTS.

Virtual Integration of Satellite and In-Situ Observation Networks (VISION) toolkit flight simulator

usage: visiontoolkit [-h] [-v] [-c CONFIG_FILE] [-p PREPROCESS_MODE_OBS]
                     [--preprocess-mode-model PREPROCESS_MODE_MODEL] [--orography OROGRAPHY]
                     [-s START_TIME_OVERRIDE] [-o OBS_DATA_PATH] [-m MODEL_DATA_PATH]
                     [--chosen-obs-field CHOSEN_OBS_FIELD] [--chosen-model-field CHOSEN_MODEL_FIELD]
                     [--skip-all-plotting] [-d OUTPUTS_DIR] [-f OUTPUT_FILE_NAME]
                     [--history-message HISTORY_MESSAGE] [--halo-size HALO_SIZE]
                     [-i SPATIAL_COLOCATION_METHOD] [-z VERTICAL_COLOCATION_COORD]
                     [--source-axes SOURCE_AXES] [--plotname-start PLOTNAME_START]
                     [--show-plot-of-input-obs] [-t] [--cfp-cscale CFP_CSCALE]
                     [--cfp-mapset-config CFP_MAPSET_CONFIG]
                     [--cfp-input-levs-config CFP_INPUT_LEVS_CONFIG]
                     [--cfp-input-general-config CFP_INPUT_GENERAL_CONFIG]
                     [--cfp-input-track-only-config CFP_INPUT_TRACK_ONLY_CONFIG]
                     [--cfp-output-levs-config CFP_OUTPUT_LEVS_CONFIG]
                     [--cfp-output-general-config CFP_OUTPUT_GENERAL_CONFIG]
                     [--satellite-plugin-config SATELLITE_PLUGIN_CONFIG] [--regrid-z-coord REGRID_Z_COORD]
                     [-r REGRID_METHOD] [--chosen-obs-fields CHOSEN_OBS_FIELDS]
                     [--chosen-model-fields CHOSEN_MODEL_FIELDS]

Named Arguments

-v, --verbose

provide more detailed output, where multiple calls will increase the verbosity yet further to a maximum at -vvv correpsonding to logging level DEBUG, where no usage gives a default of logging level WARNING

Default: 0

-c, --config-file

configuration file in JSON format to supply configuration, which overrides any configuration provided by other command-line options, if duplication of input occurs

-p, --preprocess-mode-obs

specify a pre-processing mode so a set plugin is applied to pre-process the observational data in an apprpriate way, current options being ‘flight’ and ‘satellite’ where by default we apply no pre-processing

--preprocess-mode-model

specify a pre-processing mode so a set plugin is applied to pre-process the model data in an apprpriate way, current options being ‘UM’ and ‘WRF’ where by default we apply no pre-processing

--orography

if the model data input is PP and has vertical coordinates in terms of atmosphere hybrid height then specify the path to the external orography applicable to the model data requred for calculation of the vertical coordinates

-s, --start-time-override

if given, a datetime in UTC timezone with which to override the observational datetimes so that the colocation is conducted with the spatial components of the observational path but assuming the given start time and not the actual one

-o, --obs-data-path

path location of the observational data, which can be provided in any form accepted by the ‘cf.read’ files argument, see: https://ncas-cms.github.io/cf-python/function/cf.read.html

-m, --model-data-path

path location of the model data, which can be provided in any form accepted by the ‘cf.read’ files argument, see: https://ncas-cms.github.io/cf-python/function/cf.read.html

--chosen-obs-field

string corresponding to a valid ‘select_field’ argument to select a unique field from the FieldList of the read-in observational data, else if not specified the FieldList is assumed to be of size one and the single field is extracted.

--chosen-model-field

string corresponding to a valid ‘select_field’ argument to select a unique field from the FieldList of the read-in model data, else if not specified the FieldList is assumed to be of size one and the single field is extracted.

--skip-all-plotting

Do not generate plots to preview the input or show the output fields

Default: False

-d, --outputs-dir

path location of the top-level directory to create outputs in

-f, --output-file-name

name including extension to give the result output file

--history-message

message that gets added to the ‘history’ property on the output file

--halo-size

size of the halo to apply for subspacing, see the section ‘Halos’ under ‘https://ncas-cms.github.io/cf-python/method/cf.Domain.subspace.html?highlight=halo’ for details.

-i, --spatial-colocation-method

interpolation method to apply for the spatial colocation, see ‘method’ parameter to ‘cf.regrids’ method used under-the-hood to do this for options: https://ncas-cms.github.io/cf-python/method/cf.Field.regrids.html

-z, --vertical-colocation-coord

vertical (z) coordinate to use as the vertical component in the spatial interpolation step of colocation, where either a pressure or an altitude CF standard name is expected

--source-axes

identifies the source grid’s X and Y dimensions if they cannot be inferred from the existence of 1D dimension coordinates

--plotname-start

initial text to use in the names of all plots generated

--show-plot-of-input-obs

flag to indicate whether to show plots of the input observational data before the colocation logic begins, as a preview

Default: False

-t, --plot-of-input-obs-track-only

flag to indicate whether only the track/trajectory of the observational data is shown, as opposed to the data on the track, for the input observational data preview plots

Default: False

--cfp-cscale

cf-plot plotting configuration as a string to set the colour scale for the (input preview and) output plots, ee: https://ncas-cms.github.io/cf-plot/build/cscale.html#cscale

--cfp-mapset-config

cf-plot plotting configuration as a dictionary to set the mapping parameters for the (input preview and) output plots, see: https://ncas-cms.github.io/cf-plot/build/mapset.html#mapset

--cfp-input-levs-config

cf-plot plotting configuration as a dictionary to set the contour levels for the input preview plots, see: https://ncas-cms.github.io/cf-plot/build/levs.html#levs

--cfp-input-general-config

cf-plot plotting configuration as a dictionary to set the general plotting variables for the input preview full plot, see:https://ncas-cms.github.io/cf-plot/build/setvars.html#setvars[TODO CLARIFY/SEPARATE SETVARS AND PLOT CALL CONFIG.]

--cfp-input-track-only-config

cf-plot plotting configuration as a dictionary to set the general plotting variables for track-only input preview plot, see:https://ncas-cms.github.io/cf-plot/build/setvars.html#setvars

--cfp-output-levs-config

cf-plot plotting configuration as a dictionary to set the contour levels for the output plots, see: https://ncas-cms.github.io/cf-plot/build/levs.html#levs

--cfp-output-general-config

cf-plot plotting configuration as a dictionary to set the general plotting variables for the output plots, see:https://ncas-cms.github.io/cf-plot/build/setvars.html#setvars[TODO CLARIFY/SEPARATE SETVARS AND PLOT CALL CONFIG.]

--satellite-plugin-config

dictionary to set the configuration values for the satellite plugin, where valid keys to set are ‘latitude’, ‘longitude’, ‘sensingtime’, ‘do_retrieval’, ‘sensingtime_msec’, ‘sensingtime_day’, ‘npres’ and ‘npi’.

--regrid-z-coord

NOW DEPRECATED: use ‘–vertical-colocation-coord’ instead. [vertical (z) coordinate to use as the vertical component in the spatial interpolation step]

-r, --regrid-method

NOW DEPRECATED: use ‘–spatial-colocation-method’ instead. regridding interpolation method to apply, see ‘method’ parameter to ‘cf.regrids’ method for options: https://ncas-cms.github.io/cf-python/method/cf.Field.regrids.html

--chosen-obs-fields

NOW DEPRECATED: use ‘–chosen-obs-field’ (non-plural) instead. Note that we no longer accept an integer corresponding to a FieldList index to take a field from like this keyword permitted, now we require a valid ‘select_field’ string argument.

--chosen-model-fields

NOW DEPRECATED: use ‘–chosen-model-field’ (non-plural) instead. Note that we no longer accept an integer corresponding to a FieldList index to take a field from like this keyword permitted, now we require a valid ‘select_field’ string argument.