Retrieving data for a specific storm

The StormEvent class provides an interface to retrieve data within the time interval and spatial bounds of a specific storm event.

class stormevents.stormevent.StormEvent(name: str, year: int, start_date: datetime | None = None, end_date: datetime | None = None)

The StormEvent class can be used to retrieve data related to any arbitrary named storm event.

Parameters:

• name – storm name

• year – storm year

• start_date – starting time

• end_date – ending time

>>> StormEvent('florence', 2018)
StormEvent(name='FLORENCE', year=2018, start_date=Timestamp('2018-08-30 06:00:00'), end_date=Timestamp('2018-09-18 12:00:00'))

>>> StormEvent('paine', 2016, start_date='2016-09-18', end_date=datetime(2016, 9, 19, 12))
StormEvent(name='PAINE', year=2016, start_date=Timestamp('2016-09-18 00:00:00'), end_date=datetime.datetime(2016, 9, 19, 12, 0))

>>> StormEvent('florence', 2018, start_date=timedelta(days=2))
StormEvent(name='FLORENCE', year=2018, start_date=Timestamp('2018-09-01 06:00:00'), end_date=Timestamp('2018-09-18 12:00:00'))

>>> StormEvent('henri', 2021, start_date=timedelta(days=-3), end_date=timedelta(days=-2))
StormEvent(name='HENRI', year=2021, start_date=Timestamp('2021-08-21 12:00:00'), end_date=Timestamp('2021-08-22 12:00:00'))

>>> StormEvent('ida', 2021, end_date=timedelta(days=2))
StormEvent(name='IDA', year=2021, start_date=Timestamp('2021-08-27 18:00:00'), end_date=Timestamp('2021-08-29 18:00:00'))

classmethod from_nhc_code(nhc_code: str, start_date: datetime | None = None, end_date: datetime | None = None) → StormEvent

retrieve storm information from the NHC code

Parameters:

• nhc_code – NHC code

• start_date – starting time

• end_date – ending time

Returns:

storm object

>>> StormEvent.from_nhc_code('EP172016')
StormEvent(name='PAINE', year=2016, start_date=Timestamp('2016-09-18 00:00:00'), end_date=Timestamp('2016-09-21 12:00:00'))

classmethod from_usgs_id(usgs_id: int, year: int | None = None, start_date: datetime | None = None, end_date: datetime | None = None) → StormEvent

retrieve storm information from the USGS flood event ID

Parameters:

• usgs_id – USGS flood event ID

• start_date – starting time

• end_date – ending time

Returns:

storm object

>>> StormEvent.from_usgs_id(310)
StormEvent(name='HENRI', year=2021, start_date=Timestamp('2021-08-20 18:00:00'), end_date=Timestamp('2021-08-24 12:00:00'))

property nhc_code: str

return: NHC code, for example AL112013 for the 11th Atlantic storm in 2013, or EP032011 for the 3rd Pacific storm in 2011

property usgs_id: int

return: USGS flood event ID

property basin: str

return: basin in which storm occurred

property number: int

return: ordinal number of storm in the year

track(start_date: datetime | None = None, end_date: datetime | None = None, file_deck: ATCF_FileDeck | None = None, advisories: List[ATCF_Advisory] | None = None, filename: PathLike | None = None, forecast_time: datetime | None = None) → VortexTrack

retrieve NHC ATCF track data

Parameters:

• start_date – start date

• end_date – end date

• file_deck – ATCF file deck

• advisories – ATCF advisory types

• filename – file path to fort.22

Returns:

vortex track

>>> storm = StormEvent('florence', 2018)
>>> storm.track()
VortexTrack('AL062018', Timestamp('2018-08-30 06:00:00'), Timestamp('2018-09-18 12:00:00'), <ATCF_FileDeck.BEST: 'b'>, <ATCF_Mode.HISTORICAL: 'ARCHIVE'>, [<ATCF_Advisory.BEST: 'BEST'>], None)

property flood_event: USGS_StormEvent

return: USGS high-water marks (HWMs) for this storm event

>>> storm = StormEvent('florence', 2018)
>>> flood = storm.flood_event
>>> flood.high_water_marks()
         latitude  longitude          eventName  ... siteZone peak_summary_id                    geometry
hwm_id                                           ...
33496   37.298440 -80.007750  Florence Sep 2018  ...      NaN             NaN  POINT (-80.00775 37.29844)
33497   33.699720 -78.936940  Florence Sep 2018  ...      NaN             NaN  POINT (-78.93694 33.69972)
33498   33.758610 -78.792780  Florence Sep 2018  ...      NaN             NaN  POINT (-78.79278 33.75861)
33499   33.641389 -78.947778  Florence Sep 2018  ...                      NaN  POINT (-78.94778 33.64139)
33500   33.602500 -78.973889  Florence Sep 2018  ...                      NaN  POINT (-78.97389 33.60250)
...           ...        ...                ...  ...      ...             ...                         ...
34872   35.534641 -77.038183  Florence Sep 2018  ...      NaN             NaN  POINT (-77.03818 35.53464)
34873   35.125000 -77.050044  Florence Sep 2018  ...      NaN             NaN  POINT (-77.05004 35.12500)
34874   35.917467 -76.254367  Florence Sep 2018  ...      NaN             NaN  POINT (-76.25437 35.91747)
34875   35.111000 -77.037851  Florence Sep 2018  ...      NaN             NaN  POINT (-77.03785 35.11100)
34876   35.301135 -77.264727  Florence Sep 2018  ...      NaN             NaN  POINT (-77.26473 35.30114)
[644 rows x 53 columns]

