This page was generated from hwms.ipynb. Interactive online version: Binder badge

USGS STN Flood Event Data: High Water Marks#

The United States Geological Survey (USGS) operates a comprehensive flood event database known as the Short-Term Network (STN). The STN offers a user-friendly web front-end for easy access. For developers and scientists, there’s a RESTFul API available for more advanced queries and integrations. The STN offers access to a variety of data types including instruments, sites, high water marks, and peak summaries.

Focus: High Water Marks (HWMs)#

In this notebook, we’ll delve into the specifics of high water marks (HWMs) within the STN database. Here’s what you can expect:

  1. Data Dictionaries: Understand the structure and meaning of the data.

  2. Data Retrieval: Learn how to fetch all available data by type.

  3. Filtered Queries: Dive deeper with specific, filtered data requests.

  4. Data Limitations: We’ll also touch upon some of the known limitations including inconsistent field names and possibility for user introduced errors.

Additional Resources:#

For those interested in the methodology behind HWM collection, the USGS provides detailed resources: - Technical Guide on HWMs - High Water Marks & Flooding Overview - Video Guide: Interpreting High Water Marks

Let’s begin by importing necessary dependencies.

from pathlib import Path

import matplotlib.lines as mlines
import matplotlib.markers as mmarkers
import matplotlib.pyplot as plt
import pandas as pd

import pygeohydro as gh
from pygeohydro import STNFloodEventData

After importing, we can start with how we can obtain all the HWM data available in the database as a GeoDataFrame. We have two options for get STN data: STNFloodEventData class or stn_flood_event function. The stn_flood_event function can only pull either the information dataset about the supported data_types by STN as a pandas.DataFrame or a subset of the actual data for the supported STN data_types as a geopandas.GeoDataFrame. Moreover, the STNFloodEventData class provides access to some other data about the STN service such as data dictionary.

For example, we can get information about HWMS data either using STNFloodEventData.get_all_data("hwms") or gh.stn_flood_event("hwms").

hwm_all = STNFloodEventData.get_all_data(
    "hwms", as_list=False, async_retriever_kwargs={"disable": True, "max_workers": 6}
hwm_id waterbody site_id event_id hwm_type_id hwm_quality_id hwm_locationdescription latitude_dd longitude_dd survey_date ... survey_member_id hwm_label files stillwater peak_summary_id last_updated last_updated_by uncertainty hwm_uncertainty geometry
0 13922 Swatara Creek 16106 123 1 1 HWM is located on inside of pavillion two 40.192896 -76.723080 2012-04-26T04:00:00 ... 202.0 no_label NaN NaN NaN NaN NaN NaN NaN POINT (-76.72308 40.19290)
1 17897 Atlantic Ocean 19148 24 1 3 Mud line on bench rocks and plants near IBA Cl... 41.894148 -70.536629 2017-06-05T04:00:00 ... 2.0 HWMMAPLY-402 NaN 0.0 NaN NaN NaN NaN NaN POINT (-70.53663 41.89415)
2 19685 East Nishnabotna River 20005 168 5 6 U.S. Highway 34, seed line on flood wall (1 of... 41.026290 -95.243199 1998-07-28T05:00:00 ... 1757.0 HWM U/S NaN 1.0 3337.0 NaN NaN NaN NaN POINT (-95.24320 41.02629)
3 18530 Maquoketa River 19436 151 6 1 County Road X29/220th Avenue, southwest of Del... 42.410092 -91.363481 2010-07-30T05:00:00 ... 1755.0 USGS HWM D/S NaN 1.0 2710.0 NaN NaN NaN NaN POINT (-91.36348 42.41009)
4 19687 East Nishnabotna River 20005 168 2 6 U.S. Highway 34, debris line on guardrail (2 o... 41.026290 -95.243199 1998-07-28T05:00:00 ... 1757.0 HWM U/S NaN 1.0 3337.0 NaN NaN NaN NaN POINT (-95.24320 41.02629)

5 rows × 33 columns

hwm_all = gh.stn_flood_event("hwms")
print(f"There are {len(hwm_all)} HWMs in the database.")
There are 34722 HWMs in the database.

For an interactive map, we can use the explore method. There are at least 34,000 HWMs in the STN database scattered throughout the country. It’s important to note the possibility of outliers as this data is collected by people and liable to errors. Here, we plot a sample of 1000 HWMs.

    marker_kwds={"radius": 2},
    style_kwds={"stroke": False},
Make this Notebook Trusted to load map: File -> Trust Notebook