Meteorological Forcing Python API

See also

This is the Python API for building and writing GeoClaw meteorological forcing. The object model separates the evolving feature (a Track / StormTrack) from the forcing generated from it (ParametricMetForcing, GriddedMetForcing). The historical Storm class is retained as a backwards-compatible wrapper.

Readers ingest many track/data formats; writers emit only the two files GeoClaw consumes – a parametric storm file (write_geoclaw) and a gridded descriptor (write_data).

Storm (compatibility wrapper)

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.met.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)

  • Data

Object model:

Storm is a thin backwards-compatibility wrapper over the meteorological forcing object model introduced by the refactor: StormTrack, ParametricMetForcing, and GriddedMetForcing. Every legacy attribute is exposed as a property delegating to the underlying object.

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

Bases: object

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.

Storm is a thin compatibility wrapper: it holds a StormTrack (plus a ParametricMetForcing for the parameterized/track path) and a GriddedMetForcing for the gridded (data) path, and exposes every legacy attribute as a property delegating to the appropriate underlying object.

TODO: Add description of unit handling

Attributes:

  • t (list(float) or list(np.datetiem64)) Contains the time at which each entry of the other arrays are at. These are expected to be datetime64 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 (np.datetiem64) 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.

property ID
property basin
category(categorization='NHC', cat_names=False)

Categorize the storm (delegates to StormTrack.category()).

property central_pressure
property classification
property crop_extent
property event
property eye_location
property file_format
property file_paths
property max_wind_radius
property max_wind_speed
property met_fill_action
property met_fill_value
property met_lon_wrap
property met_time_name
property met_time_offset
property met_variable_map
property met_x_name
property met_y_increasing
property met_y_name
property name
plot(ax, *args, **kwargs)

Plot this storm’s track (delegates to StormTrack.plot()).

property ramp_width
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, **kwargs)

Read in an ATCF formatted storm file (delegates to StormTrack.read_atcf()).

read_data(path, **kwargs)

Read in a data-derived (gridded) storm file (delegates to GriddedMetForcing.read_data()).

read_geoclaw(path, **kwargs)

Read in a GeoClaw formatted storm file (delegates to ParametricMetForcing.read_geoclaw()).

read_hurdat(path, **kwargs)

Read in a HURDAT formatted storm file (delegates to StormTrack.read_hurdat()).

read_ibtracs(path, **kwargs)

Read in an IBTrACS formatted storm file (delegates to StormTrack.read_ibtracs()).

read_imd(path, **kwargs)

Read in an IMD formatted storm file (delegates to StormTrack.read_imd()).

read_jma(path, **kwargs)

Read in a JMA formatted storm file (delegates to StormTrack.read_jma()).

read_tcvitals(path, **kwargs)

Read in a TCVITALS formatted storm file (delegates to StormTrack.read_tcvitals()).

property scaling
property storm_radius
property storm_time_scale
property t
property time_offset
property wind_speeds
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)

(Not implemented) Write out a ATCF formatted storm file.

write_data(path, **kwargs)

Write out a data-derived (gridded) storm descriptor (delegates to GriddedMetForcing.write_data()).

write_geoclaw(path, **kwargs)

Write out a GeoClaw formatted storm file (delegates to ParametricMetForcing.write_geoclaw()).

write_hurdat(path, verbose=False)

(Not implemented) Write out a HURDAT formatted storm file.

write_imd(path, verbose=False)

(Not implemented) Write out an IMD formatted storm file.

write_jma(path, verbose=False)

(Not implemented) Write out a JMA formatted storm file.

write_tcvitals(path, verbose=False)

(Not implemented) Write out a TCVITALS formatted storm file.

property x_shift
property y_shift
clawpack.geoclaw.met.storm.available_formats()

Construct a string suitable for listing available storm file formats.

clawpack.geoclaw.met.storm.available_models()

Construct a string listing the available parameterized-forcing models.

The models are split into those supported by the GeoClaw Fortran code and those implemented in Python (currently none), both clearly labeled.

clawpack.geoclaw.met.storm.cle_2015(storm, r, t)
clawpack.geoclaw.met.storm.construct_fields(storm, r, t, model='holland_1980')
clawpack.geoclaw.met.storm.holland_1980(storm, r, t)
clawpack.geoclaw.met.storm.holland_2010(storm, r, t)

