Metadata-Version: 2.4
Name: aihydro-watershed
Version: 0.4.2
Summary: Watershed delineation + characterization — global pour-point delineation (NLDI + MERIT-Hydro), geomorphics, TWI, and watershed-scale hydrological signatures
Author-email: Mohammad Galib <mgalib@purdue.edu>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/AI-Hydro/aihydro-watershed
Project-URL: Documentation, https://github.com/AI-Hydro/AI-Hydro/wiki
Project-URL: Repository, https://github.com/AI-Hydro/aihydro-watershed
Project-URL: Issues, https://github.com/AI-Hydro/aihydro-watershed/issues
Keywords: hydrology,watershed,delineation,MERIT-Hydro,NLDI,geomorphology,signatures,TWI,CAMELS,agentic
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aihydro-core[contracts]<0.3,>=0.2.11
Requires-Dist: aihydro-data<0.3,>=0.2.5
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: geopandas>=0.13.0
Requires-Dist: shapely>=2.0.0
Requires-Dist: pyproj>=3.6.0
Requires-Dist: affine>=2.4.0
Requires-Dist: requests>=2.31.0
Provides-Extra: delineation
Requires-Dist: rioxarray>=0.15.0; extra == "delineation"
Requires-Dist: xarray>=2023.0.0; extra == "delineation"
Requires-Dist: rasterio>=1.3.0; extra == "delineation"
Requires-Dist: pysheds>=0.3.0; extra == "delineation"
Requires-Dist: pyflwdir>=0.5.11; extra == "delineation"
Requires-Dist: scipy>=1.11.0; extra == "delineation"
Requires-Dist: pynhd>=0.16.0; extra == "delineation"
Requires-Dist: pygeohydro>=0.16.0; extra == "delineation"
Requires-Dist: py3dep>=0.15.0; extra == "delineation"
Requires-Dist: planetary-computer>=1.0.0; extra == "delineation"
Requires-Dist: pystac-client>=0.7.0; extra == "delineation"
Requires-Dist: odc-stac>=0.3.0; extra == "delineation"
Requires-Dist: earthengine-api>=0.1.390; extra == "delineation"
Provides-Extra: delineation-full
Requires-Dist: aihydro-watershed[delineation]; extra == "delineation-full"
Provides-Extra: analysis
Requires-Dist: rioxarray>=0.15.0; extra == "analysis"
Requires-Dist: xarray>=2023.0.0; extra == "analysis"
Requires-Dist: rasterio>=1.3.0; extra == "analysis"
Requires-Dist: py3dep>=0.15.0; extra == "analysis"
Requires-Dist: scipy>=1.11.0; extra == "analysis"
Provides-Extra: analysis-legacy
Requires-Dist: aihydro-watershed[analysis]; extra == "analysis-legacy"
Requires-Dist: xrspatial>=0.3.0; extra == "analysis-legacy"
Provides-Extra: all
Requires-Dist: aihydro-watershed[analysis,delineation]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: import-linter>=2.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# aihydro-watershed

<p align="center">
  <a href="https://pypi.org/project/aihydro-watershed/"><img src="https://img.shields.io/pypi/v/aihydro-watershed?color=3775a9&label=PyPI" alt="PyPI" /></a>
  &nbsp;
  <a href="https://doi.org/10.5281/zenodo.20823440"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.20823440.svg" alt="DOI" /></a>
  &nbsp;
  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-green" alt="License" /></a>
</p>

**Watershed delineation + characterization for any point on Earth — as a standalone package.**

Delineate a watershed from a USGS gauge or any global lat/lon pour point, then
characterize it (geomorphics, topographic wetness index, terrain/runoff,
watershed-scale hydrological signatures) — without installing the full AI-Hydro
MCP hydrology stack.

Part of the [AI-Hydro](https://github.com/AI-Hydro) ecosystem. Carved out of
`aihydro-tools` in Wave A of the [ecosystem roadmap](../docs/ECOSYSTEM_ROADMAP.md).

## Install

```bash
# Delineation (fast tier: cloud DEM + pysheds + MERIT-Hydro/pyflwdir)
pip install "aihydro-watershed[delineation]"

# Characterization + signatures
pip install "aihydro-watershed[analysis]"

# Everything
pip install "aihydro-watershed[all]"
```

On Python 3.13, the `analysis` extra omits `xrspatial` (no wheel); use
`analysis-legacy` on Python 3.10–3.12 if you need TWI via xarray-spatial.

## Quick start

```python
from aihydro_watershed.delineation.router import delineate_from_point

# CONUS pour point — uses NLDI automatically
result = delineate_from_point(40.7128, -74.0060, method="auto")
print(result.data["area_km2"])          # 1234.5
print(result.data["method_used"])       # "nldi_comid"

# Global pour point (Rhine at Cologne) — falls back to fast DEM tier
result = delineate_from_point(50.932, 6.970, method="auto")
print(result.data["area_km2"])

# Expected drainage area known? Pass it to improve COMID selection
result = delineate_from_point(39.27, -77.54, expected_area_km2=25_000)

# Road culvert, catchment ~1 km2 (CONUS): USGS 3DEP 10 m + embankment notch
result = delineate_from_point(40.2497, -86.3877, method="small_catchment")
print(result.data["area_km2"], result.data["quality_flags"])
```

Results are typed `HydroResult` (from `aihydro-core`) — provenance-stamped with
tool path, version, parameters, and data sources.

### Command line (offline)

One console script, `aihydro-watershed`, runs the offline slice of the package: the
CAMELS-style signatures from a daily streamflow CSV you already hold. It makes no
network request and never asks for precipitation (so `runoff_ratio` and
`stream_elas` are null). Delineation needs DEM/NLDI/MERIT services and stays in the
Python API; the CLI takes the polygon it produced as a GeoJSON file.

```bash
aihydro-watershed signatures --flow-csv q.csv --area-km2 250 --geojson basin.geojson
# CSV columns default to `date` and `q_cms` (m3/s); override with --date-col / --flow-col.
# Negative discharge is refused; missing-data codes go in --na-values (default -999,-9999).
# The JSON has a `cli` block: missing/duplicate rows, absent days, warnings (also on stderr).
```

## What's inside

| Subpackage | Capability |
|---|---|
| `delineation` | Global pour-point / gauge delineation. Tiers: NLDI (CONUS NHD-indexed), MERIT-Basins hybrid (default outside CONUS: vector assembly of unit catchments + raster refinement of the terminal catchment), MERIT-Hydro/pyflwdir (local flowdir cache, Earth Engine). Auto-routing chooses the best available tier. |
| `merit` | MERIT-Hydro / MERIT-Basins data management: per-region vectors and rasters pinned by SHA-256, map layers, region presets. |
| `characterize` | Geomorphic parameters (28 indices), watershed attributes, topographic wetness index. |
| `terrain` | Curve number (TR-55, AMC II), event runoff (SCS-CN), RUSLE erosion. SSURGO soil attributes in CONUS (recorded hydrologic group and erodibility Kw via gNATSGO + Soil Data Access), POLARIS/SoilGrids elsewhere. |
| `signatures` | Baseflow index (Lyne-Hollick, Ladson 2013 recipe as used by CAMELS), flow-duration curve, flood frequency (Gumbel/GEV), drought indices (SPI, SPEI, Palmer). |

The flood-inundation suite is **not** part of this package.

## Delineation tiers

```
1. nldi        — USGS NLDI NHD-indexed basin (CONUS only, < 1 s)
2. merit_hybrid (alias merit_basins) — MERIT-Basins unit catchments assembled by
                 upstream traversal; only the terminal unit catchment is refined on
                 a small raster window. DEFAULT global tier (auto outside CONUS);
                 force it anywhere, including CONUS, with method="merit_hybrid".
3. merit_gee   — MERIT-Hydro flowdir from Google Earth Engine (small-basin fallback)
3. local_merit — MERIT-Hydro flowdir from local cache (global, offline after download)
4. fast        — pysheds on cloud-fetched DEM tile (global, no MERIT cache needed)
5. small_catchment (alias 3dep): CONUS catchments under ~5 km2 (road
                 culverts). USGS 3DEP 10 m bare-earth DEM, a notch carved
                 through the road embankment at the pour point, snap to the
                 largest drainage within 40 m
auto           — tries tiers in order of accuracy; degrades gracefully on failures
                 (in CONUS, expected_area_km2 < 5 sends it to small_catchment first)
```

### MERIT-Basins hybrid: data, licence, versions

- **Data.** Per-megabasin files published for Heberger's `delineator` 2.2.x
  (`basins##.db`, `rivers##.db`, optional `flowdir##.tif` / `accum##.tif`,
  plus the 52.9 MB level-2 index `megabasins.db`), pinned by SHA-256 and size in
  `aihydro_watershed/merit/delineator_data_manifest.json`. A file whose digest does
  not match is deleted before install and, if already on disk, refused
  (`MERIT_ASSET_INTEGRITY_FAILED`); nothing falls back to unverified data.
  Vectors are staged on demand under the tiered policy (`AIHYDRO_MERIT_AUTO_STAGE=never|tiered|always`,
  `merit_auto_stage_max_gb`, default 2 GB). Rasters are optional and staged explicitly. Everything lives under
  `$AIHYDRO_HOME/merit` (default `~/.aihydro/merit`); `AIHYDRO_MERIT_DIR` overrides.
- **First-call cost.** The first delineation in a region downloads that region's `basins##.db` + `rivers##.db` (SHA-256
  verified) under the tiered policy (the default, one constant: `DEFAULT_AUTO_STAGE_POLICY` in `merit/merit_manager.py`;
  set it to `"never"` for confirm-first, or use `AIHYDRO_MERIT_AUTO_STAGE=never`). From the pinned manifest, over all 60 regions:
  **min 14 MB (region 54), median 530 MB, max 2015 MB (region 56, Australia, above the 2 GB auto-stage limit so it needs an
  explicit `merit_ensure_basins_region`)**; North America (71-78, 81-86): min 60 MB, median 502 MB, max 916 MB. The very first call
  ever also fetches the 52.9 MB level-2 index. Staged rasters are optional and explicit (flowdir + accum per region: min 12 MB,
  median 696 MB, max 1931 MB). Staging needs 2x the pending bytes free on disk. Every call that downloads says so: quality flag
  `MERIT_AUTO_STAGED`, and `data_provenance.downloaded` lists `{name, bytes, url, sha256}`, with `data_provenance.acquisition_policy`.
  A file that fails verification is deleted and not retried automatically for 24 h (`MERIT_ASSET_INTEGRITY_FAILED`, with the
  observed digest); interrupted downloads resume with an HTTP Range request when the server supports it.
