Tropical Cyclones detection, tracking and zoom in diagnostic

Description

This diagnostic package provides a tool to detect tropical cyclones (TCs) and compute their trajectories. Moreover it allows one to save selected variables in the vicinity of the TCs centres. The purpose of this diagnostic is to analyse how some variables of interest such as pressure, wind, wind gusts and precipitation associated with tropical cyclones are represented in high-resolution climate simulations, in particular their intensity and spatial pattern. Detection and tracking of TCs can be also used to compute TCs trajectories and compare them with other climate simulations and observations.

Structure

The tropical cyclones diagnostic follows a class structure and consists of the files:

  • notebooks/tropical_cyclones.ipynb: a python notebook which provides an example use of the TCs diagnostic, including the TCs class initialisation, a wrapper function which calls the DetectNodes and StitchNodes functions from tempest-extremes (which now are implemented as methods of the TCs class) and saves the data in the vicinity of the detected TCs at each time step and for the TCs tracks in a considered time interval. Finally some plotting functions are included to plot some selected variables at a few time steps and the TCs tracks in a particular period;

  • tropical_cyclones/tropical_cyclones.py: a python file in which the TCs class constructor and the other class methods are included; it contains the wrapper function which retrieves data from the reader and prepares them for DetectNodes and StitchNodes, it runs DetectNodes and StitchNodes and finally saves the variables in the vicinity of TCs tracks in a netcdf file;

  • tropical_cyclones/detect_nodes.py: class with all methods related to DetectNodes;

  • tropical_cyclones/stitch_nodes.py: class with all methods related to StitchNodes;

  • tropical_cyclones/tools/tempest_utils.py: a python file which contains some functions (external to the tropical cyclones class) to analyse the output text files produced by running the tempest-extremes methods DetectNodes and StitchNodes;

  • tropical_cyclones/tools/tcs_utils.py: contains some functions external to the TCs class but called by the TCs class methods;

  • tropical_cyclones/plots/plotting_TCs.py: a python file which contains the plotting functions;

  • tropical_cyclones/aqua_dask.py: python file which contains a class to initialise Dask and its methods to set and close Dask when it is needed;

  • cli/tropical_cyclones_cli.py: a python file with the command line interface for tropical cyclones diagnostic; can be executed as python script or as slurm job;

  • cli/run_TCs_LEVANTE.job: script to run tropical_cyclones_cli.py as slurm job on LEVANTE. See dedicated README file in the cli folder;

  • cli/run_TCs_LUMI.job: script to run tropical_cyclones_cli.py as slurm job on LUMI;

  • cli/config_tcs.yml: a yaml file in which all parameters are configured (including variables to save) and paths are specified. Version for Levante;

  • pyproject.toml : file to build pyproject of the tropical cyclones diagnostic;

  • README.md : a readme file which contains some tecnical information on how to install the tropical cyclones diagnostic and its environment.

Input variables

  • msl (Mean sea level pressure, GRIB paramid 151)

  • z (Geopotential height, GRIB paramid 129 at 300 and 500 hPa and at the surface (orography))

  • 10u (2m zonal wind, GRIB paramid 165)

  • 10v (2m meridional wind, GRIB paramid 166)

Output

Here is a list of files produced by the tropical cyclones diagnostic. The following files are saved in a “$tmpdir/model_name/exp_name” directory (configured in the configuration yml):

  • tempest_output_yyyymmddThh.txt: text files produced by Tempest DetectNodes with TCs centres coordinates and maximum wind at each time step;

  • tempest_track_yyyymmddThh-yyyymmddThh.txt: text files produced by Tempest StitchNodes with TCs centres coordinates and maximum wind; for each TC trajectory (i.e. after tracking is applied);

The following files are saved in “$fullres/model_name/exp_name” directory:

  • TC_fullres_yyyymmddThh.nc: netcdf files with selected variables (at original model resolution) in the vicinity of each TC centre detected at each time step;

  • tempest_tracks_yyyymmddThh-yyyymmddThh.nc: netcdf files with selected variables (at original model resolution) in the vicinity of each TC centre following TCs trajectories (includes time dimension, yyyymmddThh-yyyymmddThh states the start-end period considered).

