rstool is an open source command-line program for converting radiosonde measurement data to NetCDF and calculation of derived physical quantities. It can also be used for the calculation of derived quantities from source quantities, such as exporting variables along a vertical profile from a model and letting rstool calculate the derived quantities (rstool prof prof input output).

Supported instruments:

• InterMet Systems (iMet) radiosondes, such as iMet-1-ABxn, data files produced by the iMetOS-II software (a directory containing .dat and .flt files).
• Windsond, data files produced by the Windsond software (.sounding).

Support for other instruments can be added by writing a Python module in rstool/drivers to read the data files produced by the radiosonde (see the template in rstool/drivers/template.py).

rstool converts radiosonde measurement data to NetCDF intrument-dependent intermediate (im), points (pts), and profile (prof) datasets and calculates derived physical quantities.

Usage: rstool input_type output_type input [surface] output

Arguments:

• input_type: See Input types below.
• output_type: See Output types below.
• input: Input file or directory.
• surface: Near-surface variables (NetCDF).
• output: Output file (NetCDF).

Input types:

• imet: InterMet Systems iMet-1-ABxn sounding. input should be a directory generated by the iMetOS-II software, containing .dat and .flt files.
• prof: rstool profile (prof) format (NetCDF). Vertically-interpolated quantities on pressure coordinates.
• pts: rstool points (pts) format (NetCDF). Collection of measurement points, not interpolated on vertical coordinates. The output of running rstool with the output type pts.
• im:instrument: Instrument-dependent intermediate (im) rstool format (NetCDF). instrument is one of imet or ws.
• ws: Windsond sounding. input should be a .sounding file generated by the Windsond software.

Output types:

• pts: Collection of measurement points (NetCDF).
• prof: Vertical profile calculated by interpolating the measurement points during the ascent of the radiosonde as a function of pressure (NetCDF).
• prof:desc: The same as prof, but for the descending path of the radiosonde (if present in the input data).
• im: Instrument-dependent intermediate rstool format (NetCDF).

The following input/output type combinations are possible, where instrument is imet or ws:

• instrument im: An instrument native format to instrument-dependent intermediate format (NetCDF).
• instrument pts: An instrument native format to the points format (NetCDF).
• instrument prof: An instrument native format to the profile format (NetCDF).
• instrument prof:desc: An instrument native format to the descending profile format (NetCDF).
• im:instrument pts: An instrument-dependent intermediate format (NetCDF) to the points format (NetCDF).
• im:instrument prof: An instrument-dependent intermediate format (NetCDF) to the profile format (NetCDF).
• im:instrument prof:desc: An instrument-dependent intermediate format (NetCDF) to the descending profile format (NetCDF).
• pts prof: The points format (NetCDF) to the profile format (NetCDF).
• pts prof:desc: The points format (NetCDF) to the descending profile format (NetCDF).
• prof prof: The profile format (NetCDF) to the profile format (NetCDF). This can be used to calculate derived physical quantities from a set source quantities.

Convert a Windsond sounding 2000-01-01T0000.sounding to the profile format:

rstool ws prof 2000-01-01T0000.sounding 2000-01-01T0000_prof.nc

Convert an iMet sounding in a directory 2000-01-01T0000 to the profile format:

rstool imet prof 2000-01-01T0000 2000-01-01T0000_prof.nc

Convert a Windond sounding 2000-01T01_0000.sounding to the Windsond intermediate format:

rstool ws im 2000-01-01T0000.sounding 2000-01-01T0000_im.nc

Convert an iMet sounding in a directory 2000-01-01T0000 to the points format:

rstool imet pts 2000-01-01T0000 2000-01-01T0000_pts.nc

Convert the Windsond intermediate format to the points format:

rstool im:ws pts 2000-01-01T0000_im.nc 2000-01-01T0000_pts.nc

Convert the points format to the profile format:

rstool pts prof 2000-01-01T0000_pts.nc 2000-01-01T0000_prof.nc

Calculate derived physical quantities from source physical quantities in the input (profile format):

rstool prof prof input.nc output.nc

