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 228.3 KB
Created: Mar 24, 2025 at 4:26 p.m. (UTC)
Last updated: Dec 11, 2025 at 2:47 p.m. (UTC)
Citation: See how to cite this resource
Content types: Single File Content 
Sharing Status: Public
Views: 363
Downloads: 130
+1 Votes: Be the first one to 
 this.
Comments: 1 comment

Abstract

This HydroShare resource delivers a complete, modular workflow for implementing the Next Generation Water 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 for data preparation, model execution, output evaluation (TEEHR), calibration, and analysis
  • 🛠️ Python utility modules for forcing data visualization, HydroFabric exploration, calibration workflows, output aggregation, and TEEHR-based NextGen 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/configurations, and organizes model input/output directories.
NextGen_Run.ipynb Executes the NextGen model and generates cat-files containing hydrologic variables, nex output, and routing NetCDF results.
NextGen_Outputs_Analysis.ipynb Processes outputs, computes basin-mean variables, and generates CSV summaries.
ngen_cal.ipynb Performs automated calibration with SPOTPY using USGS observations and dynamic parameter updates.
NextGen_TEEHR_Evaluation.ipynb Evaluates NextGen simulated streamflow using TEEHR by pairing USGS observations, NWM v3.0 outputs, and NextGen model results; computes performance metrics and generates diagnostics.

🛠️ 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 Utility functions supporting TEEHR-based NextGen evaluation and integration with the NextGen_TEEHR_Evaluation.ipynb workflow.

🚀 Quick Start Guide

💡 Tip: For full evaluation, run in this order: Prepare → Run → Analyze → Evaluate with TEEHR → Calibrate

✔️ Step 1 — Launch the Environment

Open this resource in CIROH 2i2c-JupyterHub to ensure all required NextGen, PyNGIAB, and TEEHR dependencies are available.

✔️ Step 2 — Prepare Inputs

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

✔️ Step 3 — Run NextGen

Execute NextGen_Run.ipynb to generate all 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 like KGE, NSE, MAE
- Visualize performance and diagnostic plots

✔️ Step 6 — Perform Calibration

Use ngen_cal.ipynb to conduct SPOTPY calibration and update model parameters.

👥 Intended Users

This resource is designed 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 improvements, please contact:
Ayman Nassar – ayman.nassar@usu.edu
David Tarboton – david.tarboton@usu.edu

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

How to Cite

Nassar, A., D. Tarboton, F. Baig (2025). NextGen Water Modeling Workflow for Research-Scale Applications, HydroShare, http://www.hydroshare.org/resource/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