TRACK

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].

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

class tctrack.track.TRACKTracker(parameters)[source]

Bases: TCTracker

Class containing bindings to the TRACK code.

parameters

Class containing the parameters for the TRACK algorithm(s)

Type:: TRACKParameters

References

TRACK code on the University of Reading GitLab

property global_metadata: dict

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

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

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

calculate_vorticity()[source]

Use TRACK to calculate the vorticity from the wind components.

This method requires the wind speed components to be on a Gaussian grid in a netcdf file, given by input_file. This is copied to the TRACK ‘indat’ folder and used as an input for a system call to TRACK to calculate the vorticity.

The vorticity is written to a new file in the ‘indat’ folder given by vorticity_file. This uses the following layout:

<n_lon> <n_lat> <n_frames>
<List of longitudes spaced 10 to a line>
<List of latitudes spaced 10 to a line>
FRAME 1
<Binary block of floats for the vorticities in frame 1>
FRAME 2
<Binary block of floats for the vorticities in frame 2>
...

Raises:

FileNotFoundError – If the TRACK executable cannot be found on the system.
RuntimeError – If the TRACK executable returns a non-zero exit code.

spectral_filtering()[source]

Use TRACK to perform the spectral filtering of the vorticity.

This makes a system call to TRACK to spectrally filter the vorticity (in the file vorticity_file) to keep only wavenumbers 6-63.

The output file is copied to filt_vorticity_file in the TRACK ‘indat’ folder, so that it can be used in tracking(). This file has the same format as described in calculate_vorticity().

Raises:

FileNotFoundError – If the TRACK executable cannot be found on the system.
RuntimeError – If the TRACK executable returns a non-zero exit code.

tracking()[source]

Call the tracking utility of TRACK.

This will make a system call out to TRACK to perform the detection of tropical cyclone candidates using the spectrally filtered vorticity (stored in the file filt_vorticity_file). These candidates are then combined into trajectories by minimising a cost function.

The trajectories are output in the objout.new.<ext> and tdump.<ext> text files in the TRACK ‘outdat’ folder.

Raises:

FileNotFoundError – If the TRACK executable cannot be found on the system.
RuntimeError – If the TRACK executable returns a non-zero exit code.

filter_trajectories()[source]

Use TRACK to filter the identified trajectories.

This step takes the identified trajectories from the tracking() step stored in the objout.new.<ext> and tdump.<ext> files. It then filters out trajectories with fewer than 8 points (i.e. based on the duration) or a total distance less than filter_distance (if set).

This step could also be used to combine multiple outputs if the previous tracking step was batched. However, this is not currently used.

The output of this step is a ff_trs.<ext>.nc file in the TRACK ‘outdat’ folder containing the data along the filtered trajectories. To convert this into a CF-compliant trajectory format the to_netcdf() function should be used.

Raises:

FileNotFoundError – If the TRACK executable cannot be found on the system.
RuntimeError – If the TRACK executable returns a non-zero exit code.

read_trajectories()[source]

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

This reads the output file from the filter_trajectories step, i.e. ff_trs.<ext>.nc in the TRACK ‘outdat’ folder. It also takes the times from the data in TRACKParameters.input_file.

Returns:: A list of tctrack.core.Trajectory objects.
Return type:: list[Trajectory]
Raises:: FileNotFoundError – If the TRACK output file does not exist.

set_metadata()[source]

Set the global, time, and variable metadata attributes.

Raises:: ValueError – If a variable with time coordinate is not found in the input file.
Return type:: None

run_tracker(output_file)[source]

Run the TRACK tracker to obtain the tropical cyclone track trajectories.

This runs the relevant methods in order:

calculate_vorticity()
spectral_filtering()
tracking()
filter_trajectories()

Finally the output is then saved as a CF-compliant trajectory netCDF file by calling to_netcdf().

This method will overwrite the files in the ‘outdat’ folder in the TRACK source location. Therefore, any outputs from running TRACK manually should be moved to prevent loss of data.

Parameters:

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

Raises:

FileNotFoundError – If the TRACK executable cannot be found.
RuntimeError – If the TRACK executable returns a non-zero exit code.

Examples

To set the parameters, instantiate a TRACKTracker instance and run the algorithms to generate trajectories:

>>> track_params = TRACKParameters(...)
>>> my_tracker = TRACKTracker(track_params)
>>> my_tracker.run_tracker("trajectories.nc")

class tctrack.track.TRACKParameters(base_dir, input_file, filter_distance=None, wind_var_names=('ua', 'va'), pressure_level=85000, binary='bin/track.run', file_extension='track_out', vorticity_file='vor.dat', filt_vorticity_file='vor_T63.dat', export_inputs=False, read_inputs=False, inputs_directory=None)[source]

Bases: TCTrackerParameters

Dataclass containing values for parameters used by TRACK.

base_dir: str: The filepath to the directory where TRACK is installed.

input_file: str: NetCDF input file containing the north and easterly wind speeds on a Gaussian grid in m/s.

filter_distance: float | None = None: The minimum start-to-end distance which trajectories must travel, in degrees.

wind_var_names: tuple[str, str] = ('ua', 'va'): The variable names for the Eastward and Northward Wind in the input file.

pressure_level: int = 85000: The pressure level at which to calculate the vorticity. In Pa.

binary: str = 'bin/track.run': The filepath of the main TRACK compiled binary relative to base_dir.

file_extension: str = 'track_out': The file extension to use for intermediate TRACK output files. This cannot be the same as part of the /path/to/TRACK/outdat.

vorticity_file: str = 'vor.dat': The filename for the vorticity intermediate output file.

filt_vorticity_file: str = 'vor_T63.dat': The filename for the spectral filtered vorticity intermediate output file.

export_inputs: bool = False: Flag to export the TRACK command line inputs to files.

read_inputs: bool = False: Flag to read the command line inputs from files instead of TRACKParameters. There should be a file for each step, named as calculate_vorticity.in, spectral_filtering.in, tracking.in, and filter_trajectories.in. If a file dose not exist it will generate inputs from TRACKParameters as normal.

inputs_directory: str | None = None: Directory containing files for exporting / reading command line inputs. This will be created if it does not exist. By default, the current directory is used.