1 · USGS Hydrography — Watershed Boundaries & Context

First notebook in the Thornforest hydrology series. It builds the spatial foundation (the three HUC-8 watershed boundaries) that the other notebooks rely on, and maps it.

Our study area is three HUC-8 subbasins in South Texas: - South Laguna Madre (12110208) - Los Olmos (13090001) - Lower Rio Grande (13090002)

New to Python notebooks? Run each cell in order with Shift + Enter.

Step 1 — Imports and setup

All imports are at the top. init_session() (from our shared _helpers module) loads the optional USGS API key, configures the on-disk request cache, and returns the paths we use.

Show code 
from pygeohydro import WBD

import geoviews as gv
import geoviews.tile_sources as gvts

from _helpers import init_session, save_dataframe, save_workbook, show, categorical_colors

gv.extension("bokeh")
S = init_session()
ⓘ 
USGS API key loaded.

Step 2 — Name our three watersheds

A dictionary maps each HUC-8 code to a friendly name. Colors come from a colorcet categorical palette (via categorical_colors) so the figure data colors are perceptually distinct and consistent across the project.

Show code 
HUC8_WATERSHEDS = {
    "12110208": "South Laguna Madre",
    "13090001": "Los Olmos",
    "13090002": "Lower Rio Grande",
}
HUC8_COLORS = categorical_colors(HUC8_WATERSHEDS)  # huc8 code -> hex

Step 3 — Download the watershed boundaries

WBD("huc8").byids(...) fetches the three boundaries from the USGS Watershed Boundary Dataset. The request is cached on disk; the result is also saved to data/hydrography/.

Show code 
watersheds_gdf = WBD("huc8").byids("huc8", list(HUC8_WATERSHEDS))
save_dataframe(watersheds_gdf, S.data_dir / "hydrography" / "huc8_watersheds.parquet")
print(f"{len(watersheds_gdf)} watershed boundaries.")
saved 3 rows → data/hydrography/huc8_watersheds.parquet (+ .csv)
3 watershed boundaries.

What did we get back?

A GeoDataFrame (one row per watershed, with a geometry shape). The coordinates are longitude/latitude (EPSG:4326).

Show code 
print("Coordinate system:", watersheds_gdf.crs)
show(watersheds_gdf[["huc8", "name", "areasqkm", "states"]])
Coordinate system: EPSG:4326
huc8 name areasqkm states
0 12110208 South Laguna Madre 7730.32 TX
1 13090002 Lower Rio Grande 5501.93 MX,TX
2 13090001 Los Olmos 8145.84 MX,TX

Step 4 — Map the watersheds

We layer the boundaries over an Esri World Topo basemap; * stacks layers. data_aspect=1 keeps map pixels square so the basemap tiles aren’t stretched.

Explore: hover for name/area; zoom/pan with the toolbar; click legend entries.

Show code 
watershed_layers = []
for code, name in HUC8_WATERSHEDS.items():
    one = watersheds_gdf[watersheds_gdf["huc8"] == code]
    watershed_layers.append(
        gv.Polygons(one, vdims=["name", "huc8", "areasqkm"], label=name).opts(
            color=HUC8_COLORS[code],
            line_color=HUC8_COLORS[code],
            alpha=0.45,
            line_width=2,
            tools=["hover"],
        )
    )

watersheds_map = gvts.EsriWorldTopo
for layer in watershed_layers:
    watersheds_map = watersheds_map * layer

watersheds_map = watersheds_map.opts(
    data_aspect=1,
    title="Three HUC-8 Watersheds — Thornforest Study Area (South Texas)",
    legend_position="top_left",
)
watersheds_map

Step 5 — Export to Excel

Compiles the one saved table into a single downloadable workbook — one sheet, frozen header row + first column, with autofilter enabled on the header.

Show code 
save_workbook({"huc8_watersheds": watersheds_gdf}, S.data_dir / "hydrography" / "hydrography.xlsx")
saved 1 sheet(s) → data/hydrography/hydrography.xlsx
/Users/aaufdenkampe/Documents/git_Limno/Thornforest/notebooks/_helpers/excel.py:71: UserWarning: Cell contents too long (107804), truncated to 32767 characters
  df.to_excel(writer, sheet_name=sheet_name, index=False)
/Users/aaufdenkampe/Documents/git_Limno/Thornforest/notebooks/_helpers/excel.py:71: UserWarning: Cell contents too long (75339), truncated to 32767 characters
  df.to_excel(writer, sheet_name=sheet_name, index=False)
/Users/aaufdenkampe/Documents/git_Limno/Thornforest/notebooks/_helpers/excel.py:71: UserWarning: Cell contents too long (182871), truncated to 32767 characters
  df.to_excel(writer, sheet_name=sheet_name, index=False)

What’s next

The boundaries are saved to data/hydrography/. Notebook 3_usgs_waterdata reads them to discover the USGS monitoring stations inside the watersheds and the parameters they measure.

Back to top