Checking for non-preferred file/folder path names (may take a long time depending on the number of files/folders) ...

HySwap Area-Based Runoff Duration Hydrographs — Massachusetts (7-Day Statistic)
Authors:
Owners: This resource does not have an owner who is an active HydroShare user. Contact CUAHSI (help@cuahsi.org) for information on this resource.
Type: Resource
Storage: The size of this resource is 25.1 KB
Created: Mar 14, 2026 at 12:19 a.m. (UTC)
Last updated: Mar 14, 2026 at 12:30 a.m. (UTC)
Citation: See how to cite this resource
Sharing Status: Public
Views: 48
Downloads: 5
+1 Votes: Be the first one to 
 this.
Comments: No comments (yet)

Abstract

This resource provides a Jupyter Notebook workflow for computing and visualizing area-based runoff duration hydrographs for HUC08 watersheds in Massachusetts using the USGS hyswap (Hydrologic Surface Water Analysis Package) Python package. Daily mean streamflow records are retrieved from the USGS National Water Information System (NWIS) for all streamgages with drainage basins that intersect Massachusetts HUC08 watersheds. Streamflow is normalized by drainage area to produce runoff in millimeters per day and aggregated to the HUC08 scale using an area-weighted mean approach. A 7-day rolling average is applied prior to analysis. Variable percentile thresholds (5th, 10th, 25th, 50th, 75th, 90th, and 95th percentiles) are computed by day-of-year from the full historical record (1990-2024), and Water Year 2024 runoff is overlaid on the resulting percentile envelope for each HUC08. The notebook is designed to run directly on the CUAHSI JupyterHub Python environment with minimal setup.

Subject Keywords

Content

README.md

Area-Based Runoff Duration Hydrographs — Massachusetts (7-Day Statistic)

Overview

This resource contains a Jupyter Notebook for generating area-based runoff duration hydrographs for HUC08 watersheds in the state of Massachusetts using the USGS hyswap Python package. Runoff is calculated from USGS NWIS streamgage data, normalized by drainage area, and smoothed using a 7-day rolling average. Historical percentile envelopes are computed for each HUC08 and plotted alongside the Water Year 2024 runoff trace.

Files

File Description
ma_runoff_duration_hydrograph.ipynb Main Jupyter Notebook — downloads data, computes runoff, and generates plots

How to Run

This notebook is designed to run on the CUAHSI JupyterHub (Python environment) with no manual package installation required. The first code cell installs the necessary packages automatically:

!pip install hyswap pynhd folium mapclassify --quiet

Steps: 1. Open this resource on HydroShare 2. Click "Open With" → "CUAHSI JupyterHub" 3. Select the Python server environment 4. Run all cells (Kernel → Restart & Run All)

Variables

Variable Description Units
estimated_runoff Area-weighted mean runoff estimated for each HUC08 mm/day
runoff Site-level runoff converted from streamflow at individual USGS gages mm/day
00060_Mean Daily mean streamflow (USGS NWIS parameter code 00060) ft³/s (cfs)
drain_area_va Gage drainage area from NWIS site metadata mi²
da_km2 Gage drainage area converted for runoff calculation km²
water_year USGS water year (Oct 1 – Sep 30); year N begins Oct 1 of year N−1 —
prop_huc_in_basin Proportion of a HUC08's area that falls within a gage basin fraction (0–1)
prop_basin_in_huc Proportion of a gage basin's area that falls within a HUC08 fraction (0–1)
HIST_START / HIST_END Date range used to build historical percentile baselines YYYY-MM-DD
PLOT_WATER_YEAR Target water year overlaid on duration hydrograph plots integer (e.g., 2024)
N_DAY Number of days in the rolling average window integer (days)
PERCENTILE_THRESHOLDS Percentile levels computed for the historical envelope % [5, 10, 25, 50, 75, 90, 95]

Abbreviations and Acronyms

Abbreviation Definition
USGS U.S. Geological Survey
NWIS National Water Information System
HUC Hydrologic Unit Code
HUC08 8-digit Hydrologic Unit Code (sub-basin scale)
CONUS Contiguous United States
WY Water Year (Oct 1 – Sep 30)
cfs Cubic feet per second
mm/day Millimeters per day
NHD National Hydrography Dataset
CUAHSI Consortium of Universities for the Advancement of Hydrologic Science, Inc.
hyswap Hydrologic Surface Water Analysis Package (USGS Python package)

Non-Standard File Formats

Format / File Description
.ipynb Jupyter Notebook file (JSON-based). Open via JupyterLab, Jupyter Notebook, VS Code, or the CUAHSI JupyterHub. Do not open as plain text.
huc_props_tbl_conus.csv HUC08–gage basin spatial intersection table distributed with the hyswap package. Downloaded automatically by the notebook from the hyswap GitHub repository if not found locally. Columns: da_site_no (USGS site number), huc_id (8-digit HUC), prop_basin_in_huc, prop_huc_in_basin.

Dependencies

Package Source Notes
hyswap pip USGS Hydrologic Surface Water Analysis Package
dataretrieval pip / conda-forge USGS NWIS data access
pynhd pip National Hydrography Dataset access via WaterData API
geopandas conda-forge / pip Geospatial dataframes
folium pip Interactive map rendering
mapclassify pip Classification schemes for choropleth maps
pandas conda-forge / pip Tabular data manipulation
matplotlib conda-forge / pip Plotting
numpy conda-forge / pip Numerical computation

Funding

This work was supported by the U.S. Geological Survey (USGS).

References

  • Bock, A.R. et al. (2024). hyswap: Hydrologic Surface Water Analysis Package. U.S. Geological Survey. https://doi-usgs.github.io/hyswap/
  • USGS National Water Information System (NWIS): https://waterdata.usgs.gov/nwis
  • USGS National Water Dashboard: https://dashboard.waterdata.usgs.gov

Credits

Funding Agencies

This resource was created using funding from the following sources:
Agency Name Award Title Award Number
USGS None None

How to Cite

Read, J. S. (2026). HySwap Area-Based Runoff Duration Hydrographs — Massachusetts (7-Day Statistic), HydroShare, http://www.hydroshare.org/resource/6631c6b1d65f4031b9b67578cf2624ab

This resource is shared under the Creative Commons Attribution CC BY.

 http://creativecommons.org/licenses/by/4.0/
CC-BY

Comments

There are currently no comments

New Comment

required