AquaScope Hydrology

Explore river records and run reproducible water analyses in your browser.

Find a gauge, inspect its usable record, and export data, figures and methods. No installation; core Explorer workflows need no API key.

🌊 Live Explorer Demo - Runs in Your Browser, No Install Required · Install · Examples · CLI · Features · Docs · Roadmap · Discussions

if AquaScope helps your research.

🌐 Read this in: Français

AquaScope unifies 37 global water-data sources behind one Python schema, then layers a full scientific computing stack on top — from flood-frequency methods to FAO-56 crop water requirements — wrapped in an AI engine that scores 27 research methodologies against your dataset and auto-executes 26 analysis pipelines. Regression checks include the CAMELS benchmark with 3,100+ tests across the project. The daily benchmark inputs are synthetic; flood benchmarks also use observed USGS annual peaks. See validation scope for comparators and limitations.

🌍 Try it without installing anything

Open AquaScope Explorer. Start with one task:

• Find river data: search a gauge, inspect its actual available period and units, then download CSV.
• Explore a worked analysis: open a recorded study, read its limits and reproduce its plan at another gauge.
• Analyse my table: use a sample CSV, check the inferred columns, then replace it with your own data.

Catalog coverage varies by agency and variable. A station on the map is not a guarantee of accessible observations or a sufficiently long record. Explorer shows the period it actually analyzes; modelled discharge is distinguished from gauge observations.

Study guides you from a question through a plan you approve to a report and export bundle: Word, Excel, figures, notebook, findings and study YAML. Core studies run without an API key. Optional model setup is available when you choose to use it. Beyond the design flow, a study can test whether the flood is changing, calibrate GR4J at the gauge and run "what if" rainfall and warming scenarios, or carry seven CMIP6 models through it to 2050 (advanced studies).

The open archive supplies station catalogs and mirrored observations; inspect observation refresh status separately from catalog health. Exports also work with R, QGIS, DuckDB and Julia. See the executable Python quickstart and validation scope before using a flood result in a decision.

Prefer an assistant? pip install "aquascope[mcp]" then claude mcp add aquascope -- aquascope mcp gives Claude (or any MCP client) find_stations, get_timeseries, analyze_station and flood_frequency over the same catalog and methods (docs).

🧑‍🔬 Run a study on your machine

pip install "aquascope[studio,basins]"   # the Word report, workbook, figures, notebook and the catchment step
aquascope studio

That is all. The Studio asks where (a gauge name like Fish River Fort Kent, a station id like USGS-01013500, or lat, lon) and what you want to know ("Is flooding here getting worse?"). Then it asks only what the study still needs, one pick-list question at a time with the reason (a trend question: which period; a design question: which return period), shows the plan, and runs only when you approve it (e edits a step, e.g. s3.return_period=200). The bundle lands in ./studio-<id>/: report.docx, workbook.xlsx, study.ipynb, figures/, findings.json and study.yaml, which re-runs the whole study with aquascope run study.yaml. After the report, ask a follow-up (another gauge, a trend, the flow duration curve) and the bundle is updated.

It needs no key: the playbooks plan and the templates write. If you have one, the Studio asks: paste it (hidden), it is checked with one short request, and the model writes the brief, the plan and the prose, with a $1 spend ceiling. No key yet? Groq's free tier works, and the Studio links you to it. It can remember the key for next time (~/.config/aquascope/keys.json, readable only by you), and a key already in your environment (ANTHROPIC_API_KEY, GROQ_API_KEY, ...) is offered instead. The numbers are the same either way: they come from the tools, and a sentence whose number is in no result is dropped. One line, no questions:

aquascope studio "Is flooding getting worse?" --at USGS-01013500 --provider anthropic --max-usd 1 --yes

On macOS with Homebrew or python.org Python, pip install may refuse ("externally managed environment"); make a virtual environment first: python3 -m venv .venv && source .venv/bin/activate. More in docs/studio.md.

✨ What you can do