Example of outpud variables saved in the vicinity of TCs centres are:

  • msl (Mean sea level pressure, GRIB paramid 151)

  • 10u (10m zonal wind, GRIB paramid 165)

  • 10v (10m meridional wind, GRIB paramid 166)

  • pr (Total precipitation, GRIB paramid 228)

  • 10fg (10m wind gust since the last postprocessing, GRIB paramid 49)

Figures include output variables in the vicinity of TCs centres at various time steps (useful to compare wind intensity, precipitation distribution and intensity between original resolution and a coarser resolution or with observations) and a figure with all the TCs tracks in the period considered.

Methods used

Examples from the TCs class contained in the tropical_cyclones.py and its related detect_nodes.py and stitch_nodes.py files:

  • “TCs”: the tropical cyclones class;

  • “catalog_init”: initializes the Reader object for retrieving the atmospheric data needed (i.e. the input and output vars);

  • “data_retrieve”: retrieves atmospheric data from the Reader and stores them in data arrays. It includes the posibility of simulating the streaming of data. It updates the stream_startdate and stream_enddate attributes if streaming is set to True;

  • “loop_streaming”: Wrapper for data retrieve, DetectNodes and StitchNodes. Simulates streaming data processing by retrieving data in chunks and performing TCs node detection and stitching looping over time steps;

  • “readwrite_from_intake”: regrids the atmospheric data, saves it to disk as a netCDF file, and updates the tempest_dictionary and tempest_filein attributes of the Detector object;

  • “run_detect_nodes: runs the tempest extremes DetectNodes command on the regridded atmospheric data specified by the tempest_dictionary and tempest_filein attributes, saves the output to disk, and updates the tempest_fileout attribute of the Detector object;

  • “detect_nodes_zoomin”: wrapper which calls the readwrite_from_intake, run_detect_nodes and store_detect_nodes methods in a time loop;

  • “stitch_nodes_zoomin”: wrapper which calls the run stitch_nodes and store_stitch_nodes methods in a time loop;

  • “lonlatbox”: creates a lon lat box of specified width (in degrees). Called to store the original resolution vars only in a box centred over the TCs centres;

  • “store_fullres_field”: function to write original resolution variables around TCs centres and their trajectories. Output produced in a netcdf file.

Functions used

The python file tempest_utils.py contains some functions used to analyse the raw output of tempest-extremes:

  • “getNodes”: Retrieves nodes (i.e. TCs centres in thi s case) from a TempestExtremes file (.txt output from DetectNodes);

  • “getTrajectories”: Retrieves trajectories from a TempestExtremes file (.txt file generated from StitchNodes).

