TSTORMS

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

For an overview of the functionalities, installation, and usage see the TSTORMS section of the documentation.

class tctrack.tstorms.TSTORMSTracker(tstorms_parameters, detect_parameters, stitch_parameters=None)[source]

Bases: TCTracker

Class containing bindings to the TSTORMS code.

driver_parameters

Class containing the parameters for the driver detection algorithm

Type:: TSTORMSDetectParameters | None

trajectory_parameters

Class containing the parameters for the trajectory stitching algorithm

Type:: TSTORMSStitchParameters | None

property global_metadata: dict

Read-only property containing metadata for tctrack / tracker instance.

Raises:: AttributeError – If _global_metadata has not been initialized.
Type:: dict

run_tracker_subprocess(command_name, command_list, input_file=None, input_str=None, cwd=None, verbosity=1)

Run a subprocess command for a cyclone tracking algorithm.

Parameters:

command_name (str) – The name of the command, used in logging and error messages.
command_list (list[str]) – The command and its arguments to execute.
input_file (str | None) – Path to a file to pass to the process via stdin (e.g. a namelist). Cannot be used together with input_str. Defaults to None.
input_str (str | None) – A string to pass to the process via stdin (e.g. interactive inputs). Cannot be used together with input_file. Defaults to None.
cwd (str | None) – Working directory in which to execute the command. Defaults to None.
verbosity (int) – Controls how much output is shown: 0 = No output gets printed. 1 = summary, first and last 12 lines printed (default). 2 = Entire output is streamed in real-time. Defaults to 1.

Returns:

Dictionary of subprocess output to ‘stdout’, ‘stderr’, and ‘returncode’.

Return type:

dict

Raises:

ValueError – If both input_file and input_str are provided simultaneously.
ValueError – If verbosity is not 0, 1, or 2.

set_metadata()

Initialise the metadata attributes used in the CF-netcdf output.

This is called from the to_netcdf() method.

This sets the _global_metadata attribute with the TCTrack parameters and name of the tracker. It then calls the subclass-specific _set_metadata() to set _variable_metadata and _time_metadata.

Return type:: None

property time_metadata: TCTrackerTimeMetadata

Read-only property containing time metadata for this Tracker run.

Raises:: AttributeError – If _time_metadata has not been initialized.
Type:: dict

to_netcdf(output_file)

Write track trajectories to CF-compliant NetCDF trajectory file.

Reads in trajectories based on the parameters set for a specific implementation of the class and writes them to a CF-Conventions compliant NetCDF trajectory file using cf-python. Trajectories are assumed to contain as a minimum data for lat, lon, and timestep.

An ancillary field variable is added to the output file indicating any tracks that start/end within 1 day of the input dataset boundaries.

Parameters:: output_file (str) – filename for the output netCDF file Note: This will be placed in the local directory unless a full path is given
Return type:: None

Warning

UserWarning: If there are no trajectories read in from the tracker outputs by read_trajectories() meaning no NetCDF output file can be written.

References

CF-Conventions v1.1 - H.4. Trajectory Data cf-python documentation

Examples

Instantiate a TCTracker subclass instance with appropriate parameters, run the relevant methods to generate cyclone track trajectories, and then save the results to a CF-compliant trajectory file:

>>> my_tracker = TCTracker(...)
>>> ...
>>> my_tracker.to_netcdf("my_netcdf_file.nc")

property variable_metadata: dict

Read-only property containing NetCDF metadata for variables.

Raises:: AttributeError – If _variable_metadata has not been initialized.
Type:: dict

detect(verbosity=1)[source]

Call the driver utility of TSTORMS.

This will make a system call out to the tstorms_driver code from TSTORMS (provided it has been installed as an external dependency). This will be run according to the parameters in the detect_parameters attribute that were set when the TSTORMSTracker instance was created.

The output file is a plain text file named cyclones containing each of the TC candidates at each time from the input files. This will be generated in the desired output location provided in the base parameters attribute tstorms_parameters. Cyclones in the file are listed for each time in the format:

     <day>       <month>       <year>       <number>       <hour>
 <i_index>     <j_index>    <lon_slpmin>      <lat_slpmin>
<max_wind>    <max_vort>    <min_slp>    <exist_warm_core> <exist_thickness>
<max_warm_core>    <max_thickness>
       ...

number is the number of nodes at that time.
i_index, j_index are the grid indices of the node.
lon_slpmin, lat_slpmin are the coordinates of the slp minimum.
Other values are the variable values for the cyclone output from the code.

Parameters:

verbosity (int) – Controls how much output is shown: 0 = No output gets printed. 1 = summary, first and last 12 lines printed (default). 2 = Entire output is streamed in real-time. Defaults to 1.

