Storm Specification Class and Tools

Warning

This describes new tools added in Clawpack 5.5

Module defines a class and routines for managing storm best-track type input and testing reconstructed wind and pressure fields. Additionally some support for ensembles of storms from various providers is also included.

The primary class of interest in the module is the Storm class that facilitates dealing with various best-track formats found around the world and the expected GeoClaw storm format that is read into the FORTRAN code. The basic workflow in a setrun.py file would do the following:

  1. Create a Storm object by reading in from a file:

    storm = clawpack.geoclaw.surge.storm.Storm("my_storm.txt", file_format='ATCF')

  2. Write out the storm object created into the GeoClaw format:

    storm.write("my_geoclaw_storm.txt", file_format="geoclaw")

  3. Specify the path to the GeoClaw formatted storm file, in this case “my_geoclaw_storm.txt”.

Formats Supported

  • GeoClaw (fully)

  • ATCF (reading only)

  • HURDAT (reading only)

  • IBTrACS (reading only)

  • JMA (reading only)

  • IMD (planned)

  • tcvitals (reading only)

exception clawpack.geoclaw.surge.storm.NoDataError

Exception to raise when no valid data in input file

class clawpack.geoclaw.surge.storm.Storm(path=None, file_format='ATCF', **kwargs)

Storm data object

This object contains a time series of time data that describe a particular storm. This includes the attributes below and the ability to read from multiple sources for data such as the U.S. National Hurricane Center (NHC), the Japanese Meterological Agency (JMA), and the Indian Meteorlogical Department (IMD). This class can then write out in any of these formats, construct the wind and pressure fields using a supported parameterized model, or output the GeoClaw supported storm format used for running storm surge simulations.

TODO: Add description of unit handling

Attributes

  • t (list(datetime.datetiem)) Contains the time at which each entry of the other arrays are at. These are expected to be datetime objects. Note that when written some formats require a time_offset to be set.

  • eye_location (ndarray(:, :)) location of the eye of the storm. Default units are in signed decimcal longitude and latitude.

  • max_wind_speed (ndarray(:)) Maximum wind speed. Default units are meters/second.

  • max_wind_radius (ndarray(:)) Radius at which the maximum wind speed occurs. Default units are meters.

  • central_pressure (ndarray(:)) Central pressure of storm. Default units are Pascals.

  • storm_radius (ndarray(:)) Radius of storm, often defined as the last closed iso-bar of pressure. Default units are meters.

  • time_offset (datetime.datetime) A date time that as an offset for the simulation time. This will default to the beginning of the first of the year that the first time point is found in.

  • wind_speeds (ndarray(:, :)) Wind speeds defined in every record, such as 34kt, 50kt, 64kt, etc and their radii. Default units are meters/second and meters.

Initialization

  1. Read in existing file at path.

  2. Construct an empty storm and supply the fields needed. Note that these fields must be converted to the appropriate units.

Input

  • path (string) Path to file to be read in if requested.

  • file_format (string) Format of file at path. Default is “hurdat”

  • kwargs (dict) Other key-word arguments are passed to the appropriate read routine.

category(categorization='NHC', cat_names=False)

Categorizes storm based on relevant storm data

Input

  • categorization (string) Type of categorization to use. Defaults to the National Hurricane Center “NHC”.

  • cat_names (bool) If True returns the category name rather than a number. Default to False.

Output

  • (ndarray) Integer array of categories at each time point of the storm.

  • (list) Similar to the above but the name of the category as a string. This is only returned if car_names = True.

plot(axes=None, intensity=False, limits=None, track_color='red', category_color=None, categorization='NHC', plot_package=None)

Plot the track and optionally the intensity of the storm

Easily plot the track and intensity of a storm using a mapping package.

Input

  • axes (matplotlib.pyplot.axes) Axes to plot into. Default is None

  • intensity (bool) Plot the intensity of storm along the track. Defaults to False.

  • limits (list) Limits of the plot specified. Defaults to either using the plotting package’s default or the max and min of the longitude and latitude of the storm track.

  • track_color (str) String or specification of plotting color to use for the track if intensity is not being plotted.

  • category_color (dict) Dictionary containing mapping between category numerical value and colors. Defaults to [0, 5] -> [‘red’, ‘yellow’, ‘orange’, ‘green’, ‘blue’, ‘gray’]

  • categorization (str) Type of categorization, defaults to “NHC”

  • plot_package (str) Package that will do the plotting. Available packages include ‘cartopy’, ‘basemap’ and ‘basic’. Checks to see what packages are available if None is given.

Output

  • (matplotlib.pyplot.axes) Axes object that was plotted into.