These functions are largerly based on the ones found in the CyMeP repository by Colin Zarzycki (https://github.com/zarzycki/cymep).

The python file tcs_utils.py contains some functions called by the TCs class and the DetectNodes and StitchNodes classes but external to them:

  • “lonlatbox”: define the list for the box to retain high res data in the vicinity of the TC centres;

  • “write_fullres_field”: writes the high resolution file (netcdf) format with values only within the TCs centres box.

Observations

Tropical cyclones tracks and variables structure in the vicinity of TCs are compared with ERA5 reanalysis data.

References

  • tempest-extremes GitHub: https://github.com/ClimateGlobalChange/tempestextremes

  • CyMeP GitHub: https://github.com/ClimateGlobalChange/tempestextremes

  • Ullrich, P.A., C.M. Zarzycki, E.E. McClenny, M.C. Pinheiro, A.M. Stansfield and K.A. Reed (2021) “TempestExtremes v2.1: A community framework for feature detection, tracking and analysis in large datasets” Geosci. Model. Dev. 14, pp. 5023–5048, DOI <10.5194/gmd-14-5023-2021>.

  • Zarzycki, C. M., P. A. Ullrich, and K. A. Reed, 2021: Metrics for Evaluating Tropical Cyclones in Climate Data. J. Appl. Meteor. Climatol., 60, 643–660, DOI <https://doi.org/10.1175/JAMC-D-20-0149.1>.

Example Plot(s)

../_images/tropical_cyclones1.png

Module of wind in the vicinity of a tropical cyclone following its trajectory (from the nextGEMS IFStco1279-orca025-cycle3 simulation).

../_images/tropical_cyclones2.png

Example of TCs trajectories computed from the nextGEMS IFS simulation tco1279-orca025-cycle3. Note the extratropical cyclone identifided offshore the East Coast of the US which might have been erroneously classified as tropical by the TempestExtremes algorithm.

Available demo notebooks

Notebooks are stored in diagnostics/tropical_cyclones/notebooks

Detailed API

This section provides a detailed reference for the Application Programming Interface (API) of the “tropical_cyclones” diagnostic, produced from the diagnostic function docstrings.

tropical_cyclones module

class tropical_cyclones.DetectNodes

Bases: object

Class Mixin to take care of detect nodes.

detect_nodes_zoomin()

Method for detecting the nodes of TCs and storing variables in a box centred over the TCs centres at each time step. Wrapper to read, prepare data and run DetectNodes at each time step

Parameters:

None

Returns:

None

read_lonlat_nodes()

Read from txt files output of DetectNodes the position of the centers of the TCs

Parameters:

tempest_fileout – output file from tempest DetectNodes

Returns:

Dictionary with ‘date’, ‘lon’ and ‘lat’ of the TCs centers

readwrite_from_intake(timestep)

Read and write data from intake reader for the specified timestep.

Parameters:

timestep – Timestep for which to read and write the data.

Returns:

None

run_detect_nodes(timestep)

” Basic function to call from command line tempest extremes DetectNodes. Runs the tempest extremes DetectNodes command on the regridded atmospheric data specified by the tempest_dictionary and tempest_filein attributes, saves the output to disk, and updates the tempest_fileout attribute of the Detector object.

Parameters:

  • tempest_dictionary – python dictionary with variable names for tempest commands

  • tempest_filein – file (netcdf) with low res data

  • tempest_fileout – output file (.txt) from DetectNodes command

Returns:

output file from DetectNodes in string format

store_detect_nodes(timestep, write_fullres=True)

Store the output of DetectNodes in a netcdf file.

Parameters:

  • timestep – Timestep for which to store the data.

  • write_fullres – Boolean to write the full resolution data to disk.

Returns:

None

class tropical_cyclones.StitchNodes

Bases: object

Class Mixin to take care of stitch nodes

prepare_stitch_nodes(block, dates_freq, dates_ext)

Prepares the stitch nodes for the given block and time window by gathering relevant file paths and filenames.

Parameters:

  • block – Block for which the stitch nodes are being prepared.

  • dates_freq – DatetimeIndex with daily frequency for the time window.

  • dates_ext – Extended DatetimeIndex with the time window around the initial date.

Returns:

None

reorder_tracks()

Open the total track files, reorder tracks in time then creates a dict with time and lons lats pair of every track.

Parameters:

track_file – input track file from tempest StitchNodes

Returns:

Python dictionary with date lon lat of TCs centres after StitchNodes has been run

run_stitch_nodes(maxgap='24h', mintime='54h')

” Basic function to call from command line tempest extremes StitchNodes.

Parameters:

  • maxgap (str) – The maximum time gap allowed between consecutive nodes.

  • mintime (str) – The minimum track duration required for a node to be included.

Returns:

None

set_time_window(n_days_freq=30, n_days_ext=10)

Set the time window parameters for frequency and extension.

Parameters:

  • n_days_freq (optional) – Number of days for the frequency of time windows.

  • n_days_ext (optional) – Number of days for the extension of time windows.

Returns:

None

stitch_nodes_zoomin(startdate, enddate, n_days_freq, n_days_ext)

Method for producing tracks of selected variables stored in netcdf files. Wrapper for run_stitch_nodes and store_stitch_nodes for selected time period.

Parameters:

  • startdate – Start date of the chosen period.

  • enddate – End date of the chosen period.

  • n_days_freq – Number of days for the frequency of time windows.

  • n_days_ext – Number of days for the extension of time windows.

Returns:

None

store_stitch_nodes(block, dates_freq, write_fullres=True)

Store stitched tracks for each variable around the Nodes in NetCDF files.

Parameters:

  • block – Block representing a specific time period.

  • dates_freq – Frequencies of dates used for storing the tracks.

  • write_fullres (optional) – Boolean flag indicating whether to write full-resolution fields. Default is True.

Returns:

None

time_window(initial_date)

Creates a time window around the initial date by extending the dates index.

Parameters:

initial_date – Initial date of the time window.

Returns:

DatetimeIndex with daily frequency starting from the initial date. dates_ext: Extended DatetimeIndex with the time window around the initial date.

Return type:

dates_freq

class tropical_cyclones.TCs(tdict=None, paths=None, model=None, exp='None', source2d='None', source3d='None', boxdim=10, lowgrid='r100', highgrid='r010', var2store=None, streaming=False, frequency='6h', startdate=None, enddate=None, stream_step=1, stream_unit='days', stream_startdate=None, loglevel='INFO', orography=False, nproc=1)

Bases: DetectNodes, StitchNodes

This class contains all methods related to the TCs (Tropical Cyclones) diagnostic based on tempest-estremes tracking. It provides two main functions - “detect_nodes_zoomin” and “stitch_nodes_zoomin” - for detecting the nodes of TCs and producing tracks of selected variables stored in netcdf files, respectively.

Constructor method that initializes the class attributes based on the input arguments or tdict dictionary.

Parameters:

  • tdict (dict) – A dictionary containing various configurations for the TCs diagnostic. If tdict is provided, the configurations will be loaded from it, otherwise the configurations will be set based on the input arguments.

  • paths (dict) – A dictionary containing file paths for input and output files.

  • model (str) – The name of the weather model to be used for the TCs diagnostic. Default is “IFS”.

  • exp (str) – The name of the weather model experiment to be used for the TCs diagnostic. Default is “tco2559-ng5”.

  • boxdim (int) – The size of the box centred over the TCs centres in the detect_nodes_zoomin method. Default is 10.

  • lowgrid (str) – The low-resolution grid used for detecting the nodes of TCs. Default is ‘r100’.

  • highgrid (str) – The high-resolution grid used for detecting the nodes of TCs. Default is ‘r010’.

  • var2store (list) – The list of variables to be stored in netcdf files. Default is None.

  • streaming (bool) – A flag indicating whether the TCs diagnostic is performed in streaming mode. Default is False.

  • frequency (str) – The time frequency for processing the TCs diagnostic. Default is ‘6h’.

  • startdate (str) – The start date for processing the TCs diagnostic.

  • enddate (str) – The end date for processing the TCs diagnostic.

  • stream_step (int) – The number of stream units to move forward in each step in streaming mode. Default is 1.

  • stream_unit (str) – The unit of stream_step in streaming mode. Default is ‘days’.

  • stream_startdate (str) – The start date for processing the TCs diagnostic in streaming mode.

  • loglevel (str) – The logging level for the TCs diagnostic. Default is ‘INFO’.

Returns:

A TCs object

catalog_init()

Initialize the catalog for data retrieval based on the specified model.

Args: - self: Reference to the current instance of the class.

Returns:

None

Raises: - Exception: If the specified model is not supported.

data_retrieve(reset_stream=False)

Retrieve the necessary 2D and 3D data for analysis.

Args: - self: Reference to the current instance of the class. - reset_stream (optional): Boolean flag indicating whether to reset the stream. Default is False.

Returns:

None

loop_streaming(tdict)

Wrapper for data retrieve, DetectNodes and StitchNodes. Simulates streaming data processing by retrieving data in chunks and performing TCs node detection and stitching looping over time steps.

Parameters:

  • self – The current object instance.

  • tdict – A dictionary containing various parameters for streaming and stitching.

Returns:

None

store_fullres_field(xfield, nodes)

Create xarray object that keep only the values of a field around the TC nodes

Parameters:

  • mfield – xarray object (set to 0 at the first timestep of a loop)

  • xfield – xarray object to be concatenated with mfield

  • nodes – dictionary with date, lon, lat of the TCs centres

  • boxdim – length of the lat lon box (required for lonlatbox funct)

Returns:

xarray object with values only in the box around the TC nodes centres for all time steps

Return type:

outfield

tropical_cyclones.multi_plot(tracks_nc_file, tdict, title=None, units=None, save=False)
tropical_cyclones.plot_hist_cat(trajfile1, trajfile2, trajfile3, ibtracs_file=None)
tropical_cyclones.plot_press_wind(trajfile1, trajfile2, trajfile3, ibtracs_file, dot_dim)
tropical_cyclones.plot_trajectories(trajfile, tdict)