Feature tracking

pyTRACK.track_uv(infile, outdirectory=None, hemisphere: Literal['NH', 'SH'] = 'NH', ysplit: bool = False, sdate=None, trunc: Literal['42', '63'] = '42', keep_all_files: bool = False)

Workflow to track features on 850hPa u-v wind data. Tracks both cyclones and anticyclones. The input file should contain 6-hourly data, and should have dimensions {time, lat, lon} (no height dimension!)

First computes vorticity from the input data and then truncates and spectrally filters out small wavenumbers.

Tracks features on this data. Outputs to outdirectory in folders of {hemisphere}_y{year}.

If sdate is passed, then rewrites the .nc files with date_time matching the passed sdate.

Parameters:

  • infile (str) – Name of the input file.

  • outdirectory (str) – Path to the output directory, will be created if it does not already exist.

  • ysplit (bool) – Should tracking be done for each year separately. Turn this on if you’re tracking by season!

  • sdate (str) – First time step in MMDDHH format. Start year is captured from the file directly, taking ysplit into consideration.

  • trunc (str) – Spectral truncation required - defaults to T42. Note - setting T63 will take longer and track more cyclones!

  • keep_all_files (bool) – Do you want to keep all the intermediate files? Default is no. Turn this on if you want to retreive these files, or during development.

The track_uv function currently requires a particular infile file format. Below is a code snippet on python that demonstrates how you can meet most of these.

dat=xr.open_dataset(f)
dat=dat.transpose("time", "plev", "lat", "lon") # Ensures that the order is correct, skip plev if only lat-lon
dat.lon.attrs["units"]="degrees_east"; dat.lat.attrs["units"]="degrees_north" # needs these units
dat=dat[['U', 'V']].rename_vars({'U':'ua', 'V':'va'})#.drop_vars(['plev']) # should be names ua and va
dat=dat.sel(plev=85000) # skip if only lat-lon
dat.to_netcdf('', unlimited_dims={'time'})

Note

The sdate argument should be passed with care if you decide to split years. If ysplit is true, then sdate relies on first date_time being the same every year. Hence, it’s a useful feature if you want to track JJA cyclones across years - input data for JJA and pass ysplit=True and sdate=’060100’. To track DJF (Or any other time period that is cross-year), input data shifted such that seasons are in the same year and pass ysplit=True and sdate=’110100’. This also assumes a Gregorian calendar, so be mindful of the differences if the data is on a different calendar like noleap for instance.

The track_uv() function creates folders named {hemisphere}_y{year} in the outdirectory. Inside each of these folder, many files are written. For vorticity, both positive and negative anomalies are tracked. Cyclones are associated with positive anomalies in the Northern Hemisphere and negative anomalies in the Southern Hemisphere. The *pos files are associated with positive vorticity and the *neg files are associated with negative vorticities. The tr* files contain all tracks and the ff* files contain only filtered tracks that last longer than 48 hours and travel at least 1000 km. The *.nc files are netCDF files with or without Gregorian date_time (depending on if sdate was passed) and the other files are ASCII files with the same data.

The track_uv() function outputs

pyTRACK.track_splice(datin, ext, ntime, trunc, keep_all_files=False)

Code to run feature tracking in parts and combine at the end. This is because tracking in one go can be really expensive for long time series.

This code is automatically called from track_uv()

Parameters:

  • datin (str) – The final processed vorticity file

  • ext (str) – Extension to append to the TRACK output files.

  • ntime – Number of frames in datin

  • trunc (str) – Spectral truncation required - defaults to T42. Note - setting T63 will take longer and track more cyclones!

  • keep_all_files (bool) – Do you want to keep all the intermediate files? Default is no. Turn this on if you want to retreive these files, or during development.