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

NextGen Water Modeling Workflow for Research-Scale Applications
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 7.9 MB
Created: Mar 24, 2025 at 4:26 p.m. (UTC)
Last updated: May 22, 2026 at 5:34 p.m. (UTC) (Metadata update)
Published date: May 22, 2026 at 5:34 p.m. (UTC)
DOI: 10.4211/hs.27045581bdea4808a393330f2417379c
Citation: See how to cite this resource
Sharing Status: Published
Views: 2131
Downloads: 2526
+1 Votes: 1 other +1 this
Comments: 1 comment

Abstract

This HydroShare resource accompanies the journal article, “A cloud-based JupyterHub platform for community research with the NextGen water resources modeling framework,” published in Environmental Modelling & Software. The resource provides the datasets, workflows, notebooks, and supporting materials used in the study to facilitate reproducibility, collaboration, and community-based research with the NextGen water resources modeling framework. The paper is available at: https://doi.org/10.1016/j.envsoft.2026.107031

This HydroShare resource delivers a complete, modular workflow for implementing the Next Generation Water Resources Modeling Framework (NextGen) using cloud-based or containerized computing environments. The workflow guides users through each key component of a research-scale hydrologic modeling application, including model input data preparation, model configuration and execution, calibration, and performance evaluation.

To run this workflow, users must launch the resource within an interactive computing environment. From the HydroShare "Open With" web app connector, select "CIROH-2i2c JupyterHub", then choose the pre-configured "CIROH Community NextGen Hub" image. This environment includes all required NextGen tools and dependencies to ensure consistent, reproducible execution.

The workflow is organized into five interoperable Jupyter Notebooks that can be executed independently or as a full end-to-end sequence:

1. NextGen Data Preparation – Subsets the hydrofabric for a user-defined Area of Interest (AOI), generates meteorological forcing data, and creates model configuration files and realizations for CFE and Noah-OWP model components.

2. NextGen Run – Executes the NextGen model using default configurations to establish baseline simulation performance.

3. NextGen TEEHR Evaluation – Compares simulated streamflow results with USGS observations and the National Water Model Retrospective Analysis v3.0 using TEEHR (Tools for Exploratory Evaluation in Hydrologic Research).

4. NextGen Output Analysis – Visualizes water balance components and other model outputs for interpretation and post-processing.

5. NextGen Calibration – Applies SPOTPY-based optimization to improve model performance through automated streamflow calibration.

A lightweight Python wrapper, pyngiab.py, streamlines interaction with the NextGen model engine by managing configuration loading, model execution, and output organization directly from the notebooks.

Supplementary Python utility scripts support data subsetting, visualization, calibration, programmatic execution, and reproducible model management. Together, these components establish a transparent, adaptable, and fully traceable workflow to support collaborative hydrologic research, model testing, and community-driven advancement of the NextGen framework.

Subject Keywords

Coverage

Spatial

Coordinate System/Geographic Projection:
WGS 84 EPSG:4326
Coordinate Units:
Decimal degrees
Place/Area Name:
CONUS
North Latitude
49.8040°
East Longitude
-65.4594°
South Latitude
24.6390°
West Longitude
-124.8739°

Temporal

Start Date:
End Date:

Content

README.md

🌊 NextGen Modeling Workflow Resource

🔍 Overview

This HydroShare resource provides a complete, reproducible workflow for preparing, running, evaluating, calibrating, and analyzing research-scale simulations of the Next Generation Water Resources Modeling Framework (NextGen). It is designed for execution on the CIROH 2i2c-JupyterHub cloud platform.

✨ What This Resource Includes

  • 📓 Jupyter notebooks — data preparation, model execution, output evaluation (TEEHR), calibration, and analysis
  • 🛠️ Python utility modules — forcing visualization, HydroFabric exploration, calibration, output aggregation, and TEEHR evaluation

This resource enables hydrologic researchers and students to experiment with NextGen components, evaluate model skill against USGS and NWM datasets using TEEHR, visualize HydroFabric layers, and explore hydrologic behavior at subdomain scale.

📂 Contents

📓 1. Jupyter Notebooks

Notebook Description
📋 NextGen_Data_Preparation.ipynb Subsets HydroFabric, prepares forcing data, creates model realizations and configurations, and organizes model input and output directories.
▶️ NextGen_Run.ipynb Executes the NextGen model and generates cat-files (hydrologic variables), nexus output, and routing NetCDF results.
📊 NextGen_Outputs_Analysis.ipynb Processes outputs, computes basin-mean variables, and generates CSV summaries.
📈 NextGen_TEEHR_Evaluation.ipynb Evaluates simulated streamflow with TEEHR using USGS observations, NWM v3.0, and NextGen results; computes performance metrics and diagnostics.
⚙️ NextGen_Calibration.ipynb Performs automated calibration with SPOTPY using USGS observations and dynamic parameter updates.

