USGS high water mark (HWM) surveys
The United States Geological Survey (USGS) conducts surveys of flooded areas following flood events to determine the highest level of water elevation, and provides the results of these surveys via their API.
list flood events that have HWM surveys
- stormevents.usgs.events.usgs_flood_events(year: int = None, event_type: EventType = None, event_status: EventStatus = None) DataFrame
this function collects all USGS flood events of the given type and status that have high-water mark data
https://stn.wim.usgs.gov/STNServices/Events.json
USGS does not standardize event naming, and they should. Year, month, and storm type are not always included. The order in which the names are in the response is also not standardized. This function applies a workaround to fill in gaps in data. USGS should standardize their REST server data.
- Parameters:
event_type – type of USGS flood event
year – year of event
event_status – status of USGS flood event
- Returns:
table of flood events
>>> usgs_flood_events() name year description ... last_updated_by start_date end_date usgs_id ... 7 FEMA 2013 exercise 2013 Ardent/Sentry 2013 FEMA Exercise ... NaN 2013-05-15 04:00:00 2013-05-23 04:00:00 8 Wilma 2005 Category 3 in west FL. Hurricane Wilma was t... ... NaN 2005-10-20 00:00:00 2005-10-31 00:00:00 9 Midwest Floods 2011 2011 Spring and summer 2011 flooding of the Mississ... ... 35.0 2011-02-01 06:00:00 2011-08-30 05:00:00 10 2013 - June PA Flood 2013 Localized summer rain, small scale event ... NaN 2013-06-23 00:00:00 2013-07-01 00:00:00 11 Colorado 2013 Front Range Flood 2013 A large prolonged precipitation event resulted... ... 35.0 2013-09-12 05:00:00 2013-09-24 05:00:00 ... ... ... ... ... ... ... ... 312 2021 Tropical Cyclone Ida 2021 NaN ... 864.0 2021-08-27 05:00:00 2021-09-03 05:00:00 313 Chesapeake Bay - October 2021 2021 Coastal-flooding event in the Chesapeake Bay. ... 406.0 2021-10-28 04:00:00 NaT 314 2021 November Flooding Washington State 2021 Atmospheric River Flooding ... 864.0 2021-11-08 06:00:00 2021-11-19 06:00:00 315 Washington Coastal Winter 2021-2022 2021 NaN ... 864.0 2021-11-01 05:00:00 2022-06-30 05:00:00 317 2022 Hunga Tonga-Hunga Haapai tsunami 2022 ... 1.0 2022-01-14 05:00:00 2022-01-18 05:00:00 [293 rows x 11 columns]
abstraction of a USGS flood event
- class stormevents.usgs.events.USGS_Event(id: int)
representation of an arbitrary flood event as defined by the USGS
- Parameters:
id – USGS event ID
>>> flood = USGS_Event(182) >>> flood.high_water_marks() latitude longitude eventName hwmTypeName ... hwm_label files siteZone geometry hwm_id ... 22636 32.007730 -81.238270 Irma September 2017 Seed line ... HWM1 [] NaN POINT (-81.23827 32.00773) 22757 30.510528 -81.460833 Irma September 2017 Debris ... HWM 1 [] 0 POINT (-81.46083 30.51053) 22885 30.770560 -81.581390 Irma September 2017 Seed line ... GACAM17842 [] NaN POINT (-81.58139 30.77056) 22965 31.063150 -81.404540 Irma September 2017 Debris ... HWM [] NaN POINT (-81.40454 31.06315) 23052 30.845000 -81.560000 Irma September 2017 Debris ... GACAM17840 [] NaN POINT (-81.56000 30.84500) ... ... ... ... ... ... ... ... ... ... 25147 30.018190 -81.859657 Irma September 2017 Mud ... HWM01 [] NaN POINT (-81.85966 30.01819) 25148 30.097214 -81.891451 Irma September 2017 Seed line ... hwm 01 [] NaN POINT (-81.89145 30.09721) 25150 30.038222 -81.880928 Irma September 2017 Seed line ... HWM01 [] NaN POINT (-81.88093 30.03822) 25158 29.720560 -81.506110 Irma September 2017 Seed line ... HWM [] NaN POINT (-81.50611 29.72056) 25159 30.097514 -81.794375 Irma September 2017 Seed line ... HWM 1 [] NaN POINT (-81.79438 30.09751) [221 rows x 52 columns] >>> flood.high_water_marks(quality=['EXCELLENT', 'GOOD']) latitude longitude eventName hwmTypeName ... hwm_label files siteZone geometry hwm_id ... 22636 32.007730 -81.238270 Irma September 2017 Seed line ... HWM1 [] NaN POINT (-81.23827 32.00773) 22885 30.770560 -81.581390 Irma September 2017 Seed line ... GACAM17842 [] NaN POINT (-81.58139 30.77056) 23130 31.034720 -81.640000 Irma September 2017 Seed line ... HWM1 [] NaN POINT (-81.64000 31.03472) 23216 32.035150 -81.045040 Irma September 2017 Seed line ... HWM1 [] NaN POINT (-81.04504 32.03515) 23236 32.083650 -81.157520 Irma September 2017 Seed line ... HWM1 [] NaN POINT (-81.15752 32.08365) ... ... ... ... ... ... ... ... ... ... 25146 29.992580 -81.851518 Irma September 2017 Seed line ... HWM 01 [] NaN POINT (-81.85152 29.99258) 25148 30.097214 -81.891451 Irma September 2017 Seed line ... hwm 01 [] NaN POINT (-81.89145 30.09721) 25150 30.038222 -81.880928 Irma September 2017 Seed line ... HWM01 [] NaN POINT (-81.88093 30.03822) 25158 29.720560 -81.506110 Irma September 2017 Seed line ... HWM [] NaN POINT (-81.50611 29.72056) 25159 30.097514 -81.794375 Irma September 2017 Seed line ... HWM 1 [] NaN POINT (-81.79438 30.09751) [138 rows x 52 columns]
- classmethod from_name(name: str, year: int | None = None) USGS_Event
retrieve high-water mark info from the USGS flood event name
- Parameters:
name – USGS flood event name
year – year of flood event
- Returns:
flood event object
- classmethod from_csv(filename: PathLike) USGS_Event
read a CSV file with high-water mark data
- Parameters:
filename – file path to CSV
- Returns:
flood event object
- property files: DataFrame
list of USGS-provided files surrounding this event
- Returns:
data frame of file information for this event
>>> event = USGS_Event(135) >>> event.files name ... is_nwis file_id ... 64549 HWM_Field notes.pdf ... NaN 55811 FLVOL03146_recoveryform.JPG ... NaN 65298 IMG_1489.JPG ... NaN 65299 IMG_1490.JPG ... NaN 60279 HWM_MEASURED.jpg ... NaN ... ... ... ... 61637 NCSAM18802 GNSS Survey.jpg ... NaN 57900 SC-BEA-0508.hwm pic1.jpg ... NaN 60277 SC-GEO-0918.hwm pic1.jpg ... NaN 62481 SCBEA18200_SurveySheet.jpg ... NaN 83448 SCBEA18345_FieldSheet.jpg ... NaN [5589 rows x 19 columns]
- property sensors: DataFrame
list of USGS sensors surrounding this event
- Returns:
data frame of sensor information for this event
>>> event = USGS_Event(135) >>> event.sensors sensor_type_id ... last_updated_by instrument_id ... 8080 1 ... NaN 7755 5 ... NaN 8097 5 ... NaN 8030 1 ... NaN 7846 1 ... NaN ... ... ... ... 7889 1 ... NaN 8967 1 ... 1692.0 9037 1 ... 3.0 8046 1 ... 761.0 9511 5 ... 35.0 [394 rows x 17 columns]
- retrieve_file(id: int, path: PathLike)
- high_water_marks(us_states: List[str] | None = None, us_counties: List[str] | None = None, hwm_type: HighWaterMarkType | None = None, quality: HighWaterMarkQuality | None = None, environment: HighWaterMarkEnvironment | None = None, survey_completed: bool | None = None, still_water: bool | None = None) GeoDataFrame
- Returns:
data frame of data for the current parameters
>>> flood = USGS_Event(182) >>> flood.high_water_marks() latitude longitude eventName hwmTypeName ... hwm_uncertainty hwm_notes siteZone geometry hwm_id ... 22602 31.170642 -81.428402 Irma September 2017 Debris ... NaN NaN NaN POINT (-81.42840 31.17064) 22605 31.453850 -81.362853 Irma September 2017 Seed line ... 0.1 NaN NaN POINT (-81.36285 31.45385) 22612 30.720000 -81.549440 Irma September 2017 Seed line ... NaN There is a secondary peak around 5.5 ft, so th... NaN POINT (-81.54944 30.72000) 22636 32.007730 -81.238270 Irma September 2017 Seed line ... 0.1 Trimble R8 used to establish TBM. Levels ran f... NaN POINT (-81.23827 32.00773) 22653 31.531078 -81.358894 Irma September 2017 Seed line ... NaN NaN NaN POINT (-81.35889 31.53108) ... ... ... ... ... ... ... ... ... ... 26171 18.470402 -66.246631 Irma September 2017 Debris ... 0.5 NaN NaN POINT (-66.24663 18.47040) 26173 18.470300 -66.449900 Irma September 2017 Debris ... 0.5 levels from GNSS BM NaN POINT (-66.44990 18.47030) 26175 18.463954 -66.140869 Irma September 2017 Debris ... 0.5 levels from GNSS BM NaN POINT (-66.14087 18.46395) 26177 18.488720 -66.392160 Irma September 2017 Debris ... 0.5 levels from GNSS BM NaN POINT (-66.39216 18.48872) 26179 18.005607 -65.871768 Irma September 2017 Debris ... 0.5 levels from GNSS BM NaN POINT (-65.87177 18.00561) [506 rows x 53 columns] >>> flood.high_water_marks(quality=['EXCELLENT', 'GOOD']) latitude longitude eventName hwmTypeName ... hwm_notes peak_summary_id siteZone geometry hwm_id ... 22605 31.453850 -81.362853 Irma September 2017 Seed line ... NaN NaN NaN POINT (-81.36285 31.45385) 22612 30.720000 -81.549440 Irma September 2017 Seed line ... There is a secondary peak around 5.5 ft, so th... NaN NaN POINT (-81.54944 30.72000) 22636 32.007730 -81.238270 Irma September 2017 Seed line ... Trimble R8 used to establish TBM. Levels ran f... NaN NaN POINT (-81.23827 32.00773) 22674 32.030907 -80.900605 Irma September 2017 Seed line ... NaN 5042.0 NaN POINT (-80.90061 32.03091) 22849 30.741940 -81.687780 Irma September 2017 Debris ... NaN 4834.0 NaN POINT (-81.68778 30.74194) ... ... ... ... ... ... ... ... ... ... 25150 30.038222 -81.880928 Irma September 2017 Seed line ... GNSS Level II survey. NaN NaN POINT (-81.88093 30.03822) 25151 30.118110 -81.760220 Irma September 2017 Seed line ... GNSS Level III survey. NaN NaN POINT (-81.76022 30.11811) 25158 29.720560 -81.506110 Irma September 2017 Seed line ... GNSS Level II survey. NaN NaN POINT (-81.50611 29.72056) 25159 30.097514 -81.794375 Irma September 2017 Seed line ... GNSS Level III survey. NaN NaN POINT (-81.79438 30.09751) 25205 29.783890 -81.263060 Irma September 2017 Seed line ... GNSS Level II survey. NaN NaN POINT (-81.26306 29.78389) [277 rows x 53 columns]