Exploring CONUS Hydrology

This module mirrors the spirit of PyGeoHydro’s interactive_map — discover USGS streamgages, NID dams, and WBD hydrologic units for a map extent — inside AI-Hydro HTML Preview. Refine it here, then publish to the AI-Hydro Modules marketplace when ready.

Tip: Use the native map panel’s Search and Hydrography → Add HUCs for the same data while you work in a project.

Study extent

Default: Wabash River region (Indiana). Adjust sliders, then run the cells below.

West lon: -88.5 South lat: 39.5 East lon: -85.5 North lat: 41.5

1 — Streamgages in extent

import matplotlib.pyplot as plt
from pygeohydro import NWIS

west, south, east, north = {{west}}, {{south}}, {{east}}, {{north}}
bbox = f"{west:.4f},{south:.4f},{east:.4f},{north:.4f}"
nwis = NWIS()
sites = nwis.get_info(
    {"bBox": bbox, "siteTypeCd": "ST", "siteStatus": "all"},
    expanded=True,
)
print(f"Found {len(sites)} USGS streamgages in bbox")
if sites.empty:
    print("Try widening the extent or panning to CONUS.")
else:
    fig, ax = plt.subplots(figsize=(8, 5))
    ax.scatter(sites.dec_long_va, sites.dec_lat_va, s=18, c="#00DDFF", edgecolors="#003366", linewidths=0.4)
    ax.set_xlim(west, east)
    ax.set_ylim(south, north)
    ax.set_xlabel("Longitude")
    ax.set_ylabel("Latitude")
    ax.set_title("USGS streamgages (NWIS)")
    ax.grid(True, alpha=0.25)
    plt.tight_layout()
    plt.show()
    for _, row in sites.head(8).iterrows():
        print(f"  {row.site_no}: {row.station_nm}")

2 — Hydrologic unit (WBD)

from pygeohydro import WBD
from shapely.geometry import Point

west, south, east, north = {{west}}, {{south}}, {{east}}, {{north}}
lon, lat = (west + east) / 2, (south + north) / 2
wbd = WBD("huc8")
pt = Point(lon, lat)
gdf = wbd.bygeom((lon - 0.02, lat - 0.02, lon + 0.02, lat + 0.02), geo_crs=4326)
if gdf.empty:
    print("No HUC8 polygon at center — adjust extent.")
else:
    row = gdf.iloc[0]
    cols = [c for c in row.index if "huc" in str(c).lower() or str(c).lower() in ("name", "areasqkm")]
    print("Containing HUC8 unit:")
    for c in cols[:6]:
        print(f"  {c}: {row[c]}")
gdf2 = WBD("huc8").bygeom((west, south, east, north), geo_crs=4326)
print(f"\nHUC8 polygons intersecting view: {len(gdf2)}")

3 — Dams (NID)

from pygeohydro import NID

west, south, east, north = {{west}}, {{south}}, {{east}}, {{north}}
nid = NID()
dams = nid.get_bygeom((west, south, east, north), 4326)
print(f"NID dams in extent: {len(dams)}")
for _, row in dams.head(10).iterrows():
    name = row.get("dam_name", row.get("name", "?"))
    did = row.get("id", "?")
    print(f"  {did}: {name}")

Next steps: Add Folium popups, quizzes, or a scrolly narrative — then copy to modules/exploring-conus-hydrology/ in the Modules repo with manifest.json for one-click install.