HydroPlot: rating workshop, dynamic metrics, climate/SPI fixes, mobile UX

docs/architecture.md

@@ -0,0 +1,63 @@
+# HydroPlot Architecture Notes
+
+HydroPlot is organized around five user-facing workflows. New features should land in the workflow where the user decision happens, not in a catch-all tools page.
+
+## Workflows
+
+- **Stations** (`overview`): find a stream gage, inspect station map context, live/current condition checks, and record coverage.
+- **Site Analysis** (`single-analysis`): one selected gage, hydrographs, duration curves, exports, drought indicators, SPI, and baseflow proxy views.
+- **Compare Sites** (`comparisons`): multi-gage overlays, period comparisons, and site relationship analysis.
+- **Reach Analysis** (`reach-analysis`): selected upstream/downstream gage pairs, NHD reach map, gain/loss screening, reach plots, baseflow waterfall, and future groundwater observation support.
+- **Watershed** (`watershed`): broader basin, HUC, land-cover, dam, flowline, and future well/log context.
+
+## Groundwater Source Rules
+
+Groundwater support should be implemented as public-source tiers with explicit eligibility.
+
+1. **USGS groundwater field measurements**
+   - Public monitoring data.
+   - Eligible for time-series screening when enough records exist.
+   - First implementation target.
+
+2. **Washington Ecology EIM groundwater data**
+   - Public Ecology/partner monitoring data when accessed through published search/download/API paths.
+   - Eligible only after schema and public access are verified.
+
+3. **Washington Ecology well logs / well reports**
+   - Public context data, but locations and private-well details can be sensitive or approximate.
+   - Context only unless a record is clearly a monitoring time series with usable public measurements.
+   - Do not expose owner, address, parcel, phone/email, or other private fields.
+
+## Groundwater UI Placement
+
+- Primary: **Reach Analysis**
+  - Button-driven "Find public groundwater data" for the selected reach.
+  - Show monitoring wells separately from context-only well logs.
+  - Map markers must identify source and eligibility.
+  - Trend/correlation summaries only for eligible monitoring time series.
+
+- Secondary: **Watershed**
+  - Basin-scale well/log inventory context.
+  - No reach-level interpretation.
+
+- Later/optional: **Site Analysis**
+  - Single-gage nearby groundwater context if it supports an actual user workflow.
+
+## Data And Performance Rules
+
+- Do not fetch groundwater data automatically on every Streamlit rerun.
+- Cache public-data calls by source, reach bounds, dates, and buffer distance.
+- Normalize provider output into a safe schema before UI rendering.
+- Drop private fields at the data boundary.
+- Label approximate locations and context-only sources in the UI.
+- Avoid claiming calibrated groundwater modeling; use "screening", "proxy", and "observation support".
+
+## Verification Pattern
+
+Each new data source needs:
+
+- Unit tests for normalization.
+- Eligibility tests that prevent context-only records from being analyzed.
+- Fixture/mocked tests for missing values, sparse time series, and private-field removal.
+- One validation case in `docs/cases/` once the workflow produces a useful output.
+

docs/cases/_template/README.md

@@ -0,0 +1,35 @@
+---
+case: <slug>
+title: "<one-line case title>"
+hydroplot_version: "<version or commit>"
+showcases:
+  - <analysis_feature>
+data_source: "<dataset, URL, and access date>"
+runtime_minutes: 0
+created: YYYY-MM-DD
+---
+
+# <Title>
+
+## Scenario
+
+Describe the PNW hydrology question, the reach or gage, and why it matters.
+
+## What This Proves About HydroPlot
+
+- `<feature>`: describe the reusable HydroPlot analysis behavior being validated.
+
+## How To Run
+
+```powershell
+python scripts/run_case_study.py docs/cases/<case>/case.yml
+```
+
+## Outputs
+
+- `outputs/<file>.csv`: describe table.
+- `outputs/<file>.png`: describe figure.
+
+## Validation
+
+List the published report, agency method, or expected range used for PASS/FLAG checks.

docs/cases/_template/case.yml

@@ -0,0 +1,8 @@
+case: template
+site_ids: []
+start_date: "2000-01-01"
+end_date: "2025-01-01"
+analyses:
+  - baseflow
+  - signatures
+validation: []

docs/cases/pnw_baseflow_signatures/README.md

@@ -0,0 +1,28 @@
+# PNW Baseflow And Hydrologic Signatures
+
+## Scenario
+
+This case validates HydroPlot's baseflow and hydrologic signature workflow on a Pacific Northwest daily streamflow record. It focuses on method agreement, plausible BFI range, flow-duration behavior, and flashiness.
+
+## What This Proves About HydroPlot
+
+- `lyne_hollick_filter`: bounded multi-pass recursive filter.
+- `eckhardt_filter`: independent two-parameter filter.
+- `compute_hydrologic_signatures`: compact basin-behavior summary.
+- `validate_range`: explicit PASS/FLAG result instead of informal notebook checks.
+
+## How To Run
+
+```powershell
+python -m scripts docs/cases/pnw_baseflow_signatures/case.yml
+```
+
+## Outputs
+
+- `outputs/baseflow_components.csv`
+- `outputs/signatures.csv`
+- `outputs/validation_summary.csv`
+
+## Validation
+
+BFI and flashiness are screened against method-comparison ranges. These checks are not a substitute for a basin-specific groundwater study.

docs/cases/pnw_baseflow_signatures/case.yml

@@ -0,0 +1,12 @@
+case: pnw_baseflow_signatures
+site_ids:
+  - "12422500"
+start_date: "2000-01-01"
+end_date: "2025-01-01"
+analyses:
+  - baseflow
+  - signatures
+validation:
+  - metric: baseflow_index_lh
+    lower: 0.20
+    upper: 0.95

docs/cases/spokane_reach_gain_loss/README.md

@@ -0,0 +1,28 @@
+# Spokane Reach Gain/Loss Screening
+
+## Scenario
+
+This case validates HydroPlot's reach-scale gain/loss screening on a Spokane River reach where upstream/downstream discharge differences are important for dry-season interpretation.
+
+## What This Proves About HydroPlot
+
+- `build_reach_chain`: selected gages can be represented in upstream-to-downstream order.
+- `derive_adjacent_reaches`: a river continuum can be assessed reach-by-reach.
+- `summarize_reach_gain_loss`: paired upstream/downstream gain-loss calculation.
+- Low-flow median gain/loss: dry-window reach gain/loss signal.
+- `classify_thermal_sensitivity`: screening context for shade, low flow, and losing/gaining reach conditions.
+
+## How To Run
+
+```powershell
+python -m scripts docs/cases/spokane_reach_gain_loss/case.yml
+```
+
+## Outputs
+
+- `outputs/reach_gain_loss.csv`
+- `outputs/validation_summary.csv`
+
+## Validation
+
+This is a screening workflow. It does not claim to replace seepage runs, groundwater modeling, TTools, Shade, Heat Source, QUAL2K, or QUAL2Kw.

docs/cases/spokane_reach_gain_loss/case.yml

@@ -0,0 +1,11 @@
+case: spokane_reach_gain_loss
+site_ids:
+  upstream: "12422500"
+  downstream: "12424000"
+start_date: "2015-07-01"
+end_date: "2015-09-30"
+reach_km: 20
+analyses:
+  - reach_gain_loss
+  - thermal_context
+validation: []