💻 Command Line Interface (CLI)
As of v3.2.0, SounderPy includes a command line interface (CLI) tool for retrieving, saving, and plotting atmospheric vertical profile data directly from the command line.
After installing SounderPy, the CLI can be launched with either:
sounderpy --help
or:
python -m sounderpy --help
Checking the Installed Version
To print the installed SounderPy version:
sounderpy --version
Getting Data With The CLI
The CLI data retrieval is organized around five primary commands:
sounderpy
├── obs
├── model
├── bufkit
├── acars
│ ├── list
│ └── get
└── file
The commands provide access to:
obs: Observed RAOB and IGRAv2 vertical profiles.model: Model and reanalysis vertical profiles, including RAP/RUC, ERA5, and NCEP datasets.bufkit: Forecast vertical profiles from BUFKIT.acars: Listing and retrieval of ACARS aircraft vertical profiles.file: A local SHARPpy-format sounding file.
Help is available for the main CLI and for each command by using --help
Observed Soundings
Observed RAOB or IGRAv2 profiles can be retrieved with:
sounderpy obs STATION YYYY-MM-DD HH
where STATION is a valid RAOB or IGRAv2 station identifier and HH is
the UTC hour from 00 through 23.
For example:
sounderpy obs DTX 2024-05-21 00
By default, SounderPy prints a concise summary of the returned profile, including site information, valid time, number of vertical levels, and the pressure and height ranges.
Model Reanalysis Data
Model reanalysis profiles are retrieved with:
sounderpy model MODEL LAT LON YYYY-MM-DD HH
For example, a RAP reanalysis profile can be requested with:
sounderpy model rap-ruc 44.58 -100.82 2024-08-28 18
MODEL is rap-ruc (or rap / ruc), era5, or ncep. ERA5 comes from the Copernicus Climate
Data Store and needs a free CDS API key saved in ~/.cdsapirc.
Area Averaging
The model retrieval command uses an area-average box size of 0.10 degrees by
default. A different box size can be supplied with --box-size:
sounderpy model rap-ruc 44.58 -100.82 2024-08-28 18 \
--box-size 0.25
The box size must be greater than zero.
Targeting a Dataset
When supported by the underlying SounderPy retrieval function, a specific
dataset may be supplied with --dataset (such as with RAP & RUC data from NCEI):
sounderpy model MODEL LAT LON YYYY-MM-DD HH \
--dataset DATASET
If --dataset is not supplied, SounderPy uses its normal automatic dataset
selection logic.
BUFKIT Forecast Profiles
BUFKIT profiles use the following structure:
sounderpy bufkit MODEL STATION FHR
where FHR is the requested forecast hour and MODEL is one of gfs, rap, hrrr, or rrfs.
NAM and NAM Nest (nam, namnest) are discontinued, so they are only available for archived runs
(--run).
For example:
sounderpy bufkit gfs KMOP 6
If no model initialization time is given, SounderPy attempts to retrieve the most recent available BUFKIT run.
Archived BUFKIT Runs
An archived initialization time can be selected with --run:
sounderpy bufkit gfs KMOP 6 \
--run 2023-08-05 12
The two values following --run are the model initialization date
(YYYY-MM-DD) and UTC initialization hour (HH).
ACARS Aircraft Observations
ACARS data use two CLI actions: list and get.
Listing Available Profiles
To list available ACARS profile identifiers for a particular date and hour:
sounderpy acars list 2024-05-21 18
Each available profile identifier is printed to the terminal.
The list may instead be returned as JSON:
sounderpy acars list 2024-05-21 18 --json
Retrieving a Profile
After identifying an available ACARS profile, retrieve it with:
sounderpy acars get YYYY-MM-DD HH PROFILE_ID
For example:
sounderpy acars get 2024-05-21 18 BNA_1820
Use a profile identifier returned by sounderpy acars list for the requested
date and hour.
Local SHARPpy Files
A SHARPpy-format sounding file, such as one saved earlier with --output profile.snd, can be read with:
sounderpy file PATH
For example, to export it as CSV:
sounderpy file oax.snd --output oax.csv
A SHARPpy file holds the station ID and valid time but not the location, so --plot and --params
need --latlon LAT LON (the map inset, and the latitude used for temperature advection):
sounderpy file oax.snd \
--latlon 41.32 -96.37 \
--plot sounding \
--plot-file oax_sounding.png
The plot title uses the file name, station ID, and valid time, and the station elevation is taken from the lowest height in the file.
Saving Data to a File
Saving to JSON
Retrieved profile data can be written to standard output as JSON with
--json:
sounderpy obs DTX 2024-05-21 00 --json
The JSON output preserves units for MetPy/Pint quantities. Quantity fields are
represented using separate value and units entries.
For example, a quantity may have the general form:
{
"value": [
1000.0,
975.0,
950.0
],
"units": "hectopascal"
}
JSON output can be redirected to a file:
sounderpy obs DTX 2024-05-21 00 --json > dtx.json
It can also be piped into another command-line program:
sounderpy obs DTX 2024-05-21 00 --json | python -m json.tool
When --json is used, SounderPy suppresses its normal status output so that
standard output contains valid JSON. With --json --verbose, the status
output is written to standard error instead, so standard output stays valid JSON.
Note
--json cannot be combined with an interactive plot. To produce JSON and
a plot in the same command, save the plot using --plot-file.
Saving to CSV, SHARPPY, CM1
Retrieved profiles can be saved to standard sounding file types from the CLI with -o or --output:
sounderpy obs DTX 2024-05-21 00 \
--output dtx.csv
Format |
|
Recognized filename extensions |
|---|---|---|
CSV |
|
|
SHARPpy |
|
|
CM1 |
|
|
For example:
sounderpy obs DTX 2024-05-21 00 \
--output dtx.snd
or:
sounderpy obs DTX 2024-05-21 00 \
--output input_sounding.cm1
Plotting from the CLI
SounderPy can generate a sounding or hodograph immediately after retrieving a profile.
Opening a plot in a window needs a display and an interactive Matplotlib backend. Without one
(for example, on a server or over SSH), the CLI stops before downloading anything and asks for
--plot-file instead.
Sounding Plot
To open a sounding interactively:
sounderpy obs DTX 2024-05-21 00 \
--plot sounding
To save the sounding instead:
sounderpy obs DTX 2024-05-21 00 \
--plot sounding \
--plot-file dtx_sounding.png
The --plot-file extension sets the image format (.png, .pdf, .svg, .jpg, and the
other formats Matplotlib writes). A file name without an extension is saved as .png.
Hodograph
To create a hodograph:
sounderpy obs DTX 2024-05-21 00 \
--plot hodograph
To save the hodograph:
sounderpy obs DTX 2024-05-21 00 \
--plot hodograph \
--plot-file dtx_hodograph.png
Plot Options
Several SounderPy plotting options are available through the CLI. They all need --plot.
--color-blind, --show-theta, --mode, --obs, --parcels, and --background-parcels
apply to --plot sounding only. --storm-motion, --modify-sfc, and --mode change the
calculation as well, so they also work with --params (see Calculated Parameters).
Dark Mode
sounderpy obs DTX 2024-05-21 00 \
--plot sounding \
--dark-mode \
--plot-file dtx_dark.png
Color Blind Friendly Mode
For sounding plots, --color-blind enables SounderPy’s
color-deficiency-friendly temperature/dewpoint styling:
sounderpy obs DTX 2024-05-21 00 \
--plot sounding \
--color-blind \
--plot-file dtx_colorblind.png
Theta and Theta-e
For sounding plots, --show-theta shows theta and theta-e:
sounderpy obs DTX 2024-05-21 00 \
--plot sounding \
--show-theta \
--plot-file dtx_theta.png
Storm-Relative Hodograph
A hodograph can be transformed to storm-relative coordinates with
--storm-relative. It works with --plot hodograph and with the hodograph on
--plot sounding:
sounderpy obs DTX 2024-05-21 00 \
--plot hodograph \
--storm-relative \
--plot-file dtx_sr_hodograph.png
Map Zoom
The map inset zoom level can be changed with --map-zoom. A value of zero
disables the map/radar inset:
sounderpy obs DTX 2024-05-21 00 \
--plot sounding \
--map-zoom 0 \
--plot-file dtx_sounding.png
Disabling the map inset can be useful when working offline or when a map/radar inset is not needed.
Plot Resolution
The output resolution can be changed with --dpi:
sounderpy obs DTX 2024-05-21 00 \
--plot sounding \
--dpi 200 \
--plot-file dtx_sounding.png
Winter Sounding
--mode chooses the sounding plot: severe (the default), winter, or
auto, which draws the winter sounding when the surface wet-bulb temperature
is below 35 degrees F. --obs adds the latest surface observation near the
profile to a winter sounding (from the Iowa Environmental Mesonet), so it needs
--mode winter or --mode auto:
sounderpy bufkit hrrr KGFK 1 \
--run 2024-01-24 12 \
--plot sounding \
--mode winter \
--obs \
--plot-file kgfk_winter.png
See ❄️ Winter Soundings for a guide to the winter sounding. The winter sounding
doesn’t use --show-theta, --storm-relative, --parcels, or --background-parcels, so
they can’t be combined with --mode winter.
Storm Motion
--storm-motion sets the storm motion for the plot and the parameters: right_moving (the
default), left_moving, mean_wind, or a direction in degrees and a speed in knots:
sounderpy obs DTX 2024-05-21 00 \
--plot hodograph \
--storm-motion 250 30 \
--plot-file dtx_hodograph.png
Surface Modification
--modify-sfc changes the surface with KEY=VALUE pairs: T and Td (°C), ws (kt)
with wd (degrees), method (mix, replace, or blend), and depth (m, for
blend). See Surface Modification Logic for what each method does. The change applies to the plot and
--params; a file saved with --output keeps the original surface.
sounderpy bufkit hrrr KGFK 1 \
--run 2024-01-24 12 \
--plot sounding \
--mode winter \
--modify-sfc T=-6 Td=-7 method=blend depth=300 \
--plot-file kgfk_blend.png
Radar
--radar chooses the map’s radar: mosaic (the default; the CONUS mosaic is only available for
recent dates), single (the nearest NEXRAD site), or none. --radar-time draws the radar at
the profile’s valid time (sounding, the default) or now. Both need the map, so they can’t be
combined with --map-zoom 0.
sounderpy obs OAX 2014-06-16 18 \
--plot sounding \
--radar single \
--plot-file oax_radar.png
Special Parcels
--parcels draws special parcels from the ecape_parcel library on a severe sounding, by code
(mu, ml, or sb; ps pseudoadiabatic or ia irreversible adiabatic; cape or
ecape), and --background-parcels draws more of them faded behind. --parcels simple draws
only the standard parcels and skips the default MUECAPE trace, which is faster. See
Parcel Logic for the parcel codes.
sounderpy obs DTX 2024-05-21 00 \
--plot sounding \
--parcels mu_ia_ecape \
--background-parcels mu_ps_cape sb_ps_cape \
--plot-file dtx_parcels.png
Combining Retrieval, Export, and Plotting
A primary advantage of the CLI is that one retrieved profile can be used for multiple outputs without repeating the retrieval.
For example, the following command retrieves a RAP profile, exports the profile to CSV, and saves a sounding image:
sounderpy model rap-ruc 44.58 -100.82 2024-08-28 18 \
--box-size 0.25 \
--output rap_20240828_18z.csv \
--plot sounding \
--map-zoom 0 \
--plot-file rap_20240828_18z.png
Calculated Parameters
--params prints key parameters under the profile summary: CAPE, CIN, LCL, and ECAPE for each
parcel, DCAPE, PWAT, lapse rates, freezing levels, the storm motion, SRH, bulk shear, and composite
indices. With --mode winter (or --mode auto when the surface wet-bulb is below 35 °F), it
adds the precipitation type, the phase from source to surface, the snow ratio, the DGZ, and the
freezing drizzle and freezing fog levels.
sounderpy bufkit hrrr KGFK 1 \
--run 2024-01-24 12 \
--params \
--mode auto
--storm-motion and --modify-sfc change the parameters the same way they change the plot.
With --json, every calculated value is added to the JSON as "params", next to the profile:
sounderpy obs DTX 2024-05-21 00 --params --json | python -c "import json, sys; print(json.load(sys.stdin)['params']['thermo']['mlcape'])"
Verbose Output
The CLI hides SounderPy’s internal retrieval and plotting status messages and warnings by default, producing cleaner command-line output. SounderPy’s own warnings about the figure or data, such as a radar mosaic that isn’t available for the profile’s date, are still shown, one line each:
sounderpy: warning: Radar mosaic could not be plotted: no radar mosaic for 08/05/2023 18:00Z: the mosaic archive only keeps about the last month. Use the nearest NEXRAD site for older dates (radar='single', or --radar single in the CLI)
To display the underlying SounderPy status messages and warnings, and the full
Python traceback when something fails, use -v or --verbose:
sounderpy obs DTX 2024-05-21 00 --verbose
Input Validation and Errors
The CLI validates its inputs before beginning a retrieval, so a mistake is reported without waiting for a download. Besides the values below, it checks that:
--outputhas a recognized extension, or--formatis given (and--formatis only used with--output);plot options are only used with
--plot, and sounding-only options only with--plot sounding;--storm-motion,--modify-sfc, and--modeare used with--plotor--params, and their values are valid;--parcelscodes are valid, and severe-only options aren’t combined with--mode winter;--radarand--radar-timearen’t combined with--map-zoom 0;filehas--latlonfor--plotand--params;--plot-filehas an extension Matplotlib can write;--jsonis combined with a saved plot, not a plot window.
Dates
Dates must use the form:
YYYY-MM-DD
Hours
Hours are interpreted as UTC and must be integers from 0 through 23. Both of the following are accepted:
0
00
Latitude and Longitude
For model retrieval:
latitude must be between -90 and 90 degrees;
longitude must be between -180 and 180 degrees.
Forecast Hours
BUFKIT forecast hours must be zero or greater.
Map Zoom and DPI
--map-zoom must be zero or greater, and --dpi greater than zero.
Box Size
The model --box-size value must be greater than zero.
Invalid command-line arguments produce a descriptive error and a non-zero exit status:
0: success;1: the retrieval, export, or plot failed (for example, no data for that station and time);2: invalid arguments or options;130: interrupted with Ctrl+C.
Additional Examples
Retrieve an observed profile and save it as CSV:
sounderpy obs DTX 2024-05-21 00 \
--output dtx.csv
Retrieve RAP reanalysis and save a sounding:
sounderpy model rap-ruc 44.58 -100.82 2024-08-28 18 \
--box-size 0.25 \
--plot sounding \
--map-zoom 0 \
--plot-file rap_sounding.png
Retrieve an archived BUFKIT profile and export it:
sounderpy bufkit gfs KMOP 6 \
--run 2023-08-05 12 \
--output kmop_gfs_f006.csv
Create a storm-relative hodograph from an observed sounding:
sounderpy obs DTX 2024-05-21 00 \
--plot hodograph \
--storm-relative \
--map-zoom 0 \
--plot-file dtx_sr_hodograph.png
Retrieve JSON for use in another program:
sounderpy obs DTX 2024-05-21 00 --json > dtx.json
Using the Python Module Entry Point
The CLI may also be executed through Python:
python -m sounderpy obs DTX 2024-05-21 00
This form supports the same commands and options as the sounderpy console
command.