stephanie-iris/mmc-watershed-data

Purpose and Entry Points

MMC Watershed Data is a Python 3.11+ rainfall-collection and analysis package for Moores Mill Creek stations in Auburn and Opelika, Alabama. Its primary entry point is the mmc CLI, implemented through src/mmc_watershed_data/__main__.py and src/mmc_watershed_data/cli.py. A separate local Streamlit entry point is src/mmc_watershed_data/dashboard.py. The reproducible publication entry point is reports/mmc-rainfall-report.qmd.

Orchestrated Collection Workflow

src/mmc_watershed_data/workflow.py coordinates a date-bounded run across configured stations: fetch each source, preserve evidence, validate/transform records, and persist outputs. src/mmc_watershed_data/config.py supplies operational settings and station/source configuration; src/mmc_watershed_data/stations.py represents and selects the station set. Failures are station-scoped, allowing other stations to complete.

Source-Specific API Adapters

A source boundary isolates incompatible public APIs:

• src/mmc_watershed_data/auburn.py calls LI-COR’s timeseries endpoint and converts epoch-millisecond readings into the project’s UTC-6 display representation while retaining rainfall as RainIn.

• src/mmc_watershed_data/opelika.py calls ThorArchive’s interval endpoint and converts cumulative RainToday values to interval RainIn; negative deltas are treated as gauge resets.

• src/mmc_watershed_data/api.py provides the shared HTTP/API interaction layer.

Neither public source requires credentials.

Evidence, Validation, and Persistence Boundary

The canonical processing boundary is API response → raw JSON evidence → Pydantic validation → processed CSV. src/mmc_watershed_data/models.py defines structured data contracts, and src/mmc_watershed_data/validation.py enforces source payload and record validity before data become analytical outputs. src/mmc_watershed_data/storage.py owns run-specific raw JSON/raw CSV and processed CSV layout under generated data/raw/... and data/processed/....

Analysis and Event Semantics

src/mmc_watershed_data/analysis.py operates on processed interval observations. It derives rainfall events from positive RainIn observations, grouping nearby observations using the documented one-hour tolerance, and produces event duration, total precipitation, and participating-station summaries. This layer should consume processed CSV/schema-compatible records rather than live API payloads.

Interactive Dashboard and Geospatial Context

src/mmc_watershed_data/dashboard.py is a Streamlit UI that can trigger collection or load saved processed datasets, display station rainfall charts, and present event analysis. src/mmc_watershed_data/geospatial.py loads station and watershed geometries for OpenStreetMap-based views. Its immutable local spatial inputs are assets/geospatial/stations/auburn_stations.kmz, assets/geospatial/stations/opelika_stations.kmz, and assets/geospatial/watershed/mmc_boundary.kmz.

Reporting and Runtime Boundaries

src/mmc_watershed_data/reporting.py loads the newest matching processed-data collection (or bundled fallback data) and supplies report-ready summaries, maps, and charts to reports/mmc-rainfall-report.qmd. The committed fallback is reports/data/mmc_report_2026-07-01_to_2026-08-01_processed.csv; the rendered artifact is reports/mmc-rainfall-report.pdf. Runtime infrastructure is Python managed by uv; reporting additionally requires Quarto, a configured project Python/Jupyter kernel, and a PDF engine such as TinyTeX. Operational diagnostics are centralized in src/mmc_watershed_data/logging_config.py.