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

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

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.

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.