NextGen Hydrologic Modeling Workshop: From Forcings to Extreme-Event Evaluation

Authors: Savalan Naser Neisary, Parthkumar Modi, Steven Burian Contact: snaserneisary@crimson.ua.edu Workshop materials on HydroShare: [HydroShare link to be added]

Abstract

This workshop presents a practical, end-to-end approach to working with water data across the United States, from data collection and preparation to analysis, visualization, and prediction, while highlighting selected tools and resources developed through the Cooperative Institute for Research to Operations in Hydrology (CIROH). Participants will be introduced to Python-based tools for accessing and preprocessing hydrological and meteorological data from multiple sources, including observational datasets and forecasting products such as National Water Model streamflow predictions. The workshop will demonstrate how processed data can be used for multiple applications, including analysis, visualization, and large-scale modeling. Examples will include both conventional and machine learning-based approaches, along with methods for evaluating model performance against observations. Designed for a broad audience including researchers, consultants, and operational practitioners, the session will emphasize practical methods and reusable tools that support real-world water applications. By the end of the workshop, participants will have a clearer understanding of how to collect, prepare, analyze, visualize, and use water data for prediction and decision support, while gaining exposure to CIROH’s broader ecosystem of open-source tools and resources for operational hydrology.

Learning objectives

1. Retrieve, preprocess, and evaluate AORC and MRMS data against meteorological observations.
2. Run a pretrained LSTM model within NGIAB to predict streamflow for two hydrologically contrasting watersheds using alternative precipitation forcings.
3. Use CSES to visualize and evaluate overall and low-flow streamflow prediction performance, and interpret how performance varies across watersheds, precipitation forcings, and low-flow thresholds.

Prerequisites

• Basic Python and Jupyter Notebooks.
• Basic hydrology (streamflow, precipitation, rainfall–runoff modeling).

Notebooks

Run the notebooks in order. Each one starts with a short description and ends with a link to the next.

Study basin: Sipsey Fork near Grayson, Alabama (USGS gage 02450250, 243 km²; NWM reach 18578829; NextGen segment 486182).

Folder structure

. ├── 01.forcing_prepration.ipynb ├── 02.forcing_evaluation.ipynb ├── 03.model_run.ipynb ├── 04.model_evaluation_teehr.ipynb ├── 05.extreme_events_.ipynb ├── utils/ # Python code used by the notebooks (the notebooks only call it) ├── data/ # ready-made data used by notebooks 2 and 5 └── ngiab_preprocess_output/ # NGIAB inputs and outputs, one folder per gage (created by notebook 1)

utils/

data/

Getting started

Option A: 2i2c JupyterHub (recommended)

1. Log in to the workshop JupyterHub and choose the NGIAB image (quay.io/awiciroh/ngiab-2i2c:v1.3.1).
2. Upload or clone this folder into your home directory.
3. Open 01.forcing_prepration.ipynb and run the cells from top to bottom (Shift + Enter).

Option B: Your own computer with Docker

Anyone with Docker can run the whole workshop. Nothing else needs to be installed: Python, all packages, the NGIAB tools, the NextGen model and TEEHR are already inside the Docker image.

What you need: Docker, an internet connection, and about 13 GB of free disk space for the image plus about 6 GB for the hydrofabric that notebook 1 downloads. On Apple Silicon Macs the image runs under emulation and is slower.

Step 1. Download the workshop files and folders. Download the complete workshop folder from HydroShare ([HydroShare link to be added]) and unzip it. Keep all files and folders together (the five notebooks, utils/ and data/).

Step 2. Install Docker. Install Docker Desktop (Windows or macOS) or Docker Engine (Linux), then start it and wait until it says it is running.

Step 3. Start the workshop. Open a terminal (PowerShell on Windows) inside the workshop folder and run:

macOS / Linux:

bash mkdir -p .ngiab docker run --rm -it --platform linux/amd64 -p 8888:8888 -v "$PWD":/home/jovyan/workshop -v "$PWD/.ngiab":/home/jovyan/.ngiab quay.io/awiciroh/ngiab-2i2c:v1.3.1 jupyter lab --ip 0.0.0.0 --ServerApp.root_dir=/home/jovyan

Windows (PowerShell):

powershell mkdir .ngiab docker run --rm -it --platform linux/amd64 -p 8888:8888 -v "${PWD}:/home/jovyan/workshop" -v "${PWD}/.ngiab:/home/jovyan/.ngiab" quay.io/awiciroh/ngiab-2i2c:v1.3.1 jupyter lab --ip 0.0.0.0 --ServerApp.root_dir=/home/jovyan

The first run downloads the image, which takes a while. When it starts, the terminal prints a link such as http://127.0.0.1:8888/lab?token=.... Open it in your browser, open the workshop folder, and start with notebook 1.

Notes - Keep the terminal open while you work. Press Ctrl + C in it to stop. Your files stay in the workshop folder. - To start again, run the same docker run command. The hydrofabric stays in the hidden .ngiab folder, so it is downloaded only once. - If Docker runs out of memory, increase the memory given to Docker in Docker Desktop (Settings → Resources).

Practical notes

• Restart the kernel before running a notebook (Kernel → Restart Kernel and Clear Outputs of All Cells).
• The online setting (notebooks 1 and 3). It is set in the first settings cell of the notebook.
• online = 'yes': run the steps that download or create the model inputs (hydrofabric download, subsetting, forcings, model configuration). This needs an internet connection and is required the first time you run the workshop for a gage.
• online = 'no': skip those steps and use the files that are already in ngiab_preprocess_output/. Use this only when that folder already has the files for your gage.
• Hydrofabric download: the CONUS hydrofabric is about 1.7 GB to download and about 6 GB after unpacking. It is stored in ~/.ngiab and downloaded only once per machine.
• Model run time: a 2-month run takes a few minutes; long runs (decades) can take 20 minutes or more. On 2i2c, use 3 CPUs (_cpu_count = 3); more can run out of memory.
• Forcing period: the NWM v3.0 retrospective forcing used here ends on 2023-01-31. Do not set a run end date later than that.
• TEEHR data (notebook 4): data_path = 'offline' reuses a saved evaluation; 'online' deletes it and downloads the data again.
• "Connection refused" in TEEHR means its Spark engine stopped, usually from low memory. Shut down other kernels, restart the kernel, and run again.

Workshop resources

More material about this course. Add the links when they are ready.

Our research and tools

Other research and tools from our group that you can review after the workshop. Add one row for each.

Useful links (external tools and data)

How to cite

Please cite this workshop as:

Naser Neisary, S., Modi, P., & Burian, S. (2026). NextGen Hydrologic Modeling Workshop: From Forcings to Extreme-Event Evaluation. HydroShare. https://doi.org/[DOI to be added]

If you use the extreme-event evaluation method, please also cite the SEED paper listed above.

Acknowledgments

This work was funded by the Cooperative Institute for Research to Operations in Hydrology (CIROH). The workshop builds on the CIROH NextGen/NGIAB workshop materials and runs on the CIROH 2i2c JupyterHub.

The workshop materials are archived on HydroShare. DOI: [HydroShare DOI to be added]