• 🌊 Pull water data from USGS, NOAA NWPS, Colorado DWR/CDSS, US Water Quality Portal, England's Environment Agency, France Hub'Eau, Germany PEGELONLINE, Ireland OPW, Greece Hydroscope and OpenHi.net, Poland IMGW-PIB, EU WFD, Taiwan MOENV/WRA/CWA/Civil IoT/DataGov, Japan MLIT, Korea WAMIS, India WRIS, South Africa DWS, Australia BOM, Brazil ANA Hidroweb, CAMELS-CL and CAMELS-BR, GRDC, GEMStat, Copernicus ERA5, OpenMeteo, FAO AQUASTAT, FAO WaPOR and UN SDG 6 — one unified Python API.
• 📈 Run hydrological analyses — flood frequency (GEV / LP3 / Gumbel / non-stationary GEV, with separate EMA routines), baseflow separation, rating curves, 22 hydrological signatures.
• 🌾 Plan agricultural water — FAO-56 Penman-Monteith ET₀, crop water requirements for 26 crops (olive, grape, citrus and winter wheat resolved by variety and canopy), irrigation scheduling, soil water balance with auto-irrigation.
• 🤖 Ask the AI engine — describe your goal in plain English and get a recommended methodology, scored against your dataset profile and auto-executed. LLM enhancement via OpenAI, Groq (free), HuggingFace (free), or local Ollama.
• 🧑‍🔬 Hand a study to the crew — aquascope studio "PROBLEM" --lat --lon: a Consultant, a Scout, a Methodologist, Analysts, an Interpreter, a Critic and an Author over one workspace, the plan shown before it runs, every step gated (a failed gate fails its step, not the study), every answer graded (established, indicative, screening, not established) with findings that point at the result they rest on, a request for the data that would unlock a question instead of a decline, and the bundle (Word, Excel, figures, notebook, findings.json, study.yaml) at the end. Also in the Explorer and over MCP. The advanced studies go past the design flow: change points and a nonstationary flood fit, GR4J with a snow store validated on years it never saw, "what if" scenarios, and CMIP6 change factors through the calibrated model.
• 📊 Visualise + report — 17 plot types, Q-Q / P-P diagnostics, Markdown / HTML reports with embedded figures, threshold alerts (WHO / EPA / EU WFD).
• 🗺️ Spatial hydrology — DEM processing, D8 flow direction, watershed delineation, Strahler ordering.

For the full capability list see docs/features.md.

📊 Why AquaScope

⚡ Install

pip install aquascope              # core — collectors + hydrology
pip install "aquascope[all]"       # everything — ML, viz, spatial, dashboard

Feature-group extras:

pip install "aquascope[ml]"           # sklearn, xgboost, statsmodels
pip install "aquascope[viz]"          # matplotlib, seaborn, folium
pip install "aquascope[scientific]"   # xarray, netcdf4, h5py
pip install "aquascope[interop]"      # xarray + geopandas (collect as_xarray / as_geodataframe)
pip install "aquascope[spatial]"      # rasterio, geopandas, shapely
pip install "aquascope[dashboard]"    # streamlit
pip install "aquascope[forecast]"     # prophet, torch (for LSTM)
pip install "aquascope[studio]"       # matplotlib, openpyxl, python-docx (the Studio's Word, Excel, figures)
pip install "aquascope[basins]"       # pyogrio, geopandas (BasinATLAS catchments, similar basins)

For development:

git clone https://github.com/Rekin226/aquascope.git
cd aquascope
pip install -e ".[all,dev]"

🚀 Examples

1. Flood frequency analysis (Bulletin 17C)

from aquascope.api import flood_analysis

result = flood_analysis(daily_discharge, method="gev", return_periods=[10, 50, 100])
print(result.return_periods)
# {10: 1840.2, 50: 2530.7, 100: 2870.4}
print(result.confidence_intervals)
# {10: (1690.4, 2010.6), 50: (2280.1, 2820.9), 100: (2540.6, 3260.5)}

Switch method to "lp3", "gumbel", "gev_lmoments", or "gpd". Non-stationary GEV (fit_nonstationary_gev) and Bulletin 17C EMA for censored records (expected_moments_algorithm) are available in aquascope.hydrology.flood_frequency.

2. Baseflow separation + hydrological signatures

from aquascope.api import baseflow_analysis, compute_all_signatures

bf  = baseflow_analysis(daily_discharge, method="eckhardt")   # or "lyne_hollick"
sig = compute_all_signatures(daily_discharge)

print(bf.bfi)                  # baseflow index, e.g. 0.42
print(sig.q5, sig.q95)         # high-flow / low-flow exceedances
print(sig.flashiness_index)    # Richards-Baker flashiness index