It is recommended to run rstool on Linux.

On Debian-derived distributions (Ubuntu, Devuan, ...), install the required system packages with:

sudo apt install python3 python3-pip pipx

On Fedora, install the required system packages with:

sudo yum install python3 pipx

Install rstool:

pipx install rstool

Make sure that $HOME/.local/bin is included in the PATH environment variable if not already. This can be done with pipx ensurepath.

You should now be able to run rstool.

To uninstall:

pipx uninstall rstool

Open the Terminal. Install rstool with:

python3 -m pip install rstool

Make sure that /Users/<user>/Library/Python/<version>/bin is included in the PATH environment variable if not already, where <user> is your system user name and <version> is the Python version. This path should be printed by the above command. This can be done by adding this line to the file .zprofile in your home directory and restarting the Terminal:

PATH="$PATH:/Users/<user>/Library/Python/<version>/bin"

You should now be able to run rstool.

To uninstall:

python3 -m pip uninstall rstool

Install Python 3. In the installer, tick Add python.exe to PATH.

Open Command Prompt from the Start menu. Install rstool with:

pip install rstool

You should now be able to run rstool.

To uninstall:

pip uninstall rstool

rstool calculates a number of physical quantities from a set of source physical quantities, such as different humidity quantities (water vapor partial pressure, mixing ratio, specific humidity, relative humidity, and dew point temperature), potential temperature, lifting condensation level, and eastward and northward wind. This is done when converting from a native instrument format, the instrument-dependent intermediate (im) format, the points (pts) format, or the profile (prof) format to the profile (prof) format. Conversion of quantities is performed recursively from source to derived quantities through any number of steps required. Supported elementary quantity conversions are the following (source quantities 🠢 derived quantities):

thetav, zg, p, g 🠢 p_bvf, zg_bvf, bvf
p, w 🠢 e
td 🠢 e
ps, ws 🠢 es
tds 🠢 es
ta 🠢 esat
tas 🠢 esats
station_lat 🠢 g
g 🠢 gammad
p, ta, gammad 🠢 gammam
w, wsat 🠢 hur
ws, wsats 🠢 hurs
w 🠢 hus
ws 🠢 huss
pc, p, zg 🠢 lcl
pcs, p, zg 🠢 lcls
p, theta, thetas 🠢 lts
ps, ws, tas 🠢 pc
ps, ws, ts 🠢 pcs
rhod, rhow 🠢 rho
p, e, ta 🠢 rhod
ps, es, tas 🠢 rhods
rhods, rhows 🠢 rhos
p, e, ta 🠢 rhow
ps, es, tas 🠢 rhows
e 🠢 td
es 🠢 tds
ta, w 🠢 tv
tas, ws 🠢 tvs
p, ta 🠢 theta
ps, tas 🠢 thetas
theta, w 🠢 thetav
thetas, ws 🠢 thetavs
wds, wdd 🠢 ua
wdss, wdds 🠢 uas
wds, wdd 🠢 va
wdss, wdds 🠢 vas
hus 🠢 w
hur, wsat 🠢 w
p, e 🠢 w
ua, va 🠢 wdd
uas, vas 🠢 wdds
ua, va 🠢 wds
uas, vas 🠢 wdss
huss 🠢 ws
hurs, wsats 🠢 ws
ps, es 🠢 ws
p, esat 🠢 wsat
ps, esats 🠢 wsats
zg, g 🠢 z
z, g 🠢 zg

Below is a description of the output NetCDF formats. Time is expressed as Julian date (fractional number of days since -4712-01-01 12:00 UTC, or -4713-11-24 12:00 UTC in the proleptic Gregorian calendar). This can be converted to UNIX time (number of non-leap seconds since 1 January 1970 00:00 UTC) with the forumula (time - 2440587.5)*86400.

The formats can be converted in the order from intrument-depedent intermediate (im:instrument) to points (pts) to profile (prof).

All variables are stored either as 64-bit floating point (float64) or 64-bit integer (int64). Missing values are stored as NaN in float64 and -9223372036854775806 in int64.