read(path=None, file_format='atcf', **kwargs)

Read in storm data from path with format file_format

Input

  • path (string) Path to data file.

  • file_format (string) Format of the data file. See list of supported formats for a list of valid strings. Defaults to “hurdat”.

  • kwargs (dict) Keyword dictionary for additional arguments that can be passed down to the appropriate read functions. Please refer to the specific routine for a list of valid options.

Raises

  • ValueError If the file_format requested does not match any of the available supported formats a ValueError is raised.

read_atcf(path, verbose=False)

Read in a ATCF formatted storm file

ATCF format has storm stored individually so there is no support for multiple storms in a particular file.

Input

  • path (string) Path to the file to be read.

  • verbose (bool) Output more info regarding reading.

read_geoclaw(path, verbose=False)

Read in a GeoClaw formatted storm file

GeoClaw storm files are read in by the Fortran code and are not meant to be human readable.

Input

  • path (string) Path to the file to be read.

  • verbose (bool) Output more info regarding reading.

read_hurdat(path, verbose=False)

Read in HURDAT formatted storm file

This is the current version of HURDAT data available (HURDAT 2). Note that this assumes there is only one storm in the file (includes the header information though). Future features will be added that will allow for a file to be read with multiple storms defined.

For more details on the HURDAT format and getting data see

http://www.aoml.noaa.gov/hrd/hurdat/Data_Storm.html

Input

  • path (string) Path to the file to be read.

  • verbose (bool) Output more info regarding reading.

Raises

  • ValueError If the method cannot find the name/year matching the storm or they are not provided when single_storm == False then a value error is risen.

read_ibtracs(path, sid=None, storm_name=None, year=None, start_date=None, agency_pref=['wmo', 'usa', 'tokyo', 'newdelhi', 'reunion', 'bom', 'nadi', 'wellington', 'cma', 'hko', 'ds824', 'td9636', 'td9635', 'neumann', 'mlc'])

Read in IBTrACS formatted storm file

This reads in the netcdf-formatted IBTrACS v4 data. You must either pass the sid of the storm (a unique identifier supplied by IBTrACS) OR storm_name and year. The latter will not be unique for unnamed storms, so you may optionally pass start_date as well. The wmo_* variable is used when non-missing, with missing values filled in by the corresponding variable of the agency specified in wmo_agency and/or usa_agency. If still missing, the other agencies are checked in order of agency_pref to see if any more non-missing values are available.

Input

  • path (string) Path to the file to be read.

  • sid (string, optional) IBTrACS-supplied unique track identifier.

    Either sid OR storm_name and year must not be None.

  • storm_name (string, optional) name of storm of interest

    (NAME field in IBTrACS). Either sid OR storm_name and year must not be None.

  • year (int, optional) year of storm of interest.

    Either sid OR storm_name and year must not be None.

  • start_date (datetime.datetime, optional) If storm is not

    named, will find closest unnamed storm to this start date. Only used for unnamed storms when specifying storm_name and year does not uniquely identify storm.

  • agency_pref (list, optional) Preference order to use if wmo_* variable

    is missing and wmo_agency and usa_agency are also missing.

Raises
  • ValueError If the method cannot find the matching storm then a

    value error is risen.

read_imd(path, verbose=False)
Extract relevant hurricane data from IMD file

and update storm fields with proper values.

Input

  • path (string) Path to the file to be read.

Return ValueError if format incorrect or if file not IMD.

read_jma(path, verbose=False)

Read in JMA formatted storm file

Note that only files that contain one storm are currently supported.

For more details on the JMA format and getting data see

http://www.jma.go.jp/jma/jma-eng/jma-center/rsmc-hp-pub-eg/Besttracks/e_format_bst.html

Input

  • path (string) Path to the file to be read.

  • verbose (bool) Output more info regarding reading.

Raises

  • ValueError If the method cannot find the name/year matching the storm or they are not provided when single_storm == False then a value error is risen.

read_tcvitals(path, verbose=False)
Extract relevant hurricane data from TCVITALS file

and update storm fields with proper values.

Input

  • path (string) Path to the file to be read.

  • verbose (bool) Output more info regarding reading.

write(path, file_format='geoclaw', **kwargs)

Write out the storm data to path in format file_format

Input

  • path (string) Path to data file.

  • file_format (string) Format of the data file. See list of supported formats for a list of valid strings. Defaults to “geoclaw”.

  • kwargs (dict) Keyword dictionary for additional arguments that can be passed down to the appropriate write functions. Please refer to the specific routine for a list of valid options.

Raises

  • ValueError If the file_format requested does not match any of the available supported formats a ValueError is raised.