22 signatures across magnitude, variability, timing, recession, and flashiness — see docs/features.md.

3. Collect data from any of the 37 sources

from aquascope import find_stations
from aquascope.collectors import USGSCollector, AquastatCollector, WaPORCollector

# Which gauges measure discharge around Greater London? (USGS, UK EA, Hub'Eau,
# PEGELONLINE, Ireland OPW, Greece (Hydroscope + OpenHi.net) and Taiwan CWA
# expose station catalogs; more coming)
gauges = find_stations(bbox=(-0.5, 51.3, 0.3, 51.7), variable="discharge")
print(gauges[0].name, gauges[0].url)

usgs = USGSCollector()   # pass api_key=... for reliable access
flow = usgs.collect(days=7, bbox="-77.6,38.7,-76.9,39.1")   # Potomac basin, last week

aquastat = AquastatCollector()
egy_water = aquastat.collect(country_code="EGY", variable_ids=[4263, 4253, 4312])

wapor = WaPORCollector()
et = wapor.collect(
    bbox=(30.5, 29.8, 31.1, 30.2),
    variable="RET",
    start_date="2026-04-01",
    end_date="2026-07-31",
)

Every collector returns records in the same Pydantic schema, so downstream analyses don't care where the data came from. See docs/data_sources.md for the full list.

4. FAO-56 crop water requirements + soil water balance

from datetime import date
from aquascope.agri import (
    penman_monteith_daily,
    crop_water_requirement,
    SoilWaterBalance,
)
from aquascope.agri.water_balance import SoilProperties

# Reference ET (FAO-56 Penman-Monteith) — Cairo, July
eto = penman_monteith_daily(
    t_min=18.0, t_max=32.0, rh_min=40, rh_max=80,
    u2=2.0, rs=22.0, latitude=30.0, elevation=70, doy=180,
)

# Crop water requirement for maize from planting through harvest — eto_series is
# a daily ET₀ pd.Series (build one with penman_monteith_series on a weather DataFrame)
cwr = crop_water_requirement(eto_series, crop="maize", planting_date=date(2026, 4, 1))

# Soil water balance with auto-irrigation triggers — returns a daily DataFrame
soil    = SoilProperties(field_capacity=0.30, wilting_point=0.15, root_depth=1.0)
balance = SoilWaterBalance(soil).auto_irrigate(
    cwr["etc"], precip_series, efficiency=0.7,
)
print(balance["irrigation_mm"].sum())             # total irrigation applied (mm)
print(int(balance["irrigation_trigger"].sum()))   # number of deficit days

Notebook tutorial: agricultural water demand and irrigation scheduling.

5. AI methodology recommender

from aquascope.ai_engine import DatasetProfile, recommend

# Describe your dataset and goal — get ranked, scored methodologies
profile = DatasetProfile(
    parameters=["DO", "BOD5", "COD"],
    n_records=4_500,
    time_span_years=6.0,
    research_goal="detect long-term pollution trends with seasonality",
)
recs = recommend(profile)

for r in recs[:3]:
    print(f"{r.score:5.1f}  {r.methodology.id:<18}  {r.rationale[:46]}…")
#  55.9  trend_analysis      Your dataset includes bod5, cod, do which are…
#  54.6  lstm_forecasting    Your dataset includes bod5, cod, do which are…
#  54.6  arima_forecast      Your dataset includes bod5, cod, do which are…

Then auto-execute the top result with run_pipeline(recs[0].methodology.id, df).

6. Change-point detection + copula dependence

from aquascope.api import detect_changepoints, fit_copula

cps  = detect_changepoints(annual_runoff, method="pettitt")
cop  = fit_copula(rainfall, runoff, family="auto")    # AIC-selects Gaussian/Clayton/Gumbel/Frank
cp   = cps.changepoints[0]
print(cp.timestamp, cp.p_value)
print(cop.family, cop.parameter, cop.aic)

7. Bayesian regression with uncertainty quantification

from aquascope.api import bayesian_regression

# Annual rainfall → runoff with full posterior + convergence diagnostics
posterior = bayesian_regression(X=annual_precip, y=annual_runoff)

print(posterior.posterior_mean)
# {'beta_0': 12.4, 'beta_1': 0.82, 'sigma2': 41.6}

