aqua-signal

Track alignment

Track 2 — Data-to-Insight. aqua-signal turns open environmental sensor data into actionable stream-health and One Health insights: a dashboard, trend analysis, and plain-language insight summaries for 10 urban rivers. Its explainable rules engine also speaks to Track 3 — AI-Supported Assessment: transparent, auditable decision support that assists human judgment instead of replacing it.

Inspiration

The OneAquaHealth concept treats urban freshwater ecosystems as a public-health signal: the same rivers people live next to are early-warning indicators of environmental stress that eventually touches human and animal health. The problem is that the underlying data already exists — the USGS runs continuous water-quality monitors on rivers through the middle of American cities and gives the data away for free — but it lives in raw sensor feeds that no resident, journalist, or city analyst will ever open. We wanted to close the last mile: turn those open feeds into a one-glance, honest answer to "how is our river doing, and which way is it heading?"

What it does

aqua-signal is a self-contained dashboard that screens 10 urban rivers across the US — Philadelphia, Trenton, Washington DC, Pittsburgh, Cleveland, Clinton (IA), Atlanta, Portland, Wilmington (DE metro), and Baton Rouge — using live data from the USGS National Water Information System.

For every river it pulls up to 400 days of daily-mean water temperature, dissolved oxygen, pH, and turbidity, then runs an AI-supported assessment engine that flags sites trending toward poor ecological status:

• Threshold rules based on published freshwater criteria (EPA pH 6.5–9.0, dissolved oxygen ≥ 5 mg/L warmwater criterion, temperature and turbidity stress bands).
• Seasonality-free trend detection: the last 30 days are compared against the same calendar window one year earlier, so normal spring-to-autumn warming is never mistaken for degradation. A raw Mann-Kendall test with Sen's slope is shown alongside for context.
• Anomaly detection: a 30-day rolling z-score flags sensor spikes and pollution events (|z| ≥ 2.5), drawn right on the charts.
• Plain-language narratives: every site gets a generated assessment naming exactly which rules fired and the numbers behind them.

Sites are ranked worst-first into a watch list. On our live build, the engine surfaced a consistent signal: urban rivers running 1.3–2.7 °C warmer than the same period last year, with Brandywine Creek topping the watch list on combined warming, dissolved-oxygen decline (-0.78 mg/L YoY), and turbidity rise (+12.9 FNU YoY).

Target users are the people who need the answer but will never open a raw sensor feed: residents who live along these rivers, local journalists, city sustainability and public-health analysts, and citizen-science coordinators. Expected impact: earlier public awareness of degrading urban waterways, a screening layer any city can adopt at zero cost, and a working bridge from federal open data to local One Health decision-making.

The output is a single static HTML file with inline SVG charts — no JavaScript, no server, no dependencies — hosted free on GitHub Pages.

How we built it

Pure Python, zero runtime dependencies (standard library only):

• Data layer (aquasignal/fetch.py) — a client for the USGS NWIS daily-values REST API (free, public, no API key) with retry/backoff and a JSON disk cache, so the dashboard rebuilds offline and deterministically. The parser correctly selects the daily-mean statistic from NWIS's min/mean/max series.
• Assessment engine (aquasignal/analysis.py) — the rules+statistics module described above. Every threshold is centralized in one auditable RULES table that a city analyst could tune to local criteria.
• Renderer (aquasignal/render.py) — generates the static dashboard with inline SVG sparklines, status badges, and the watch list.
• Tests — 43 unit tests (stdlib unittest) covering the parser against a real captured USGS API response, every statistical routine, the rules engine, and the renderer. All passing.

Challenges we ran into

Seasonality masquerading as trend. Our first version ran Mann-Kendall over a 180-day window and every single river fired "temperature rising, oxygen declining" — because spring turns to autumn everywhere. We replaced rule-firing with year-over-year comparison of matched calendar windows, which is both more honest and far more discriminating.

NWIS returns three series per parameter (daily min/mean/max); naive parsing interleaves them into garbage. The parser now selects the mean statistic explicitly, with tests against a captured real payload.

Urban monitors are patchy. Several candidate sites (Trinity River at Dallas, Connecticut River) report instantaneous values but no daily-value record; we verified sensor availability site-by-site and curated 10 urban rivers with genuine continuous records.

Accomplishments that we're proud of

• A fully working pipeline from raw public API to deployed dashboard, with every number on the page traceable to a rule and a dataset.
• An assessment engine that is honest about what it is: transparent screening heuristics, explicitly not regulatory determinations, with limitations documented on the dashboard itself.
• 43 passing tests and zero dependencies — the whole thing runs offline from a clone in under a minute.

What we learned

Open water data is abundant but the interpretation layer is the scarce part — and the simplest defensible statistics (year-over-year matched windows, rolling z-scores) often beat fancier models for screening tasks, especially when the audience needs to verify the reasoning.

How aqua-signal maps to the judging criteria

• Impact & OneAquaHealth mission — direct monitoring of urban freshwater ecosystem health as an early-warning signal for community well-being, on rivers running through 10 US cities; free for any community to reuse.
• Innovation & creativity — seasonality-free year-over-year screening is a deliberately simple, defensible alternative to black-box ML; the zero-dependency static architecture makes the result reproducible by anyone, anywhere.
• Architecture — clean fetch → analyze → render pipeline in dependency-free Python; 43 passing tests including a real captured USGS API fixture; deterministic offline rebuilds from the committed data cache.
• UX — one glance gives the answer: worst-first watch list, status badges, inline SVG charts, and generated plain-language narratives naming every rule that fired. No JavaScript; accessible in any browser or straight from disk.
• Scale — the same pipeline runs on any of the ~2,000 USGS continuous water-quality monitors; thresholds live in one tunable RULES table; scheduled rebuilds with status-change alerting are the documented next step.

What's next for aqua-signal

• Expand from 10 curated sites to all ~2,000 USGS continuous water-quality monitors, with automatic site discovery by HUC/city.
• Add EU data (EEA Waterbase / Copernicus) for cross-Atlantic comparison under a shared OneAquaHealth framing.
• Plug a local LLM over the assessment engine's structured output to draft per-site briefings — with the deterministic engine as the factual grounding layer.
• Alerting: scheduled rebuilds that file a GitHub issue when a site's status class changes.

Links

• Live dashboard: https://ntoledo319.github.io/aqua-signal/
• Source code (MIT, docs included): https://github.com/ntoledo319/aqua-signal
• Demo video (3:20): linked above

Built with Python (standard library only), the USGS NWIS Water Services API, and GitHub Pages. This project was built with AI coding assistance (disclosed in the README); all assessment logic is deterministic and test-covered.

Built With

• data-visualization
• environmental-monitoring
• one-health
• open-data
• python
• usgs
• water-quality