mrms-usgs-events 0.1.3

Time-series peak extraction, basin delineation, state-level MRMS data download, and Zarr conversion.

Citation

If you use this package in your research, please cite:

🎥 Operational Demonstration of the Python Package in the "USGS MRMS Flood Explorer" Web Application

▶️ Demonstration

The package performs

Peak extraction, basin delineation, mask generation, state-scale MRMS downloads in less than one minute, and Zarr conversion. This fast processing enables state-based operational analyses across the entire United States using real observations.

Although the methodology can continue to be improved, it provides a flexible foundation for future research and collaborations are welcome to expand and refine its capabilities.

Environment Setup & package Installation

(WSL required for Windows users due to GDAL/GRIB dependencies)

1. Install Micromamba

curl -Ls https://micro.mamba.pm/install.sh | bash

source ~/.bashrc

micromamba --version

micromamba info

2. Create and activate environment

micromamba create -n tethys_flood -c conda-forge python=3.11 gdal geopandas libgdal-grib -y

micromamba activate tethys_flood

3. Install the package

python -m pip install --upgrade pip # Upgrade pip

Development mode (code modifications)

pip install -e .

User mode (No code modifications)

python -m pip install mrms-usgs-events # Install the package (Do NOT run if using development mode (-e))

4. Verify installation

gdalinfo --formats | grep -i grib # Verify gdal grib

mrms-usgs --help # Verify installation

Example use for the Texas July 4 2025 event at the Mystic Camp. (Use at least 1 year between start and end)

mrms-usgs run-site 08165500
--start 2023-07-01
--end 2025-07-10
--base-dir data
--overwrite

Create input tsv

mrms-usgs masks build-input --basins-dir "$BASE_DIR/basins_json" --out "$MASK_INPUT" --overwrite

mrms-usgs masks build-state-masks

mrms-usgs masks build-state-masks --sample-grib-gz "$SAMPLE_GRIB" --mask-input "$MASK_INPUT" --out-dir "$STATE_MASK_DIR" --overwrite

Create state basin index

mrms-usgs masks build-state-basin-index --sample-grib-gz "$SAMPLE_GRIB" --mask-input "$MASK_INPUT" --state-mask-dir "$STATE_MASK_DIR" --out-dir "$STATE_INDEX_DIR" --overwrite

Extract historical event information (Run using tmux)

./run_ews_by_state_parallel.sh

Training engine, filter data

mrms-usgs ews fit-predictors
--summary-dir "$BASE_DIR/ews_history"
--out-dir "$BASE_DIR/ews_predictors"

Download state current rainfall (Texas example)

BASE_DIR="/data/repository_code/unified_data" STATE="TEXAS"

mkdir -p "$BASE_DIR/current_rain"

mrms-usgs ews state-rain-current
--state "$STATE"
--state-mask "$BASE_DIR/state_masks/${STATE}_mrms_mask.npz"
--out-npz "$BASE_DIR/current_rain/${STATE}_current_rain.npz"
--base-dir "$BASE_DIR"
--hours-back 12
--workers 6

Run state alerts (Texas Example)

mrms-usgs ews run-state
--state "$STATE"
--recent-rain-npz "$BASE_DIR/current_rain/${STATE}_current_rain.npz"
--state-basin-index "$BASE_DIR/state_basin_index/${STATE}_state_basin_index.npz"
--predictor-dir "$BASE_DIR/ews_predictors"
--out-dir "$BASE_DIR/ews_alerts/${STATE}"

Data directory with subfolders created following this structure

data/

├── _mrms_cache/ # Temporary cache of downloaded MRMS .grib2 files to avoid re-downloading

├── basins_json/ # Watershed boundaries (GeoJSON) for each USGS station (used to mask rainfall)

├── events/ # Detected hydrologic events (CSV files with peaks, volumes, and timing)

├── logs/ # Execution logs for debugging and tracking pipeline progress

├── rain_zarr/ # Processed rainfall data stored in Zarr format (spatial + temporal arrays)

├── site_meta/ # Metadata for each USGS station (location, name, timezone, etc.)

└── stage_parquet/ # Time series of water level (stage) data from USGS in Parquet format

Acknowledgements

This material is based upon work supported by the U.S. National Science Foundation under Grant No. TI-2303756 and the Tethys Geoscience Foundation.