print(posterior.credible_intervals["beta_1"])
# (0.78, 0.86)        ← 95% credible interval on slope

print(posterior.r_hat)
# {'beta_0': 1.00, 'beta_1': 1.00, 'sigma2': 1.00}    ← Gelman–Rubin, converged

print(posterior.dic, posterior.effective_sample_size["beta_1"])
# 124.7  9842.0       ← model fit + effective sample size

Switch to MCMC with degree>1 for polynomial models, or pass prior_precision for informative priors. Conjugate linear, polynomial, and Metropolis-Hastings backends are all available.

💻 CLI

AquaScope ships a 30-command CLI (agri, basins, caravan, gym and playbooks carry subcommands) for the most common workflows:

# Find stations, then collect data
aquascope stations --bbox -0.5,51.3,0.3,51.7 --variable discharge --format geojson
aquascope harvest stations --out archive          # the open gauge catalog (GeoParquet)
aquascope basins at 48.85 2.35                    # the catchment of any point: area, climate, land cover, soils, dams (BasinATLAS)
aquascope basins similar 25.04 121.56             # gauged basins whose catchments look most like this point's (ungauged-site donors)
aquascope basins regionalize 52.29 -3.51          # estimated flow regime of an ungauged point from those donors, with the leave-one-out skill
aquascope assess 51.415 -0.308 --problem flood_risk   # what can be answered here: gauges in reach, catchment, which methods the record supports
aquascope caravan export --source uk_ea --out caravan_gb   # a Caravan-format large-sample dataset from the archive
aquascope gym run --basin uk_ea/013054a3-670e-49ee-afda-e0865a449197   # HydroGym: calibrate GR4J on a real basin as a gym episode
aquascope mcp                                     # serve the same tools to Claude / Cursor over MCP
aquascope ask "100-year flood of the Seine at Paris?"   # the analyst: tools + a cited Markdown report
aquascope ingest agency_export.csv --unit cfs     # any CSV/Excel -> clean daily series + QA report
aquascope collect --source usgs --days 365
aquascope collect --source wapor --bbox 30.5,29.8,31.1,30.2 --variable RET --start-date 2026-04-01

# Hydrological analysis
aquascope hydro --analysis flood-freq --file discharge.csv
aquascope hydro --analysis baseflow --file discharge.csv --method eckhardt -o baseflow.json

# Agriculture planning
aquascope agri plan --crop maize --planting-date 2026-04-01 --lat 30.0 --lon 31.25 -o plan.csv

# AI recommendation + natural-language problem solving
aquascope recommend --parameters DO,BOD5,COD --goal "pollution trend detection" -o recommendations.json
aquascope solve "Design flow for a road crossing, 100-year return period" --lat 51.415 --lon -0.308
aquascope studio                                     # the crew: asks where and what, then brief, plan, run, bundle
aquascope studio "Design flow for a road crossing, 100-year, and how sure can we be" --at "Thames Kingston" --out kingston/
aquascope area-study --bbox=-0.9,51.2,0.3,51.8       # a flood study over every gauge in a box: Q100, flood trends, a regional curve

# Interactive Streamlit dashboard — multipage workspace with 37 live sources,
# smart auto-insights, and fully interactive Plotly charts
aquascope dashboard

# Shell tab-completion
eval "$(aquascope completion bash)"   # add this to ~/.bashrc (or .zshrc / config.fish)

Run aquascope --help for the full command list.

🌍 Data sources at a glance

37 data collectors spanning five regions (highlights below, full list in the docs):

• 🌎 Americas — USGS (streamflow + WQ), NOAA NWPS (US streamflow), Colorado DWR/CDSS, Water Quality Portal (400+ agencies), CAMELS-CL (Chile), CAMELS-BR and ANA Hidroweb (Brazil)
• 🌍 Europe — EU Water Framework Directive, Copernicus ERA5, France Hub'Eau, Germany PEGELONLINE, England's Environment Agency, Ireland OPW, Greece Hydroscope (national archive) and OpenHi.net (live telemetry), Poland IMGW-PIB (daily archive from 1951 and the live network)
• 🌍 Africa — South Africa DWS (verified discharge and water level)
• 🌏 Asia-Pacific — Taiwan MOENV / WRA / CWA / Civil IoT / DataGov, Japan MLIT, Korea WAMIS, India WRIS, Australia BOM
• 🌐 Global — GEMStat (170 countries), UN SDG 6, OpenMeteo, FAO AQUASTAT, FAO WaPOR, GRDC (river discharge)