Track and StormTrack

Track and StormTrack objects for meteorological forcing.

This module defines the Track and StormTrack objects used by the meteorological-forcing refactor along with the track-format readers that produce a StormTrack (ATCF, HURDAT, IBTrACS, JMA, TCVITALS). The parsing logic here is moved verbatim from the original Storm readers so the parsed values (and any downstream emitted bytes) are byte-for-byte identical.

A Track is a generic evolving spatial feature (a center location over time). A StormTrack adds storm-specific metadata (intensity, radii, classification, basin). The time axis is a NumPy datetime64 array, uniform with the gridded field axis (see met_forcing_refactor.md Section 6).

class clawpack.geoclaw.met.track.Basin(*values)

Bases: Enum

Canonical tropical-cyclone basin, independent of source vocabulary.

CENTRAL_PACIFIC = 'central_pacific'
EAST_PACIFIC = 'east_pacific'
NORTH_ATLANTIC = 'north_atlantic'
NORTH_INDIAN = 'north_indian'
SOUTHERN_HEMISPHERE = 'southern_hemisphere'
SOUTH_ATLANTIC = 'south_atlantic'
SOUTH_INDIAN = 'south_indian'
SOUTH_PACIFIC = 'south_pacific'
UNKNOWN = 'unknown'
WEST_PACIFIC = 'west_pacific'
exception clawpack.geoclaw.met.track.NoDataError

Bases: ValueError

Exception to raise when no valid data in input file

class clawpack.geoclaw.met.track.StormStatus(*values)

Bases: Enum

Canonical storm status (development stage), not Saffir-Simpson category.

DISSIPATING = 'dissipating'
DISTURBANCE = 'disturbance'
EXTRATROPICAL = 'extratropical'
HURRICANE = 'hurricane'
INLAND = 'inland'
LOW = 'low'
SUBTROPICAL_DEPRESSION = 'subtropical_depression'
SUBTROPICAL_STORM = 'subtropical_storm'
SUPER_TYPHOON = 'super_typhoon'
TROPICAL_CYCLONE = 'tropical_cyclone'
TROPICAL_DEPRESSION = 'tropical_depression'
TROPICAL_STORM = 'tropical_storm'
TROPICAL_WAVE = 'tropical_wave'
TYPHOON = 'typhoon'
UNKNOWN = 'unknown'
class clawpack.geoclaw.met.track.StormTrack(**kwargs)

Bases: Track

A Track carrying storm-specific metadata.

Adds intensity-like parameters (max_wind_speed, max_wind_radius, central_pressure, storm_radius) and optional descriptors (classification, basin, wind_speeds). Supports both tropical and extratropical systems. The track-format readers below are classmethods that produce a populated StormTrack.

Quadrant wind radii, where the source provides them, are in wind_radii with shape (n_times, n_thresholds, 4) in metres, the last axis ordered NE, SE, SW, NW (WIND_RADII_QUADRANTS) and the middle axis matching wind_radii_thresholds (34/50/64 kt as m/s). np.nan means not reported. Note the archives differ on whether a zero is data: HURDAT2 has an explicit -999 for unknown, so a zero radius there is a real zero and is kept; ATCF leaves an unavailable quadrant as 0, which is indistinguishable from a genuine zero, so those become np.nan.

basin and classification remain the source’s own strings. For comparisons across formats use basin_standard() and status(), which map onto the Basin and StormStatus enums.

basin_standard()

This track’s basin as a Basin, or Basin.UNKNOWN.

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, *args, t_range=None, categorization=None, cat_colors={}, plot_swath=False, radius=None, coordinate_system=2, fill_alpha=0.25, fill_color='red', **kwargs)

Plot this storm’s track in the given axes object

Input:

  • ax (matplotlib.pyplot.axes) Axes to plot into.

  • t_range (list) Time range to plot the track for. If None then use

    entire range. Default is None.

  • categorization (str) Type of categorization to be used. This is

    used to map to the keys in the cat_colors dictionary. Default is None and will cause no categorization to occur.

  • cat_colors (dict) Color mapping between numeric categorization and

    colors to be plotted for the track.

  • plot_swath (bool) Plot a swath around the track using one of the

    methods determined by what radius information is provided. Default is False.

  • radius (None or float or numpy.ndarray)

  • coordinate_system (int)

  • fill_alpha (float)

  • fill_color (color)

  • kwargs All additional keyword arguments are passed to the plotting

    command for the track.

