This HydroShare resource accompanies the HydroLearn module "Understanding Flash Floods Through Storm Tracking." It provides interactive Jupyter notebooks, the ATRACKCS storm-tracking framework, supporting datasets, a worked example report, and installation scripts to complete the learning activities.

The case study is the June 20-22, 2024 northwest Iowa flash flood, an MCS-driven event that produced new peaks of record at ten USGS streamgages.

Resource Contents

Storm tracking (Activity 1)

• ATRACKCS/ - Source code for the ATRACKCS object-based storm-tracking framework.
• 01_Storm_Investigation_ATRACKCS_Iowa2024.ipynb - Interactive notebook: identify and characterize the MCS that produced the flood.
• cpt_convert.py and dict_trackv1.py - Python helpers to render a publication-quality IR colormap.

Flash flood analysis (Activity 2)

• 01_Find_Gauges_Iowa_2024.ipynb - Step 1: find USGS streamgages in the affected basins, filter to small basins suitable for flash flood analysis, check 15 minute data availability, save the focus gauge list.
• 02_Hydrograph_Analysis_Iowa_2024.ipynb - Step 2: download 15 minute discharge, plot hydrographs, isolate event windows, compute flash flood metrics (time to peak, rate of rise, unit-area peak, Richards-Baker Flashiness Index), overlay rainfall on streamflow, plot peak propagation, compare flashy headwater vs integrated outlet.

Supporting datasets

