This page was generated from hwms.ipynb.
Interactive online version:
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:
Data Dictionaries: Understand the structure and meaning of the data.
Data Retrieval: Learn how to fetch all available data by type.
Filtered Queries: Dive deeper with specific, filtered data requests.
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.
[1]:
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").
[2]:
hwm_all = STNFloodEventData.get_all_data(
"hwms", as_list=False, async_retriever_kwargs={"disable": True, "max_workers": 6}
)
hwm_all.head()
[2]:
| 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
[3]:
hwm_all = gh.stn_flood_event("hwms")
[4]:
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.
[5]:
hwm_all.sample(1000).explore(
marker_kwds={"radius": 2},
style_kwds={"stroke": False},
)
[5]: