AquaScope

Open-source Python toolkit for water data, hydrology, and agricultural water management — with an AI engine that recommends and auto-executes research methodologies.

🌊 Live Demo · Install · Examples · CLI · Features · Docs · Roadmap · Discussions

if AquaScope helps your research.

🌐 Read this in: Français

AquaScope unifies 27 global water-data sources behind one Python schema, then layers a full scientific computing stack on top — from Bulletin 17C flood frequency to FAO-56 crop water requirements — wrapped in an AI engine that scores 26 research methodologies against your dataset and auto-executes 26 analysis pipelines. Validated against the CAMELS benchmark with 1,000+ tests.

✨ What you can do

• 🌊 Pull water data from USGS, FAO AQUASTAT, FAO WaPOR, GEMStat, EU WFD, Copernicus ERA5, France Hub'Eau, Taiwan MOENV/WRA/Civil IoT/DataGov, Japan MLIT, Korea WAMIS, India WRIS, GRDC, CAMELS-CL, OpenMeteo, UN SDG 6, US Water Quality Portal — one unified Python API.
• 📈 Run hydrological analyses — Bulletin 17C flood frequency (GEV / LP3 / Gumbel / non-stationary GEV / EMA), baseflow separation, rating curves, 21 hydrological signatures.
• 🌾 Plan agricultural water — FAO-56 Penman-Monteith ET₀, crop water requirements for 20 crops, 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.
• 📊 Visualise + report — 16 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)

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

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

3. Collect data from any of the 27 sources

from aquascope.collectors import USGSCollector, AquastatCollector, WaPORCollector

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

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 20-command CLI for the most common workflows:

# Collect data
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

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

# AI recommendation + natural-language problem solving
aquascope recommend --parameters DO,BOD5,COD --goal "pollution trend detection"
aquascope solve --problem "Assess flood risk for a 100-year return period"

# Interactive Streamlit dashboard — multipage workspace with 21 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

27 data collectors spanning four regions (highlights below, full list in the docs):

• 🌎 Americas — USGS (streamflow + WQ), NOAA NWPS (US streamflow), Water Quality Portal (400+ agencies), CAMELS-CL (Chile), CAMELS-BR (Brazil)
• 🌍 Europe — EU Water Framework Directive, Copernicus ERA5, France Hub'Eau, Germany PEGELONLINE, UK Environment Agency
• 🌏 Asia-Pacific — Taiwan MOENV / WRA / Civil IoT / DataGov, Japan MLIT, Korea WAMIS, India WRIS
• 🌐 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

• 1,000+ 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 26 methodologies live in the theory guide
• JOSS paper in submission — 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 💻 ⚠️ 📖

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.9.0},
  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 with a version DOI.

📄 License

MIT — see LICENSE.