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 Version 2

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] [-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] [--plot-mode PLOT_MODE]
                     [--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] [-t] [--skip-all-plotting]
                     [--show-plot-of-input-obs]

Named Arguments

-v, --verbose

provide more detailed output, where multiple calls will increase the verbosity yet further to a maximum at -vvv (3 v)corresponding to logging level ‘DEBUG’, where no specification gives a default of logging level ‘WARNING’ (0 v)

Default: 0

-c, --config-file

configuration file in JSON format to supply configuration, where any configuration provided by other command-line options will take precedence over the configuration file input, if duplication should occur

-p, --preprocess-mode-obs

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

--preprocess-mode-model

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

--orography

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

-s, --start-time-override

if given, a datetime in the UTC timezone with which to override the observational datetimes so that the co-location is conducted with the same spatial components of the observational path but assuming the given start time instead of the actual timestamped one when the data was collected/sampled

-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 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 extracted

-d, --outputs-dir

path location of the top-level directory in which to put the toolkit output(s)

-f, --output-file-name

name including extension to call the toolkit result output file

--history-message

message that is added to the ‘history’ property on the toolkit result 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=halos’ for context

-i, --spatial-colocation-method

interpolation method to apply for the spatial co-location, see the ‘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 co-location, where either a pressure or an altitude CF standard name is expected

--source-axes

a dictionary to identify the source grid’s X and Y dimensions if they cannot be inferred from the existence of 1D dimension coordinates, for context see: https://ncas-cms.github.io/cf-python/method/cf.Field.regrids.html?highlight=src_axes

--plotname-start

initial text to preface the names of all plots generated

--plot-mode

what if anything to plot with the toolkit (note this requires cf-plot to be installed at suitable version), where integer inputs represent the supported modes, which are: [0] to not plot anything (the default); [1] to plot both the outputs and, before starting co-location, as a means of verification and/or quick inspection, the observational input (with its data); [2] to plot only the outputs (the default mode, if plot-mode is not specified); and [3] to plot both the outputs and observational input but only show the track/swath of the inputs without the data on it to indicate the track/swath which the model field will then be co-located onto (the most relevant part of the observational input for VISION purposes)

--cfp-cscale

cf-plot plotting configuration as a string to set the colour scale for the (input preview and) output plots, see: 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

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

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

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

-r, --regrid-method

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

DEPRECATED: use ‘–chosen-obs-field’ (non-plural) instead and 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

DEPRECATED: use ‘–chosen-model-field’ (non-plural) instead and 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

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

DEPRECATED: use ‘–plot-mode’ instead [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

--skip-all-plotting

DEPRECATED: use ‘–plot-mode’ instead [Do not generate plots to preview the input or show the output fields]

Default: False

--show-plot-of-input-obs

DEPRECATED: use ‘–plot-mode’ instead [flag to indicate whether to show plots of the input observational data before the co-location logic begins, as a preview]

Default: False