Full details, endpoints, and API-key requirements: docs/data_sources.md. Want to add your country's water service? See adding a data source.

🧪 Scientifically validated

• 3,100+ tests covering every collector, hydrology method, and pipeline (spatial and ARIMA tests require the optional [all] / [ml] extras)
• CAMELS benchmark — a 10-catchment validation subset of the CAMELS dataset ships with the repo at data/camels_benchmark/ and runs as part of CI
• Every method cited — equations, decision trees, and DOI references for all 27 methodologies live in the theory guide
• JOSS paper in preparation — see paper.md and paper.bib

📚 Documentation

🤝 Contributing

We welcome contributions from the global water and agriculture research community. Highest-impact contributions right now:

• New data source collectors — your country / region
• New research methodologies — expand the AI recommender
• New crop coefficients — extend the FAO Kc table
• Jupyter tutorials and validation studies — compare against HEC-SSP, R packages, etc.

📌 Where to start

📍 Data sources wanted — help us map every country's water data 🌍 — our pinned meta-issue. Want your country in AquaScope? Start here.

New contributor? These good first issues are scoped with clear acceptance criteria — just comment to claim one:

Browse the full issue list or vote on what to build next in Discussions → Ideas.

See CONTRIBUTING.md, the adding a data source guide, and the adding a methodology guide.

🪜 The contributor ladder

We want contributors to grow, not vanish after one PR. There's a clear path: start with a good first issue, then graduate to a good second issue (a bigger self-contained piece that builds on what you learned), and after a few PRs in one area we'll invite you to help triage and review. See CONTRIBUTORS.md for details.

🙌 Contributors

Thanks to these wonderful people who make AquaScope possible (emoji key):

Abdoul Rachid Ouedraogo 💻 📖 🚧	Vaishnavi Desai 🔌	Karthick 💻	sagiB74 ⚠️	Karthik Laishetti 💻 🐛
Adam Jenkins 🔌 💻 ⚠️	Steven Widjaja ⚠️	Sai Raj Kasam 💻	safiashaik04 💻	Navaneeth Sankar 📖 ⚠️
Taran 💻 ⚠️	Ahmed Baruwa 💻 ⚠️	Anthony 💻 ⚠️	James Boardman 💻 ⚠️ 📖 🐛 🚇 🤔	Khyati Tiwari 💻 🔣
PRAKSHAL BHAVINKUMAR BHANDARI 📖	Osheun 💻 ⚠️ 📖	Dipak Chaudhari 💻 ⚠️	Sanchar127 💻 ⚠️	hari 💻 ⚠️
leatke 💻 📖 🔬	Talia Pulsifer 💻 ⚠️	mikemikimike 💻 ⚠️	Jade 💻 ⚠️ 🔣	송은우 💻 ⚠️ 📖
Satya Srujana Pilli 💻 ⚠️	0x 💻	bazinga0027-gif 💻 ⚠️ 📖	Harsh Raj Singhania 💻 ⚠️	Kudala Bharani Kumar Reddy ⚠️ 📖
Berserker-GM 💻 ⚠️	GALABA VAMSI 💻

Your first merged PR puts you on this board, every kind of contribution counts. See CONTRIBUTORS.md.

📜 Citation

If you use AquaScope in your research, please cite:

@software{aquascope2026,
  title   = {AquaScope: Open-Source Water Data Aggregation, Hydrological Analysis, and Agricultural Water Management Toolkit},
  author  = {Ouédraogo, Abdoul Rachid},
  year    = {2026},
  url     = {https://github.com/Rekin226/aquascope},
  version = {0.21.0},
  doi     = {10.5281/zenodo.21903143},
  license = {MIT}
}

Machine-readable metadata lives in CITATION.cff; GitHub's "Cite this repository" button renders it in APA and BibTeX. Every tagged release is archived on Zenodo; 10.5281/zenodo.21903143 is the concept DOI that always resolves to the latest version (v0.20.0 is 10.5281/zenodo.23009178).

📄 License

MIT — see LICENSE.