Catching the Flow
Real Streamflow Data
In Module 3 you read the shape of a hydrograph on synthetic data. Now you locate a real USGS gauge on a map, fetch its multi-year record, plot the annual regime, and find the year it flooded — all in one Python cell.
Six-step tour — click to jump
1 · Four teaching gauges — four stories
USGS operates ~8 000 active stream gauges in CONUS. We've chosen four whose records tell distinctly different hydrological stories — a range every hydrology student should recognise. Click a card to select that gauge.
2 · Locate your gauge on the map
The four curated gauges are pinned below. Click a marker to jump to that gauge's card above. The selected gauge (highlighted blue) is what the Python cell will use.
Interactive map loads inside the AI-Hydro Preview panel.
Tip: In the AI-Hydro map panel, use Hydrography → Add HUCs or search by gauge ID to layer USGS stations over any basemap.
3 · Select your gauge & fetch the record
Choose a gauge below, then click Run ▶. The cell tries to pull
5 years of real USGS daily values via dataretrieval.
If that package isn't installed, it synthesises a CAMELS-shaped record so the module
always works even offline.
waterservices.usgs.gov when dataretrieval is installed.
A progress message appears while the request runs. If you're offline, the synthetic fallback kicks in automatically.
fetch_streamflow_data then extract_hydrological_signatures.
4 · Reading the annual regime
The lower panel of the plot shows the annual regime — mean discharge for each calendar month, averaged over the whole record. Each gauge has a distinctive signature shape:
5 · Spotting a flood event
In the cell output, flood days are shaded amber — days where discharge exceeds the 95th percentile threshold of the whole record. This is a simple but robust peak-over-threshold (POT) approach used in operational flood studies.
Why P95?
The 95th percentile means only 5% of all days exceed it. On a 5-year record that's ~91 days — spread across several distinct flood events. Lowering the threshold captures minor high-flow days; raising it isolates only extreme events.
Return period
The peak printed below the plot is the multi-year maximum. Dividing the record length by the number of exceedances gives a rough return period estimate — useful context for flood risk but needs longer records for reliability.
6 · Checkpoint
Answer all three questions correctly to mark this module complete.
USGS measures streamflow at a gauge by recording water level (stage) and converting it to discharge using a rating curve. What is the key assumption behind that conversion?
Rillito Creek in Tucson records near-zero flow for most of the year, then spikes violently during July–September. Which catchment characteristic best explains this pattern?
The 95th-percentile threshold is used in the cell to colour flood days. If you instead used the 99th percentile, what would change in the plot?
References
- USGS National Water Information System (NWIS). Real-time and historical streamflow data. U.S. Geological Survey. waterdata.usgs.gov/nwis
- Addor, N., Newman, A.J., Mizukami, N. & Clark, M.P. (2017). The CAMELS data set: catchment attributes and meteorology for large-sample studies. Hydrology and Earth System Sciences, 21, 5293–5313. DOI: 10.5194/hess-21-5293-2017
- Pettitt, A.N. (1979). A non-parametric approach to the change-point problem. Applied Statistics, 28(2), 126–135. (Background: regime shifts in streamflow.)
- Moore, C. et al. (2019). dataretrieval: a Python package for accessing USGS water data. GitHub: DOI-USGS/dataretrieval-python
dataretrieval (real data) or CAMELS-shaped synthetic fallback.