write_atcf(path, verbose=False)

Write out a ATCF formatted storm file

Input

  • path (string) Path to the file to be written.

  • verbose (bool) Print out additional information when writing.

write_geoclaw(path, verbose=False, max_wind_radius_fill=None, storm_radius_fill=None)

Write out a GeoClaw formatted storm file

GeoClaw storm files are read in by the GeoClaw Fortran code.

Input

  • path (string) Path to the file to be written.

  • verbose (bool) Print out additional information when writing.

  • max_wind_radius_fill (func) Function that can be used to fill in missing data for max_wind_radius values. This defaults to simply setting the value to -1. The function signature should be max_wind_radius(t, storm) where t is the time of the forecast and storm is the storm object. Note that if this or storm_radius field remains -1 that this data line will be assumed to be redundant and not be written out.

  • storm_radius_fill (func) Function that can be used to fill in missing data for storm_radius values. This defaults to simply setting the value to -1. The function signature should be storm_radius(t, storm) where t is the time of the forecast and storm is the storm object. Note that if this or max_wind_radius field remains -1 that this data line will be assumed to be redundant and not be written

write_hurdat(path, verbose=False)

Write out a HURDAT formatted storm file

Input

  • path (string) Path to the file to be written.

  • verbose (bool) Print out additional information when writing.

write_imd(path, verbose=False)

Write out an IMD formatted storm file

Input

  • path (string) Path to the file to be written.

  • verbose (bool) Print out additional information when writing.

write_jma(path, verbose=False)

Write out a JMA formatted storm file

Input

  • path (string) Path to the file to be written.

  • verbose (bool) Print out additional information when writing.

write_tcvitals(path, verbose=False)

Write out an TCVITALS formatted storm file

Input

  • path (string) Path to the file to be written.

  • verbose (bool) Print out additional information when writing.

clawpack.geoclaw.surge.storm.available_formats()

Construct a string suitable for listing available storm file formats.

clawpack.geoclaw.surge.storm.available_models()

Construct a string suitable for listing available storm models.

clawpack.geoclaw.surge.storm.fill_rad_w_other_source(t, storm_targ, storm_fill, var, interp_kwargs={})

Fill in storm radius variable (max_wind_radius or storm_radius) with values from another source. i.e. if you have missing radii in IBTrACS, you can fill with ATCF. This function will assume storm_fill has more non-missing values than storm_targ for this particular radius variable. Thus, it first attempts to interpolate the variable in storm_fill to the desired timestep. If that is missing, it tries to interpolate the non-missing values of the variable in storm_targ. If that also fails, it simply returns -1. The proper usage of this function is to wrap it such that you can pass a function with (t, storm) arguments to max_wind_radius_fill or storm_radius_fill when calling write_geoclaw.

Input

System Message: WARNING/2 (/Users/rjl/Downloads/clawpack-v5.9.0/geoclaw/src/python/geoclaw/surge/storm.py:docstring of clawpack.geoclaw.surge.storm.fill_rad_w_other_source, line 15)

Field list ends without a blank line; unexpected unindent.

  • t (datetime.datetime) the time corresponding to

    a missing value of max_wind_radius or storm_radius

  • storm_targ (clawpack.geoclaw.storm.Storm) storm

    that has missing values you want to fill

  • storm_fill (clawpack.geoclaw.storm.Storm) storm

    that has non-missing values you want to use to fill storm_targ

  • var (str) Either ‘max_wind_radius’ or ‘storm_radius’

  • interp_kwargs (dict) Additional keywords passed to scipy’s

    interpolator.

Returns

System Message: WARNING/2 (/Users/rjl/Downloads/clawpack-v5.9.0/geoclaw/src/python/geoclaw/surge/storm.py:docstring of clawpack.geoclaw.surge.storm.fill_rad_w_other_source, line 26)

Field list ends without a blank line; unexpected unindent.

  • (float) value to use to fill this time point in storm_targ. -1

    if still missing after using storm_fill to fill.

Examples

>>> storm_ibtracs = Storm(file_format='IBTrACS', path='path_to_ibtracs.nc',
...     sid='2018300N26315')

>>> storm_atcf = Storm(file_format='ATCF', path='path_to_atcf.dat')

>>> def fill_mwr(t, storm):
...     return fill_rad_w_other_source(t, storm, storm_atcf, 'max_wind_radius')

>>> storm_ibtracs.write(file_format = 'geoclaw',
...     path = 'out_path.storm',
...     max_wind_radius_fill = fill_mwr)
clawpack.geoclaw.surge.storm.make_multi_structure(path)

Create a dictionary of Storm objects for ATCF files with multiple storm tracks in them