Returns:

dict of subprocess output corresponding to stdout, stderr, and returncode.

Return type:

dict

Raises:

FileNotFoundError – If the tstorms_driver executeable from TSTORMS cannot be found.
RuntimeError – If the tstorms_driver executeable from TSTORMS returns a non-zero exit code.

Examples

To set the parameters, instantiate a TSTORMSTracker instance and run detect:

>>> base_params = TSTORMSBaseParameters(...)
>>> detect_params = TSTORMSDetectParameters(...)
>>> my_tracker = TSTORMSTracker(
        tstorms_parameters=base_params,
        detect_parameters=detect_params
    )
>>> result = my_tracker.detect()

stitch(verbosity=1)[source]

Call the trajectory analysis utility of TSTORMS to stitch candidate storms.

This will make a system call out to the trajectory_analysis code from TSTORMS (provided it has been installed as an external dependency). This will be run according to the parameters in the stitch_parameters attribute that were set when the TSTORMSTracker instance was created. It assumes that the candidate storms are contained in the output_dir directory in a file cyclones text file.

The outputs are plain text files named:

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 (stitch_parameters do_filter) there will be additional files ori_filt, traj_filt, and trav_filt from after this takes place. These files will be generated in the desired output location provided in the base parameters attribute tstorms_parameters.

Parameters:

verbosity (int) – Controls how much output is shown: 0 = No output gets printed. 1 = summary, first and last 12 lines printed (default). 2 = Entire output is streamed in real-time. Defaults to 1.

Returns:

dict of subprocess output corresponding to stdout, stderr, and returncode.

Return type:

dict

Raises:

FileNotFoundError – If the trajectory_analysis executeable from TSTORMS cannot be found.
RuntimeError – If the trajectory_analysis executeable from TSTORMS returns a non-zero exit code.

Examples

To set the parameters, instantiate a TSTORMSTracker instance and run stitch:

>>> base_params = TSTORMSBaseParameters(...)
>>> stitch_params = TSTORMSStitchParameters(...)
>>> stitch_params = TSTORMSTracker(
        tstorms_parameters=base_params,
        stitch_parameters=stitch_params
    )
>>> result = my_tracker.stitch()

read_trajectories()[source]

Parse outputs from TSTORMS to list of tctrack.core.Trajectory.

This will read from the trav file output from trajectory stitching, or trav_filt if filtering was applied (see do_filter in the tstorms_parameters attribute).

Returns:: trajectories – A list of tctrack.core.Trajectory objects.
Return type:: list[Trajectory]

run_tracker(output_file)[source]

Run TSTORMS tracker to obtain tropical cyclone track trajectories.

This first runs detect() to get TC candidates at each time. Then these are combined into trajectories using stitch(). The output is then saved as a CF-compliant NetCDF trajectory file.

Parameters:

output_file (str) – Filename to which the tropical cyclone trajectories are saved.

Raises:

FileNotFoundError –
- If the TSTORMS executables cannot be found.
RuntimeError – If the TSTORMS commands return a non-zero exit code.

Examples

To set the parameters, instantiate a TSTORMSTracker instance and run run_tracker():

>>> tstorms_params = TSTORMSBaseParameters(...)
>>> detect_params = TSTORMSDetectParameters(...)
>>> stitch_params = TSTORMSStitchParameters(...)
>>> my_tracker = TSTORMSTracker(tstorms_params, detect_params, stitch_params)
>>> my_tracker.run_tracker()

class tctrack.tstorms.TSTORMSBaseParameters(tstorms_dir, output_dir, input_dir='')[source]

Bases: TCTrackerParameters

Dataclass containing values used in configuring the TSTORMS install.

This class is intended to configure the install so that executables can be run correctly and data stored in a desired location. Configuration of the actual cyclone detection algorithm is done using TSTORMSDetectParameters and TSTORMSStitchParameters.

tstorms_dir: str: Full path to the TSTORMS installation directory. This will be likely be a directory named tropical_storms_pub/ and should contain tstorms_driver/ and trajectory_analysis/ subdirectories.

output_dir: str: Full path to the directory where TSTORMS outputs should be deposited.

input_dir: str = '': Full path to the directory where TSTORMS input files can be found. Defaults to empty string which will load from current directory.

class tctrack.tstorms.TSTORMSDetectParameters(u_in_file, v_in_file, vort_in_file, tm_in_file, slp_in_file, use_sfc_wind=True, vort_crit=3.5e-05, tm_crit=0.5, thick_crit=50.0, dist_crit=4.0, lat_bound_n=90.0, lat_bound_s=-90.0, do_spline=False, do_thickness=False)[source]