coops_product_within_isotach(product: COOPS_Product, wind_speed: int, advisories: List[ATCF_Advisory] | None = None, status: StationStatus | None = None, start_date: datetime | None = None, end_date: datetime | None = None, datum: COOPS_TidalDatum | None = None, units: COOPS_Units | None = None, time_zone: COOPS_TimeZone | None = None, interval: COOPS_Interval | None = None, track: VortexTrack | None = None) → Dataset

retrieve CO-OPS tidal station data from within the specified polygon

Parameters:

• product – CO-OPS product

• wind_speed – wind speed in knots (one of 34, 50, or 64)

• advisories – ATCF advisory types

• start_date – start date

• end_date – end date

• status – either current or historical

• datum – tidal datum

• units – either metric or english

• time_zone – time zone

• interval – time interval

• track – vortex track object or file path to fort.22

Returns:

CO-OPS station data

>>> storm = StormEvent('florence', 2018)
>>> storm.coops_product_within_isotach('water_level', wind_speed=34, start_date='2018-09-12 14:03:00', end_date='2018-09-14')
<xarray.Dataset>
Dimensions:  (nos_id: 7, t: 340)
Coordinates:
  * nos_id   (nos_id) int64 8651370 8652587 8654467 ... 8658120 8658163 8661070
  * t        (t) datetime64[ns] 2018-09-12T14:06:00 ... 2018-09-14
    nws_id   (nos_id) <U5 'DUKN7' 'ORIN7' 'HCGN7' ... 'WLON7' 'JMPN7' 'MROS1'
    x        (nos_id) float64 -75.75 -75.56 -75.69 -76.69 -77.94 -77.81 -78.94
    y        (nos_id) float64 36.19 35.78 35.22 34.72 34.22 34.22 33.66
Data variables:
    v        (nos_id, t) float32 7.181 7.199 7.144 7.156 ... 9.6 9.634 9.686
    s        (nos_id, t) float32 0.317 0.36 0.31 0.318 ... 0.049 0.047 0.054
    f        (nos_id, t) object '0,0,0,0' '0,0,0,0' ... '0,0,0,0' '0,0,0,0'
    q        (nos_id, t) object 'v' 'v' 'v' 'v' 'v' 'v' ... 'v' 'v' 'v' 'v' 'v'

coops_product_within_region(product: COOPS_Product, region: Polygon, start_date: datetime | None = None, end_date: datetime | None = None, status: StationStatus | None = None, datum: COOPS_TidalDatum | None = None, units: COOPS_Units | None = None, time_zone: COOPS_TimeZone | None = None, interval: COOPS_Interval | None = None) → Dataset

retrieve CO-OPS tidal station data from within the specified region

Parameters:

• product – CO-OPS product; one of water_level, air_temperature, water_temperature, wind, air_pressure, air_gap, conductivity, visibility, humidity, salinity, hourly_height, high_low, daily_mean, monthly_mean, one_minute_water_level, predictions, datums, currents, currents_predictions

• region – a Shapely polygon denoting the region of interest

• start_date – start date

• end_date – end date

• status – either current or historical

• datum – tidal datum, one of STND, MSL, MHHW, MHW, MTL, MLW, MLLW, NAVD

• units – either metric or english

• time_zone – time zone

• interval – time interval

Returns:

CO-OPS station data

>>> import shapely
>>> storm = StormEvent('florence', 2018)
>>> region = shapely.geometry.box(*storm.track().linestrings.bounds)
>>> storm.coops_product_within_region('water_level', region=region, start_date='2018-09-12 14:03:00', end_date='2018-09-14')
<xarray.Dataset>
Dimensions:  (nos_id: 89, t: 340)
Coordinates:
  * nos_id   (nos_id) int64 2695535 2695540 8447386 ... 9759394 9759938 9761115
  * t        (t) datetime64[ns] 2018-09-12T14:06:00 ... 2018-09-14
    nws_id   (nos_id) <U5 'FRCB6' 'BEPB6' 'FRVM3' ... 'MGZP4' 'MISP4' 'BARA9'
    x        (nos_id) float64 -64.69 -64.69 -71.19 ... -67.19 -67.94 -61.81
    y        (nos_id) float64 32.38 32.38 41.72 41.69 ... 18.22 18.09 17.59
Data variables:
    v        (nos_id, t) float32 1.956 1.952 1.948 1.939 ... 8.916 8.901 8.898
    s        (nos_id, t) object 0.007000000216066837 ... '0.041'
    f        (nos_id, t) object '0,0,0,0' '0,0,0,0' ... '0,0,0,0' '0,0,0,0'
    q        (nos_id, t) object 'v' 'v' 'v' 'v' 'v' 'v' ... 'p' 'p' 'p' 'p' 'p'