- **Licence.** Non-commercial and share-alike. mghydro.com releases the files under CC BY-NC-SA 4.0; MERIT Hydro is
  CC BY-NC 4.0 or ODbL 1.0; the sources disagree on the exact variant. The result carries the
  licence (`data_provenance.share_alike: true`) and the SHA-256 of every file used (`data_provenance`).
  Legacy shapefile layouts (`shp/merit_catchments`, `shp/merit_rivers`) are not read; `basins_region_cache` says so.
- **Version consistency.** The vectors are MERIT-Basins v0.7/v1.0_bugfix1. With the regional
  rasters staged, snapping and refinement use the same provider's files. Without them the tier uses
  Earth Engine (MERIT Hydro v1.0.1) and flags `MERIT_VERSION_MIX`; `data_provenance.version_consistency`
  records which dataset each step used. Refinement via Earth Engine is limited to a 40 km window and is
  skipped (flagged) beyond it.

Why a separate small-catchment tier: NLDI returns whole NHDPlus catchments
(and the router rejects anything under 1 km2), MERIT-Hydro is 90 m, and the
`fast` tier reads Copernicus GLO-30, a surface model that keeps canopy and
buildings. A road embankment also acts as a dam on any DEM unless it is
notched. On 67 Indiana culverts (INDOT SPR-4926) the small-catchment tier
matched engineer-computed drainage areas within a factor of 2 at 76 % of
sites (median ratio 1.01, Spearman 0.80). Results under 0.05 km2 were always
roadside-ditch snaps and are flagged `LIKELY_DITCH_SNAP`.

USGS StreamStats is not used as a tier: the old
`streamstats.usgs.gov/streamstatsservices` API is retired (404), and the
current `/ss-delineate/v1/delineate/sshydro/{STATE}?lat=&lon=` service does not
snap points onto its stream grid for very small channels.

## Layering

Depends only **downward**:

```
aihydro-core  ←  contract (HydroResult / HydroMeta / ToolError)
aihydro-data  ←  data acquisition (streamflow, DEM, land cover, soil)
     ↑
aihydro-watershed   (this package)
```

The layering contract is enforced offline by `tests/test_layering.py` (AST walk,
zero deps) and by `import-linter` for anyone who installs the `dev` extra.

## Running tests

```bash
# Offline (layering, geometry/router envelopes, and pure signature kernels)
pytest tests/ -m "not live" -q

# Full suite including live API calls (requires network)
pytest tests/ -v

# Parity checks only (Wave A4 gate)
pytest tests/test_parity.py -m live -v
```

The offline suite covers import layering, delineation failure/escalation
envelopes, geometry validity/GeoJSON conversion, and pure hydrologic signature
kernels. Live tests are reserved for NLDI/GEE/STAC/3DEP/API parity checks.

## Status

v0.1.0. Wave A extraction complete (2026-06-21). All five subpackages
(`delineation`, `merit`, `characterize`, `terrain`, `signatures`) are live.
Compatibility shims remain in `ai_hydro/analysis/` and `ai_hydro/data/` of
`aihydro-tools` for one release cycle; see `MIGRATION.md`.

## Migration from `aihydro-tools`

If you previously imported from `ai_hydro.analysis.*` or `ai_hydro.data.*`,
see [MIGRATION.md](MIGRATION.md) for the one-line import changes.

## Citation

If you use `aihydro-watershed` in your research, please cite:

```bibtex
@software{aihydro_watershed_2026,
  title   = {aihydro-watershed: Global Watershed Delineation and Characterization},
  author  = {Galib, Mohammad and Merwade, Venkatesh},
  year    = {2026},
  version = {0.1.0},
  doi     = {10.5281/zenodo.20823440},
  url     = {https://doi.org/10.5281/zenodo.20823440}
}
```
