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(float) or 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 decimal 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(ax, radius=None, t_range=None, coordinate_system=2, track_style='ko--', categorization='NHC', fill_alpha=0.25, fill_color='red')

TO DO: Write doc-string

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, force=False, skip=True, verbose=False, fill_dict={}, **kwargs)

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.

• skip (bool) Skip a time if NaNs are found and are not replaced.

  Default is True.

• force (bool) Force output of storm even if there is missing data.

  Default is False.

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

  Default is False.

• fill_dict (dict) Dictionary of functions to use to fill in missing

  data represented by NaNs. The keys are the field to be filled and the function signature should be my_func(t, storm) where t is the time of the forecast and storm is the storm object. If the field remains a NaN or a function is not provided these lines will be assumed redundant and will be ommitted. Note that the older keyword arguments are put in this dictionary. Currently the one default function is for storm_radius, which sets the value to 500 km.

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/clawpack_src/clawpack_master/geoclaw/src/python/geoclaw/surge/storm.py:docstring of clawpack.geoclaw.surge.storm, line 12)

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/clawpack_src/clawpack_master/geoclaw/src/python/geoclaw/surge/storm.py:docstring of clawpack.geoclaw.surge.storm, line 23)

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