pts is an instrument-independent format containing a sequence of radiosonde measurements as received by the base station ordered by time, converted to a standard set of variables.

prof is an instrument-independent format containing standard variables interpolated as a function of height. Profiles are calculated by averaging points (pts) on a regular vertical pressure grid. For calculation of an ascending profile (default), only strictly increasing subsets of points are considered. For a descending profile (prof:desc), only strictly decreasing subsets of points are considered. Vertical intervals with no points are filled with missing values. It is therefore possible to identify vertical intervals where no radiosonde data were received, and optionally interpolate (linearly or in some other way) across these intervals when plotting.

surf dataset specifies near-surface variables, which can be used as an optional input to rstool. These can come from a co-located automatic weather station (AWS). Some native radiosonde data can already contain the same of these variables (iMet). Near-surface variables are needed to calculate some derived profile variables, such as the lifting condensation level. All variables must have a single dimension of time. The point nearest to the radiosonde launch time is picked. If no points are within 1 hour of the radiosonde launch, the surface input is ignored. Either (uas, vas) or (wdds, wdss) can be defined. Either hurs or (ps, tas, tds) can be defined.

im:imet is an intermediate instrument format of the InterMet radiosonde converted to NetCDF by reading input .dat and .flt files.

im:ws is an intermediate instrument format of the Windsond radiosonde converted to NetCDF by reading an input .sounding file.

rstool writes the following attributes in the intrument-dependent intermediate (im:instrument), points (pts), and profile (prof) NetCDF files.

In addition, the following attributes may be available in instrument-depedent intermediate, pts, and prof datasets depending on the instrument:

rstool provides functions implementing algorithms for calculating various physical quantities. The functions are available in the Python module rstool.algorithms.

All of the functions below use keyword-only arguments, which means that they have to be called with explicitly specified keyword arguments. They cannot be called with positional arguments. This is to prevent accidental mistakes in specifying the arguments.

calc_bvf(*, thetav, zg, p, g, res=400)

Calculate Brunt-Väisälä frequency (Hz) from air temperature ta (K), geopotential height zg (m), air pressure p (Pa) and gravitational acceleration g (m.s^-2). res is vertical resolution in geopotential height (m). Returns a tuple of p_bvf (Pa), zg_bvf (m) and bvf (Hz), where p_bvf are new air pressure coordinates, zg_bvf is geopotential height at p_bvf, and bvf is the Brunt-Väisälä frequency at p_bvf.

calc_e(*, p, w)

Calculate water vapor partial pressure in air (Pa) from humidity mixing ratio w (1) and air pressure p (Pa).

calc_esat(*, ta)

Calculate saturation water vapor partial pressure (Pa) from air temperature ta (K).

calc_g(*, lat=45)

Calculate gravitational acceleration (m.s^-2) from latitude lat (degree). Height dependence is ignored.

calc_gammad(*, g)

Calculate dry adiabatic air temperature lapse rate (K.m^-1) at gravitational acceleration g (m.s^-2).

calc_gammam(*, p, ta, gammad)

Calculate moist adiabatic air temperature lapse rate (K.m^-1) from pressure p (Pa), temperature ta (K) and dry adiabatic air temperature lapse rate gammad (K.m^-1).

calc_hur(*, w, wsat)

Calculate relative humidity (%) from humidity mixing ratio w (1) and saturation water vapor mixing ratio in air wsat (1).

calc_hus(*, w)

Calculate specific humidity (1) from humidity mixing ratio w (1).

calc_lts(*, p, theta, thetas):

Calculate lower tropospheric stability (K) from air pressure p (Pa), air potential temperature theta (K) and near-surface air potential temperature thetas (K).

calc_rho(*, rhod, rhow)

Calculate density of air (kg.m^-3) from density of dry air rhod (kg.m^-3) and density of water vapor rhow (kg.m^-3).

calc_rhod(*, p, e, ta)

Calculate density of dry air (kg.m^-3) from air pressure p, water vapor partial pressure e (Pa), and air temperature ta (K).

calc_rhow(*, p, e, ta)