• DATA_RESOURCES/ - Auxiliary datasets and plotting resources for Activity 1.
• DATA_RESOURCES/track_iowa.gpkg - ATRACKCS storm track polygon and attributes for the June 20-21, 2024 MCS.
• DATA_RESOURCES/focus_gauges_iowa_2024.csv - Output of Activity 2, Step 1.
• DATA_RESOURCES/event_metrics.csv - Output of Activity 2, Step 2.
• DATA_RESOURCES/iv_15min/ - Cached USGS NWIS 15 minute discharge for the eight focus gauges.
• data/ofr20261066.pdf - USGS Open-File Report 2026-1066 (Marti and O'Shea, 2026) used as the reference for the event.

Worked example report (solution key)

• solution/example_report.docx - A polished post-event report a learner could submit, in Word format so it can be edited or graded.
• solution/FF_analysis_results - Folder containing the results and plots from the Flash Flood analysis (Activity 2, step 1 and 2)
• solution/Outputs_StormTracking - Folder containing the results and plots from the Storm Tracking analysis (Activity 1)
• solution_Storm_Investigation_ATRACKCS_Iowa2024.ipynb - Notebook with the solution for the Storm Tracking analysis (Activity 1). To use this notebook move it to the main directory.

Installation scripts

• install_atrackcs_hydroshare.sh - Installs ATRACKCS on the CUAHSI JupyterHub server.
• install_atrackcs_local.sh - Installs ATRACKCS in a local Conda environment.

Users may complete the activities on the CUAHSI JupyterHub server or on their own computer. Instructions for both options are provided below.

Setup instructions for CUAHSI JupyterHub server

CUAHSI maintains a HydroShare-linked JupyterHub server on which you can run these notebooks. To use it:

1. Make sure you have a HydroShare user account and join the CUAHSI Cloud Computing group in HydroShare.

2. Log into HydroShare, click the "Open with" button at the top of this resource's landing page, and select "CUAHSI JupyterHub."

3. Agree to the terms of use if prompted, then click "Sign in with HydroShare" and "Authorize" to allow CUAHSI JupyterHub to interact with your HydroShare account.

4. Select "Python v3.11.10 - JupyterLab Interface" in the server options, then click start.

5. After the content is copied (this can take a few minutes), you will see the resource files in the /content/ directory. Proceed to install the ATRACKCS environment.

Install the ATRACKCS environment on CUAHSI JupyterHub

1. Click the [+] button in the upper right of JupyterLab.
2. Click Terminal under Other.
3. Navigate to the working folder:

cd ~/downloads/cae34af8808645c38af89aeb343ff3a7/data/contents

You can confirm the contents with ls.

1. Run the installation script:

bash install_atrackcs_hydroshare.sh

The script will find the ATRACKCS/ folder, create or update the atrackcs Conda environment from atrackcs_env.yml, install ATRACKCS, install ipykernel, and register the environment as a Jupyter kernel called ATRACKCS.

1. When the script finishes (a few minutes), return to JupyterLab.

Run Activity 1 (storm tracking)

Open 01_Storm_Investigation_ATRACKCS_Iowa2024.ipynb. Select the kernel:

Kernel > Change Kernel > ATRACKCS

Run the cells to identify and characterize the MCS that drove the June 2024 flood.

Run Activity 2 (flash flood analysis)

Open the notebooks in notebooks/ in this order:

1. 01_Find_Gauges_Iowa_2024.ipynb (gauge selection).
2. 02_Hydrograph_Analysis_Iowa_2024.ipynb (hydrograph analysis).

These notebooks depend on pandas, numpy, matplotlib, and requests only. The default CUAHSI Python kernel already has these, so the ATRACKCS kernel is not required for Activity 2. Either kernel works.

Build the deliverable

After running both activities, open solution/example_report.docx (Word) to see the expected structure of the final post-event report. Either edit that file or start from docs/learning_activity_overview.md which lists the report sections and the discussion questions.

Setup instructions to run the notebooks locally

The ATRACKCS source code and example notebooks included in this resource can be installed automatically using the provided installation script.

Prerequisites

• Anaconda or Miniconda installed.
• JupyterLab, Jupyter Notebook, VS Code, or another Python interpreter.

Installation

1. Download and extract this HydroShare resource.
2. Open a terminal and navigate to the ATRACKCS directory:

cd ATRACKCS

1. Run the installation script:

bash install_atrackcs_local.sh

The script will create (or update) the atrackcs Conda environment and install all required dependencies.

Activate the environment

conda activate atrackcs

Verify the installation

python -c "import atrackcs; print('ATRACKCS installed successfully')"

Run the notebooks

Open your preferred development environment (JupyterLab, Jupyter Notebook, VS Code, etc.) and select the atrackcs Conda environment as the Python interpreter. The notebooks included in this resource should now run without additional configuration.

For Activity 2 only, you do not need the ATRACKCS environment. A minimal environment with pandas, numpy, matplotlib, and requests is sufficient:

pip install pandas numpy matplotlib requests

Recommended workflow

1. Read the learning activity overview in docs/learning_activity_overview.md.
2. Run Activity 1 to characterize the MCSs (01_Storm_Investigation_ATRACKCS_Iowa2024.ipynb, ATRACKCS kernel).
3. Run Activity 2, Step 1 to select the USGS gauges (02_Find_Gauges_Iowa_2024.ipynb).
4. Run Activity 2, Step 2 to compute the flash flood metrics (03_Hydrograph_Analysis_Iowa_2024.ipynb).
5. Write the final post-event report following the structure in docs/learning_activity_overview.md. The worked example in solution/example_report.docx is provided as a reference.

License

Creative Commons Attribution 4.0 International (CC-BY 4.0). Free to share and adapt with attribution.

Suggested citation

Robledo, V., Kaba, D.R., Abdelkader, M. (2026). Hydrometeorological Analysis of Flash Floods with the ATRACKCS Object-Based Storm Tracking Algorithm. HydroShare resource for the HydroLearn module Understanding Flash Floods Through Storm Tracking. CIROH.

Acknowledgment

Funding for this project was provided by the National Oceanic and Atmospheric Administration (NOAA), awarded to the Cooperative Institute for Research to Operations in Hydrology (CIROH) through the NOAA Cooperative Agreement with The University of Alabama, NA22NWS4320003. Vanessa Robledo was supported by a NASA FINESST grant 80NSSC25K0649.