TSTORMS

TSTORMS is an early tracking software for tropical cyclones originally developed by NOAA GFDL and described in [Vitart2001]. It is made available under a GPL-2.0 license.

TCTrack provides bindings for both the Driver routine for detecting candidate storms, also the Trajectories functionality for stitching nodes to generate trajectories.

For full details of the TSTORMS API in TCTrack see the TCTrack TSTORMS API documentation.

Installation

Using the TSTORMS module in TCTrack requires TSTORMS to be installed on a user’s system.

The original source is available as an archive from NOAA GFDL via FTP, but users should install from the ICCS Fork on GitHub as this contains a number of fixes for hard-coded filepaths etc. over the original to aid usability.

TSTORMS comprises two codes, one for storm detection (tstorms_driver) and another for generating trajectories (trajectory_analysis). The code is built using Make and requires a Fortran compiler and an installation of NetCDF. The steps are summarised here:

git clone https://github.com/Cambridge-ICCS/TSTORMS.git
cd TSTORMS/
cd tstorms_driver/
make FC=gfortran
cd ../trajectory_analysis/
make FC=gfortran

This will clone the TSTORMS code and then then build the two TSTORMS executables using Make. ifort or ifx can also be used for the compilation. Any other compilers will require modification to both tstorms_driver/mkmf_template and trajectory_analysis/mkmf_template.

Once this is complete the TSTORMS executables can then be found at /path/to/TSTORMS_installation/tstorms_driver/tstorms_driver.exe and /path/to/TSTORMS_installation/trajectory_analysis/trajectory_analysis_csc.exe. To use these from TCTrack you will need to provide the path /path/to/TSTORMS_installation/ to TSTORMSBaseParameters as tstorms_dir so that the executables can be located at runtime.

Usage

Cyclone tracking in TSTORMS is described in [Vitart2001] and consists of two phases: detection, which performs node detection of candidate storms for each snapshot in time, and stitching, which combines suitable nodes across timesteps to generate trajectories. [*]

Usage of TSTORMS in TCTrack is through the tstorms module.

This provides the TSTORMSTracker class that stores algorithm parameters and provides access to the methods. The detection and stitching algorithms can be configured through the various parameters in the TSTORMSBaseParameters, TSTORMSDetectParameters, and TSTORMSStitchParameters dataclasses, or by using parameter_set() to get a default set of parameters.

The basic usage is illustrated below:

from tctrack.tstorms import parameter_set, TSTORMSTracker

input_files = [
    "path/to/u_input.nc",
    "path/to/v_input.nc",
    "path/to/vort_input.nc",
    "path/to/tm_input.nc",
    "path/to/slp_input.nc",
]

# Define the parameters
base_params, detect_params, stitch_params = parameter_set(
    "default",
    tstorms_dir="path/to/tstorms/installation/",
    output_dir="path/to/place/outputs/",
)

# Define and run the tracking algorithm
tracker = TSTORMSTracker(base_params, detect_params, stitch_params)
tracker.run_tracker(input_files, "trajectories.nc")

The sections below go into further detail about the stages of the tracking algorithm and manually defining the parameters.

Detection

In the following example we demonstrate the approach for detecting tropical cyclones using TSTORMS. First, we set up the detect() functionality to detect candidate storms based on locating points that satisfy certain minima or maxima, with full details of each input given in the TSTORMSDetectParameters documentation:

from tctrack.tstorms import (
    TSTORMSBaseParameters,
    TSTORMSDetectParameters,
    TSTORMSTracker,
)

input_files = [
    "path/to/u_input.nc",
    "path/to/v_input.nc",
    "path/to/vort_input.nc",
    "path/to/tm_input.nc",
    "path/to/slp_input.nc",
]