Bases: TCTrackerParameters

Dataclass of values used by the Driver operation of TSTORMS for candidate detection.

Default values are set to match those in the TSTORMS tstorms_driver source-code.

Raises:

ValueError –
- If northern latitude bound is less than the southern latitude bound. - If any of the input file filenames are left as None.
UserWarning –
- If do_thickness is set to True as this has no effect.

u_in_file: str: Filename of the u (zonal) velocity input file. This should be a NetCDF file containing a single lat-lon slice of the u field named u_ref (if use_sfc_wind is True) or u850. This should be the full path unless the location of input files was specified in TSTORMSBaseParameters’ input_dir.

v_in_file: str: Filename of the v (meridional) velocity input file. This should be a NetCDF file containing a single lat-lon slice of the v field named v_ref (if use_sfc_wind is True) or v850. This should be the full path unless the location of input files was specified in TSTORMSBaseParameters’ input_dir.

vort_in_file: str: Filename of the vorticity input file. This should be a NetCDF file containing a single lat-lon slice of the vorticity field named vort850 at the 850 hPa level. This should be the full path unless the location of input files was specified in TSTORMSBaseParameters’ input_dir.

tm_in_file: str: Filename of the temperature input file. This should be a NetCDF file containing a single lat-lon slice of the mean temperature of the warm-core layer named tm. This should be the full path unless the location of input files was specified in TSTORMSBaseParameters’ input_dir.

slp_in_file: str: Filename of the sea-level pressure input file. This should be a NetCDF file containing a single lat-lon slice of sea-level pressure named slp. This should be the full path unless the location of input files was specified in TSTORMSBaseParameters’ input_dir.

use_sfc_wind: bool = True: Whether to use surface winds (True), or winds at 850 hPa level.

vort_crit: float = 3.5e-05: Critical vorticity threshold [s-1] to be exceeded to qualify as a candidate storm.

tm_crit: float = 0.5: Critical warm core local maximum to be exceeded to qualify as a candidate storm.

thick_crit: float = 50.0: Critical thickness threshold to be exceeded to qualify as a candidate storm. Note that thickness calculations are not yet implemented in TSTORMS.

dist_crit: float = 4.0: Critical radius [degrees] within which vorticity, sea-level pressure, and other maxima/minima must lie within each other to qualify as a candidate storm.

lat_bound_n: float = 90.0: Northern latitude bound [degrees] below which storm detection should occur.

lat_bound_s: float = -90.0: Southern latitude bound [degrees] above which storm detection should occur.

do_spline: bool = False: Whether to use splines for detecting minma instead of gridpointwise search.

do_thickness: bool = False: Whether to use thickness of the 200-1000 hPa layer as a variable for detecting candidate storms. Note that this functionality is not yet implemented in TSTORMS.

class tctrack.tstorms.TSTORMSStitchParameters(r_crit=900.0, wind_crit=17.0, vort_crit=3.5e-05, tm_crit=0.5, thick_crit=50.0, n_day_crit=2, do_filter=True, lat_bound_n=40.0, lat_bound_s=-40.0, do_spline=False, do_thickness=False)[source]

Bases: TCTrackerParameters

Dataclass containing values used by the stitching trajectory operation of TSTORMS.

Default values are set to match those in the TSTORMS trajectory_analysis source-code.

Raises:

ValueError – If northern latitude bound is less than the southern latitude bound.
UserWarning – If do_thickness is set to True as this has no effect.

r_crit: float = 900.0: Maximum daily track length [km] between succcessive points in a trajectory.

wind_crit: float = 17.0: Critical wind speed [m/s] for trajectory calculations.

vort_crit: float = 3.5e-05: Critical vorticity threshold [s-1] for trajectory calculations.

tm_crit: float = 0.5: Critical warm core threshold for trajectory calculations.

thick_crit: float = 50.0: Critical thickness threshold for trajectory calculations.

n_day_crit: int = 2: Minimum number of days a trajectory must last to be valid.

do_filter: bool = True: Whether to apply filtering of trajectories. Filtering is based on landmask and lat-lon bounds to generate *_filt output files.

lat_bound_n: float = 40.0: Northern latitude bound [degrees] for trajectory filtering.

lat_bound_s: float = -40.0: Southern latitude bound [degrees] for trajectory filtering.

do_spline: bool = False: Whether to use splines for trajectory calculations. Should match the value used in the Driver routine. If splines used then twc_crit and thick_crit will not be used in comparisons.

do_thickness: bool = False: Whether to use thickness of the 200-1000 hPa layer as a variable for detecting candidate storms. Note that this functionality is not yet implemented in TSTORMS.