Calculate density of water vapor (kg.m^-3) from air pressure p, water vapor partial pressure e (Pa), and air temperature ta (K).

calc_tpar(*, p, ps, tas)

Calculate dry-moist adiabatic parcel temperature at air pressure p (Pa), assuming surface air pressure ps and near-surface air temperature tas (K).

calc_tv(*, ta, w)

Calculate virtual temperature (K) from air temperature ta (K) and humidity mixing ratio w (1).

calc_theta(*, p, ps, ta, p0=1e5)

Calculate air potential temperature (K) from air pressure p (Pa), surface air pressure ps (Pa) and air temperature ta (K). Assume standard pressure p0.

calc_td(*, e)

Calculate dew point temperature (K) from water vapor pressure e (Pa).

calc_pc(*, ps, ws, tas)

Calculate condensation pressure (Pa) from surface air pressure ps (Pa), near-surface humidity mixing ratio ws (Pa) and near-surface air temperature tas (K).

calc_ua(*, wds, wdd)

Calculate eastward wind (m.s^-1) from wind speed wds (m.s^-1) and wind direction wdd (degree).

calc_va(*, wds, wdd)

Calculate northward wind (m.s^-1) from wind speed wds (m.s^-1) and wind direction wdd (degree).

calc_w(*,
[option 1] p, e
[option 2] hus
[option 3] hur, wsat
)

Calculate humidity mixing ratio from [option 1] pressure p (Pa) and water vapor partial pressure e (Pa), [option 2] specific humidity hus (1), or [option 3] relative humidity hur (%) and saturation humidity mixing ratio wsat (1).

calc_wdd(*, ua, va)

Calculate wind direction (degree) from eastward wind ua (m.s^-1) and northward wind va (m.s^-1).

calc_wds(*, ua, va)

Calculate wind speed (m.s^-1) from eastward wind ua (m.s^-1) and northward wind va (m.s^-1).

calc_wsat(*, p, ta)

Calculate saturation humidity mixing ratio (1) from air pressure p (Pa) and air temperature ta (K).

calc_z(*,
[option 1] zg, g
[option 2] p1, p, z
)

Calculate altitude (m) from [option 1] geopotential height zg (m) and gravitational acceleration g (m.s^-2), [option 2] by interpolation from air pressure level p1 (Pa), air pressure at all levels p (Pa) and altitude at all levels z (m).

calc_zg(*,
[option 1] z, g
[option 2] p1, p, zg
)

Calculate geopotential height (m) from [option 1] altitude z (m) and gravitational acceleration g (m.s^-2), [option 2] by interpolation from air pressure level p1 (Pa), air pressure at all levels p (Pa) and geopotential height at all levels zg (m).

This software can be used, modified, and distributed freely under the terms of the MIT license (see LICENSE.md).

• Fixed pts to prof conversion.
• Fixed ua and va calculation from wdd and wds. The sign was flipped.
• Fixed an error in the formula for moist adiabatic lapse rate calculation.
• Potential temperature is now calculated relative to standard pressure (1000 hPa) instead of surface pressure.
• imet: Fixed surface pressure reading. The units were not converted to Pa from hPa.
• Refactored variable names and headers.
• Removed parcel variables and lifting level variables.
• More complex and recursive derivation of physical quantities.
• New variables: virtual potential temperature, LCL, condensation pressure, density, lower tropospheric stability.
• Renamed raw format to intermediate format.
• Python API for calculating physical quantities.
• Refactored code.
• Improved documentation.

• Fixed a bool type error due to a removal of the type from the numpy package.
• Improvements in the processing of surface variables.
• Latitude-dependent gravitational acceleration calculation.
• Destination variables are now only set if they do not already exist in prof to prof conversion.
• More accurate calculation of relative humidity from specific humidity.
• Fixed missing calendar attribute in the time variable of prof output.
• Fixes and improvements in the documentation.

• Changed calendar to proleptic Gregorian.
• Added standard_name attributes.

• Fixed missing surf module.
• Installation of the script via setuptools entry points.

• Initial beta release.

ALCF, ccplot, cl2nc, mpl2nc, mrr2c