TRACK

Attention

The output tracks from TRACK are not currently correct. This is due to TCTrack using incorrect input parameters. See this issue for details or if you are able to contribute to help fix the issue.

TRACK is a software package and algorithm for tracking and analysing tropical cyclones and other weather systems in meteorological and oceanic datasets. It is developed by Kevin Hodges at the University of Reading, UK, and released under an AGPLv3 license.

The TRACK code can be found on the University of Reading GitLab and the algorithm is described in [Hodges2017].

TCTrack provides bindings to perform tropical cyclone tracking using the basic TRACK algorithm. Other components may be added in future as required by users.

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

Installation

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

TRACK requires NetCDF (it can be installed through system package managers, or see the detailed installation instructions) as well as a C compiler, a FORTRAN 77 compiler, Make, and makedepend. It can then be installed with the following commands:

# Download the TRACK code
git clone https://gitlab.act.reading.ac.uk/track/track
cd track
git checkout 6ded301a5f5183d73e5b49c16019024b9a53eff7

# Set necessary environment variables
export PATH=${PATH}:.
export CC=gcc
export FC=gfortran
export NETCDF=$(nc-config --prefix)
export ARFLAGS=

# Update the source file dependencies
make -C src -f Makefile.linux depend

# Compile the code
./master -build -fext=run -inpf=inputs.nc -upath=$(cd .. && pwd)

This will clone TRACK and checkout the most recent commit that TCTrack has been tested against, however there may be newer versions available. The code is then compiled using make, creating the executable at track/bin/track.run.

For further details about installation see the instructions here.

Algorithm

Tropical cyclone tracking in TRACK uses relative vorticity at 850 hPa. This is preprocessed using spectral filtering to retain only wavenumbers 6 - 63. Tropical cyclone candidates are then identified at each time step where there is a local maximum in the relative vorticity exceeding a specific threshold. These candidates are then stitched into trajectories by minimising a cost function. Finally, the trajectories are filtered to remove any that do not travel a sufficient distance or last for a sufficient duration.

Tracking can also be performed using different fields, including mean sea level pressure, but this is not currently implemented in TCTrack. In addition, the TRACK algorithm describes performing checks for a warm core based upon the difference in vorticity between 850 and 200 hPa. However, this is also not currently implemented.

Further details can be found in [Hodges2017].

Usage

Usage of TRACK is performed using the tctrack.track module. This contains the TRACKTracker class which is used to run the algorithm, and the TRACKParameters dataclass for specifying the various parameters.

The example below illustrates how to use these to run TRACK using the default parameters. The output trajectories are written to the "trajectories.nc" file in a CF-compliant NetCDF format. Note that the location of the TRACK source directory must be provided using the base_dir parameter and the NetCDF variable names for the windspeed should be specified with wind_var_names.

from tctrack.track import TRACKParameters, TRACKTracker

params = TRACKParameters(
    base_dir="/path/to/track",
    input_file="ua_va_file_F256.nc",
    wind_var_names=("ua", "va"),
)

tracker = TRACKTracker(params)
tracker.run_tracker("trajectories.nc")

In addition to base_dir and wind_var_names there are a number of other parameters that can be used in TRACKParameters. Most notable is filter_distance which sets the minimum distance (in degrees) of trajectories.

The run_tracker() method performs several steps in sucession. These are:

calculate_vorticity(), to calculate the relative vorticity from the windspeed.
spectral_filtering(), to perform the spectral filtering on the vorticity.
tracking(), to perform the tracking to identify trajectories.
filter_trajectories(), to filter trajectories based on distance and duration.
to_netcdf(), to convert the output to a CF-compliant NetCDF file.

It is possible to call some or all of these to manually perform the tracking or repeat individual steps without rerunning the whole process. For each step, intermediate input and output files are stored in the ‘indat’ and ‘outdat’ folders in the TRACK source directory - the same location as when calling TRACK manually. Therefore, any generated files that you wish to keep should be moved to prevent them from being overwritten.

Input Data

The input data to TRACK must be contained in a single NetCDF file. This must contain the northward and eastward windspeeds at a level of 850 hPa (or as otherwise set in pressure_level) and in units of m s-1. This should be on a single Gaussian grid. Some preprocessing of the input data is likely to be required in order to concatenate along time, combine the variables onto a single grid and into one file, and to regrid onto a Gaussian grid. See Preprocessing Data for examples.

Modifying Parameters

Each step of the algorithm makes a call out to the TRACK software with a list of inputs that are built up using TRACKParameters. If you wish to experiment with different inputs that are not currently implemented in TCTrack then you can export these input lists, modify the resulting files, and then run TRACK using these files as input.

To export the inputs you can set the export_inputs parameter to True. The result will be a .in file for each step of the algorithm with one input per line. It is a bit opaque what each input corresponds to, so refer to the comments in the _get_<step>_inputs methods in TRACKTracker, or look at the output of the TRACK calls.

To read in the files, simply set the read_inputs parameter to True. Be aware that the files will then supercede any values set in TRACKParameters. If any of the inputs files do not exist it will fall back to the generated inputs for that step. So it is possible to only read inputs for a single step by deleting the exported files for the other steps. The location of the input files can also be changed by setting the value of inputs_directory.

If you identify any useful inputs it would be appreciated if you can contribute by adding these to TRACKParameters and the relevant input generation method(s).