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)
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.
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_colors=None, categorization='NHC')

Plot the track and optionally the strength of the storm

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, storm_name, year)

Read in IBTrACS formatted storm file

This reads in the netcdf-formatted IBTrACS v4 BETA data. The .nc file passed as path must contain a storm matching storm_name and year. This function will be updated, if needed, once the BETA version becomes an operational release.

NOTE: Thus far, only the reading of hurdat/atcf-based best tracks (i.e. USA tracks) is supported.

TODO: account for data formats from other reporting agencies

For more details on the IBTrACS v4 BETA format and getting data see

ftp://filsrv.cicsnc.org/kknapp/ibtracs/testing/hotel1/provisional/

Input:
  • path (string) Path to the file to be read.
  • storm_name (string) name of storm of interest (NAME field in IBTrACS).
  • year (int) year of storm of interest
Raises:
  • ValueError If the method cannot find the name/year matching the 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.