Metadata-Version: 2.4
Name: mrms-usgs-events
Version: 0.1.2
Summary: Pipeline for downloading USGS site data, extracting events, and generating MRMS RadarOnly Zarr datasets.
Author-email: Gonzalo Forero <gonzaloforero57@gmail.com>, Jacob Johnson <jjohnson@aquaveo.com>
License: Apache-2.0
Project-URL: Repository, https://github.com/GonzaloAlbertoForeroBuitrago/mrms_usgs_events
Keywords: usgs,mrms,hydrology,geoscience,zarr,data-pipeline
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9
Requires-Dist: pandas
Requires-Dist: xarray
Requires-Dist: zarr
Requires-Dist: requests
Requires-Dist: pyarrow
Requires-Dist: Hydro-Event-Detector
Requires-Dist: geopandas
Requires-Dist: orjson
Dynamic: license-file

## Citation

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

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19378061.svg)](https://doi.org/10.5281/zenodo.19378061)

## 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 mrms_usgs_events -c conda-forge python=3.11 gdal geopandas libgdal-grib -y

micromamba activate mrms_usgs_events

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.