tstorms_params = TSTORMSBaseParameters(
    tstorms_dir="path/to/tstorms/installation/",
    output_dir="path/to/place/outputs/",
)
detect_params = TSTORMSDetectParameters(
    vort_crit=3.5e-5,
    tm_crit=0.5,
    thick_crit=50.0,
    dist_crit=4.0,
    lat_bound_n=70.0,
    lat_bound_s=-70.0,
    do_spline=False,
    do_thickness=False,
    use_sfc_wind=True,
)

# Initialize the tracker
tracker = TSTORMSTracker(tstorms_params, detect_params)
tracker.set_input_files(input_files)

detect_call = tracker.detect(verbosity=2)

The result of this will be a cyclones file in the prescribed output directory with candidate storms organised by date in the format described in detect().

Stitching

These candidates may be stitched into plausible trajectories using the stitch() functionality. Stitching is based on locating subsequent candidate points within a maximum distance of the previous point. Valid trajectories must last for a set time period and can be filtered within latitude bounds and to satisfy variable thresholds. Full details of each input are given in the TSTORMSStitchParameters documentation.

from tctrack.tstorms import TSTORMSStitchParameters

stitch_params = TSTORMSStitchParameters(
    r_crit=800.0,
    wind_crit=12.0,
    vort_crit=3.5e-5,
    tm_crit=0.5,
    n_day_crit=2,
    do_filter=True,
    lat_bound_n=70.0,
    lat_bound_s=-70.0,
)
tracker = TSTORMSTracker(tstorms_params, detect_params, stitch_params)
stitching_call = tracker.stitch(verbosity=2)

The result of this will be the following set of files at the output location provided in TSTORMSStitchParameters:

  • ori containing the origins of each storm in the form lon, lat, YY, MM, DD, HH,

  • traj containing trajectory point data in the form lon, lat, wind, psl, YY, MM, DD, HH for each trajectory,

  • trav containing trajectory point data and vorticity in the form lon, lat, wind, psl, vort_max, YY, MM, DD, HH for each trajectory,

  • stats containing information about the number of storms per month/year in each basin.

If filtering is applied (TSTORMSStitchParameters do_filter) there will also be additional files ori_filt, traj_filt, and trav_filt from after this takes place.

Output

Finally, after running stitch to generate storm trajectories, the tracks can be written to a NetCDF file fully compliant with the CF-Conventions (specifically the trajectory data format) using to_netcdf():

tracker.to_netcdf("my_tstorms_cf_trajectories.nc")

This can be read using any NetCDF reading utility, though cf-python will load it following the CF data model.

Input data

TSTORMS requires data for Eastward and Northward velocities, vorticity, air temperature, and sea-level pressure at certain pressure levels or ranges. The input data must be stored in NetCDF files with dimensions (time, lat, lon) and all variables must be on the same grid. Time should be unlimited dimension and should only have positive values (e.g. if using data from 1950 the time units should be days since 1950-01-01 or earlier). The latitude coordinates should be increasing (from south to north). There can be only one variable per file and they should conform to the pre-defined variable names described below.

  • Eastward Velocity:

    • Eastward velocity in m s-1.

    • Can be at surface, in which case set use_sfc_wind to True, or at a pressure level of 850 hPa, in which case set use_sfc_wind to False.

    • Named u_ref or u850 in the NetCDF file depending on the value of use_sfc_wind.

  • Northward Velocity:

    • Northward velocity in m s-1.

    • Can be at surface, in which case set use_sfc_wind to True, or at a pressure level of 850 hPa, in which case set use_sfc_wind to False.

    • Named v_ref or v850 in the NetCDF file depending on the value of use_sfc_wind.

  • Vorticity:

    • Vorticity in s-1.

    • Should be at a pressure level of 850 hPa.

    • Named vort850 in the NetCDF file.

  • Mean Temperature:

    • Mean air temperature in the warm core layer in degrees K.

    • Should be the mean air temperature over 500-200 hPa.

    • Named tm in the NetCDF file.

  • Sea-level Pressure:

    • Sea-level pressure in Pa .

    • Named slp in the NetCDF file.

Functions to preprocess the data into these forms are described in Preprocessing Data.