🛠️ 2. Python Utility Modules

File Purpose
⚙️ cal_utils.py Calibration utilities (parameter updates, t-route output extraction, SPOTPY setup).
🌧️ forcings_utils.py Forcing data visualization, transformation, and time-series alignment.
🗺️ hydrofabric_visualization_utils.py Interactive HydroFabric visualization using Folium and GeoPandas.
📦 ngen_outputs_utils.py Aggregates Noah, CFE, and routing outputs with unit conversion and area weighting.
🔗 ngiab_utils.py Utilities for TEEHR-based NextGen evaluation and the NextGen_TEEHR_Evaluation.ipynb workflow.

🚀 Quick Start Guide

Workflow at a glance:

Step Icon Action Notebook
1 🚀 Launch environment — (open on CIROH JupyterHub)
2 📋 Prepare inputs NextGen_Data_Preparation.ipynb
3 ▶️ Run model NextGen_Run.ipynb
4 📊 Analyze outputs NextGen_Outputs_Analysis.ipynb
5 📈 Evaluate with TEEHR NextGen_TEEHR_Evaluation.ipynb
6 ⚙️ Calibrate parameters NextGen_Calibration.ipynb

💡 Tip: Run the steps in order: 📋 Prepare → ▶️ Run → 📊 Analyze → 📈 Evaluate → ⚙️ Calibrate

🚀 Step 1 — Launch the Environment

Open this resource in CIROH 2i2c-JupyterHub so NextGen, PyNGIAB, and TEEHR dependencies are available.

📋 Step 2 — Prepare Inputs

Use NextGen_Data_Preparation.ipynb to subset HydroFabric, prepare forcing data, and generate model configuration files.

▶️ Step 3 — Run NextGen

Run NextGen_Run.ipynb to produce hydrologic and routing outputs.

📊 Step 4 — Analyze Outputs

Use NextGen_Outputs_Analysis.ipynb for basin-mean calculations and CSV summaries.

📈 Step 5 — Evaluate Model Performance with TEEHR

Run NextGen_TEEHR_Evaluation.ipynb to:

  • 🔗 Add USGS, NWM, and NGIAB time series
  • 📐 Compute metrics (KGE, NSE, MAE, and others)
  • 📉 Generate performance and diagnostic plots

⚙️ Step 6 — Perform Calibration

Use NextGen_Calibration.ipynb for SPOTPY calibration and to update model parameters in realization.json.

👥 Intended Users

This resource is intended for:

  • 🌊 Hydrologic modelers
  • 🔬 CIROH researchers
  • 🎓 Students learning NextGen workflows
  • 📉 Analysts evaluating hydrologic prediction skill
  • ♻️ Anyone interested in reproducible modeling and model–data evaluation

📫 Contact

For questions or suggested improvements, contact:

  • Ayman Nassar — ayman.nassar@usu.edu; aymnassar@gmail.com
  • David Tarboton — david.tarboton@usu.edu

Related Resources

This resource is described by Tarboton, D., A. Nassar, H. Salehabadi, P. Dash, A. Patel, F. Baig, S. Wang, A. M. Castronova (2026). AMS 2026 Presentation: Enabling Community Collaboration and Open Science in Hydrology through Data and Model Sharing with CUAHSI HydroShare, HydroShare, http://www.hydroshare.org/resource/1bb4f2f28926483884a82d664c651df7
This resource is described by Nassar, A., Tarboton, D. G., Baig, F., Cunningham, J., Patel, A., Halgren, J., Lee, B., Salehabadi, H., Castronova, A. M., & Garousi-Nejad, I. (2026). A cloud-based JupyterHub platform for community research with the NextGen water resources modeling framework. Environmental Modelling & Software, 203, 107031. https://doi.org/10.1016/j.envsoft.2026.107031

Credits

Funding Agencies

This resource was created using funding from the following sources:
Agency Name Award Title Award Number
National Oceanic and Atmospheric Administration (NOAA), University of Alabama CIROH: Enabling collaboration through data and model sharing with CUAHSI HydroShare NA22NWS4320003 to University of Alabama, subaward A23-0266-S001 to Utah State University
U.S. National Science Foundation HDR Institute: Geospatial Understanding through an Integrative Discovery Environment 2118329

How to Cite

Nassar, A., D. Tarboton, F. Baig, A. Patel, J. Cunningham, H. Salehabadi (2026). NextGen Water Modeling Workflow for Research-Scale Applications, HydroShare, https://doi.org/10.4211/hs.27045581bdea4808a393330f2417379c

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

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

Comments

New Comment

required