classmethod 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.

classmethod read_hurdat(path, verbose=False, storm_id=None, name=None, year=None)

Read a HURDAT2 formatted storm file.

This is the current version of HURDAT data available (HURDAT 2). The archives NOAA/AOML distributes hold every storm in a basin in one file (~2000 storms for the Atlantic, 1851-present), so pass a selector to pick one; a file containing a single storm needs no selector. Use iter_hurdat() to walk every storm, or catalog_hurdat() for an index of what a file contains.

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.

  • storm_id (string) ATCF-style id to select, e.g. "AL092008".

  • name (string) Storm name to select, e.g. "IKE" (case-insensitive).

  • year (int) Season to select; combine with name when a name has been reused across seasons.

Raises:

  • ValueError If no storm matches the selector, or if the file holds more than one storm and no selector narrows it to exactly one.

classmethod read_ibtracs(path, sid=None, storm_name=None, year=None, start_date=None, agency_pref=None)

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 (np.datetime64, 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.

classmethod 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.

classmethod 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.

classmethod 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.

status()

Per-time storm status as StormStatus values.

None when the source carried no classification.

class clawpack.geoclaw.met.track.Track(t=None, center=None, name=None, id=None, event=None, meta=None)

Bases: object

Generic evolving feature with a spatial center over time.

Attributes:

  • t (ndarray) datetime64 array of times for each track point.

  • center (ndarray(:, :)) (n, 2) array of (lon, lat). For a tropical cyclone this is the eye; for other systems it is the central point (e.g. a pressure minimum).

  • name, id, event optional metadata.

property ID
property eye_location
property file_format
property file_paths
property time_offset
clawpack.geoclaw.met.track.catalog_hurdat(path, years=None, basins=None)

Index of the storms in a HURDAT2 file, as a pandas.DataFrame.

Columns: storm_id, name, year, basin, num_records, t_start, t_end. Reads only each storm’s first and last record, so it is much cheaper than building every track – use it to decide what to run before running it.

clawpack.geoclaw.met.track.catalog_ibtracs(path, basin=None, years=None)

Index of the storms in an IBTrACS file, as a pandas.DataFrame.

Columns: sid, name, season, basin, num_records, t_start, t_end, max_wind (m/s, from wmo_wind where present). Reads summary variables only, so it is far cheaper than building every track – use it to decide what to run before running it.

clawpack.geoclaw.met.track.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 returns np.nan. 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:

  • t (np.datetime64) 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:

  • (float) value to use to fill this time point in storm_targ. np.nan if still missing after using storm_fill to fill, so a failed fill is skipped by write_geoclaw rather than written out.

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.met.track.iter_hurdat(path, storm_ids=None, names=None, years=None, basins=None, verbose=False)

Iterate the storms in a HURDAT2 file as StormTrack objects.

One pass over the file, yielding in file order. Every filter is optional and they combine; years accepts an int or any iterable of ints, so a season range is years=range(1980, 2026).

Input:

  • path (string) Path to a HURDAT2 file (one or many storms).

  • storm_ids (iterable) ATCF-style ids to keep, e.g. ["AL092008"].

  • names (iterable) Storm names to keep (case-insensitive).

  • years (int or iterable) Seasons to keep.

  • basins (string or iterable) Two-letter basin codes to keep.

  • verbose (bool) Print each storm as it is read.

Output:

  • Generator of StormTrack, each with file_format = "hurdat".

Missing RMW/ROCI is warned about once for the whole iteration rather than once per storm; HURDAT2 never carries either.

clawpack.geoclaw.met.track.iter_ibtracs(path, basin=None, years=None, sids=None, names=None, agency_pref=None, skip_invalid=True, verbose=False)

Iterate storms in an IBTrACS v4 netCDF file as :class:`StormTrack`s.

Opens the file once and slices per storm, rather than re-scanning it for every StormTrack.read_ibtracs() call.

Input:

  • path (string) Path to an IBTrACS v4 netCDF file.

  • basin (string or iterable) Two-letter basin code(s) of storm origin, e.g. "NA"; matches what the reader stores as basin.

  • years (int or iterable) Seasons to keep, e.g. range(1980, 2026).

  • sids (iterable) IBTrACS storm ids to keep.

  • names (iterable) Storm names to keep (case-insensitive).

  • agency_pref (list) As StormTrack.read_ibtracs().

  • skip_invalid (bool) Skip storms with no time at which both a wind and a pressure were reported, instead of raising. Load-bearing over a whole basin: such storms exist, and one of them should not abort the sweep.

  • verbose (bool) Report each storm as it is read.

Output:
clawpack.geoclaw.met.track.standardize_basin(code, source='atcf')

Map a format’s basin code onto a Basin.

Unrecognized codes give Basin.UNKNOWN rather than raising: a new or misspelled code in an archive should not stop a track from being read.

clawpack.geoclaw.met.track.standardize_status(code, source='atcf')

Map a format’s status code onto a StormStatus.

Unrecognized codes give StormStatus.UNKNOWN rather than raising.

Parametric met forcing

Parameterized meteorological forcing.

ParametricMetForcing holds a Track (or StormTrack), a model identifier, and model configuration. It provides the GeoClaw parametric-forcing reader (read_geoclaw) and writer (write_geoclaw), both moved verbatim from the original Storm implementation so the emitted bytes stay identical.

time_offset is Python-to-Fortran conversion metadata resolved at the write boundary exactly as before (it is stored on the track’s shared _Meta and proxied here).

class clawpack.geoclaw.met.parametric.ParametricMetForcing(track=None, model=None)

Bases: object

Forcing generated from a parameterized model referencing a track.

Attributes:

  • track (StormTrack) The track/event the forcing references.

  • model (str) Model identifier (e.g. "holland80"). Not required by the GeoClaw writer, which emits the compact track-parameter file.

property central_pressure
property eye_location
property file_format
property file_paths
property max_wind_radius
property max_wind_speed
property name
classmethod 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.

property storm_radius
property t
property time_offset
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; a caller-supplied storm_radius fill overrides it.

Missing data is marked by numpy.nan. A negative value in one of the four intensity/geometry fields is also accepted as missing, for objects built against the older -1 convention, and warns. Zero is not treated as missing. A fill function’s return value is re-checked, so a fill that cannot produce a value leaves the row skipped rather than writing a sentinel into the file. Fills are applied to internal copies; the storm object is not modified.

Gridded met forcing

Gridded meteorological forcing.

GriddedMetForcing describes file-backed wind/pressure fields (OWI/ASCII and NetCDF). It owns the file paths, the numeric file_format tag, the NetCDF variable/dimension mapping and interpolation metadata, and the forcing controls (scaling, storm time scaling, spatial crop, edge ramping, registration shift).

The descriptor reader (read_data) and writer (write_data) are moved verbatim from the original Storm implementation so the emitted descriptor bytes are byte-for-byte identical. write_data reuses clawpack.geoclaw.netcdf_utils.MetInspector / DescriptorWriter.

class clawpack.geoclaw.met.gridded.GriddedMetForcing(meta=None)

Bases: object

Forcing read from external gridded wind/pressure field datasets.

property file_format
property file_paths
classmethod from_owi(pressure_path, wind_path, time_offset=None, meta=None)

Build a descriptor-ready forcing for an existing OWI WIN/PRE pair.

Input:

  • pressure_path (path-like) the .PRE file.

  • wind_path (path-like) the .WIN file.

  • time_offset (datetime64, optional) forcing time reference; if omitted it is read from the first record of pressure_path.

classmethod read_data(path: Path, verbose: bool = False)

Read in a data derived storm data information file

Input:

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

  • verbose (bool) Output more info regarding reading.

property time_offset
to_owi(data, pressure_path, wind_path)

Write data to an OWI WIN/PRE pair and point this forcing at it.

Input:

  • data (OWIData) fields.

  • pressure_path, wind_path (path-like) output files ([PRE, WIN]).

write_data(path, dim_mapping=None, var_mapping=None, met_inspector=None, verbose=False)

Workflow tools

Workflow tools for meteorological-forcing / storm data.

This module hosts higher-level workflow helpers that operate on storm files but are not part of the core object model. It provides iter_atcf for walking a multi-track ATCF file in memory and make_multi_structure for the older split-to-disk workflow (now a thin wrapper over iter_atcf). storm.py keeps an import shim so the historical import path continues to work.

clawpack.geoclaw.met.tools.iter_atcf(path)

Iterate the storms in a multi-storm ATCF file, without writing to disk.

The in-memory counterpart to make_multi_structure(), and the companion of met.track.iter_hurdat / iter_ibtracs for the other two archive formats.

Input:

  • path (path-like) - the (possibly multi-storm) ATCF file to read.

Output:

  • Generator of (storm_id, Storm) pairs, where storm_id is basin plus cyclone number (e.g. "AL09"), in the order the storms first appear.

read_atcf takes a path rather than an open handle, so each storm’s records are staged through a temporary file that is removed immediately afterwards; nothing is left in the working directory.

clawpack.geoclaw.met.tools.make_multi_structure(path, output_dir='Clipped_ATCFs')

Split a multi-storm ATCF file into individual Storm objects.

Some ATCF files bundle several storms in one file, distinguished by their basin and cyclone number (the first two comma-separated fields of each b-deck record, e.g. AL and 09). This groups the records by that identity, writes each storm’s records to its own file under output_dir, and reads them back as Storm objects.

Use iter_atcf() instead when the per-storm files are not wanted; this function exists for the workflow where they are.

Input:

  • path (path-like) - the multi-storm ATCF file to split.

  • output_dir (path-like) - directory the per-storm ATCF files are written into (created if it does not exist).

Output:

  • (OrderedDict) mapping each storm id (basin + cyclone number, e.g. "AL09") to a Storm read from that storm’s records, in the order the storms first appear in the file.

Met forcing data object

The surge.data file written by setrun.py is described by SurgeData (also available under the alias MetData); it is set in setrun.py as rundata.met_data (the former rundata.surge_data remains an accepted alias). See Storm Specification Data for the per-attribute reference.

class clawpack.geoclaw.data.SurgeData

Bases: ClawData

Meteorological (storm) forcing parameters written to surge.data.

Set as rundata.surge_data in a setrun.py and written to surge.data, which the Fortran met_forcing_module reads to activate and configure wind/pressure forcing. See Storm Specification Data for the per-attribute reference.

Forcing selection:

The forcing family and subtype are the preferred, explicit way to select a model:

  • storm_family – "parametric" (an analytic model with a storm center/track), "gridded" (file-backed wind/pressure fields, e.g. OWI/ASCII or NetCDF), or "none" (forcing off).

  • storm_subtype – for a parametric family, a model name such as "holland80", "holland2010", "cle", "slosh", "rankine", "modified_rankine", "demaria", or "willoughby"; for a gridded family, "gridded".

The legacy storm_specification_type (a model-name string or the signed integer code, e.g. "holland80"/1 or "data"/-1) remains fully supported: when storm_family/storm_subtype are unset it is resolved through forcing_subtype_registry. All three map to the same forcing on the surge.data wire.

Key attributes:

  • wind_forcing / pressure_forcing (bool) – enable the wind and pressure source terms.

  • drag_law (int) – wind-drag law (0 none, 1 Garratt, 2 Powell).

  • wind_index / pressure_index (int) – 0-based aux component indices for the forcing fields (Fortran indexing is +1).

  • storm_time_scale (float) – multiplicative scale on the storm time axis (>1 slower, <1 faster).

  • t_ramp_on / t_ramp_off (float) – seconds over which the forcing ramps on after t0 and off before tfinal (0 disables).

  • rotation_override (int/str) – override the hemisphere-based storm rotation sense.

  • wind_refine / R_refine (list/bool) – AMR refinement thresholds on wind speed and (parametric only) distance to the storm center.

  • storm_file (str) – path to the storm track file or gridded descriptor.

See Meteorological Forcing Python API for the Python storm/track object model and Sources for Storm Surge Data for storm data sources.

read(path: Path = PosixPath('surge.data'), force: bool = False)

Read surge data file

storm_spec_dict_mapping = {'cle': 3, 'data': -1, 'demaria': 7, 'gridded': -1, 'holland08': 8, 'holland10': 2, 'holland2008': 8, 'holland2010': 2, 'holland80': 1, 'modified-rankine': 6, 'modified_rankine': 6, 'none': 0, 'rankine': 5, 'slosh': 4, 'willoughby': 9, None: 0}
storm_spec_not_implemented = {}
write(out_file='surge.data', data_source='setrun.py')

Write out the data file to the path given