[Feature] Add MERIT-Hydro watershed boundaries for ~58k gauges

[CooperBigFoot]

Summary

~58,000 watershed boundary polygons (plus upstream river networks) have been delineated from MERIT-Hydro for the gauges already supported by RivRetrieve. This issue proposes making them accessible directly through the library.

What exists

hydra-shed (a pure-Rust reimplementation of delineator by Matt Heberger) was used to delineate catchments for every gauge station in the RivRetrieve catalog. The ~58k basins correspond to all gauges whose coordinates have more than 3 decimal places of precision and whose outlets fall inside the MERIT-Hydro basin domain. ~565 outlets could not be snapped to the MERIT-Hydro network and are excluded.

Coverage

Country	Gauges delineated
USA	23,841
Canada	7,630
Australia	6,241
France	5,327
Norway	4,541
Brazil	4,579
Poland	1,301
South Africa	1,285
Czech Republic	825
Japan	816
Slovenia	713
Chile	529
Germany (Berlin)	189
Lithuania	95
Portugal	73
Total	~58,000

GeoPackage schema (two layers per file)

Layer	Key columns	Geometry
watersheds	gauge_id, gauge_name, gauge_lat, gauge_lon, snap_lat, snap_lon, snap_dist, area, basin, country, low_res	POLYGON
rivers	gauge_id, comid, uparea, strahler, shreve	LINESTRING

Total data size is ~31 GB across 15 GeoPackage files (USA alone is ~10 GB), so per-country lazy downloading is essential.

Proposed hosting

HuggingFace Datasets at rivretrieve/watersheds — free, programmatic access via huggingface_hub, built-in caching.

Proposed API

from rivretrieve import PortugalFetcher

fetcher = PortugalFetcher()

# Returns a GeoDataFrame with the watershed polygon for gauge "04K/04A"
watershed = fetcher.get_watershed("04K/04A")

# Optionally include the upstream river network
watershed, rivers = fetcher.get_watershed("04K/04A", include_rivers=True)

Implementation outline

1. COUNTRY_CODE class attribute on each fetcher (e.g. PortugalFetcher.COUNTRY_CODE = "portugal"). Fetchers without watershed data (Spain, UK-EA, UK-NRFA) still get the attribute — they produce a clear ValueError listing available countries.

2. get_watershed() concrete method on RiverDataFetcher base class — all fetchers inherit it automatically:

   def get_watershed(self, gauge_id: str, include_rivers: bool = False):
       from . import watersheds  # lazy import
       return watersheds.query_watershed(
           country_code=self.COUNTRY_CODE,
           gauge_id=gauge_id,
           include_rivers=include_rivers,
       )

3. New module rivretrieve/watersheds.py — thin wrapper around huggingface_hub.hf_hub_download and geopandas.read_file. Handles per-country gpkg download, caching, and gauge ID lookup.

4. geopandas as optional dependency:

   # setup.py
   extras_require={
       "geo": ["geopandas>=0.12.0", "huggingface_hub>=0.20.0"],
   }

   pip install rivretrieve[geo]
   

5. Clear error messages for: gauge not found in database, country not covered, geopandas/huggingface_hub not installed.

6. Unit tests with a tiny fixture GeoPackage, mocking hf_hub_download.

7. Docs page docs/watersheds.rst.

Questions for discussion

1. Is the HuggingFace hosting approach acceptable, or would you prefer a different mechanism (e.g. Zenodo, direct S3)?
2. Should COUNTRY_CODE be a required abstract class attribute, or is a softer convention acceptable?
3. Should the rivers layer be exposed at all in v1, or keep it watershed-only?

Credits

• Watershed delineation: hydra-shed (Rust), implementing the algorithm from delineator by Matt Heberger
• Hydrography: MERIT-Hydro (Yamazaki et al., 2019)

[kratzert]

Hi @CooperBigFoot

sorry for my long silence. I discussed your proposal with @thiagovmdon and @simonmoulds the other two maintainers of this library and here is are our thoughts:

The purpose of RivRetrieve is to facilitate and unify access to observational data from different data providers. Your proposal is slightly different: You propose to add utility functions to retrieve basin polygons from a third party (statically compiled) dataset. While it is indeed incredibly useful to have watershed polygons for a given basin, we kind of agreed that this should not be part of RivRetrieve, but might be better as a separate library. We could link this library or dataset as a "community contribution" so to say, but we want to keep the focus of this library to be narrow and well-defined.

There are some other points that led us to this decision:

• Once this is merged into this library, we as the code maintainers have the duty to maintain and fix the code in case something breaks.
• The dataset is derived static but RivRetrieve is expected to grow significantly (e.g. look at the number of open PRs). Every new addition would require to update this dataset, otherwise there is a growing difference between which basins have polygons and which don't. Since we didn't derive the dataset, we would constantly rely on you or someone else to keep this updated, which is not ideal.
• MERIT-Hydro is just one of many hydrofabrics. If we would support snapping stations to hydrofabrics to get watershed polygons, why would we chose MERIT-Hydro over any other dataset. So would this mean we should support all of them?

So to conclude, here are my ideas how we could move forward to still make your valuable contribution accessible:

• You create a tiny library that given a gauge ID from RivRetrieve returns the polygon.
• If no polygon was pre-computed, maybe you can add code to compute the watershed on demand?
• We add a section to the docs and README with useful community contributions, linking to your library.

WDYT?

[CooperBigFoot]

Hi @kratzert, thanks for the thoughtful response — and to @thiagovmdon and @simonmoulds for weighing in. The reasoning makes total sense, especially the point about hydrofabric neutrality and the maintenance burden of a growing station catalog.

I'll go ahead and build this as a standalone PyPI package. The plan is a thin library that takes a RivRetrieve gauge ID + country code, downloads the corresponding GeoPackage from HuggingFace on first use, and returns the watershed polygon (and optionally the river network) as a GeoDataFrame. I'm aiming to have it published by next week.

Two questions:

1. Gauge ID stability — my library keys entirely off the gauge_id values in your cached_site_data/*.csv files. Can I treat those as stable identifiers, or is there any plan to change their format?

2. Linking — how would you prefer to reference the package? A section in the README, a mention in the docs, or something else? Happy to open a PR for that once the library is up.

[CooperBigFoot]

Hey @kratzert, following up on this. I've published the standalone package we discussed:

watershed-retrieve (v1.0.5)

• ~60k MERIT-Hydro delineated basins across 15 countries
• Hosted on R2 CDN (no HuggingFace dependency)
• pip install watershed-retrieve, zero config needed
• Returns GeoDataFrames, optionally with river networks

import watershed_retrieve as wr
gdf = wr.get_watershed("portugal", "04K-04A")

Would love a link from the RivRetrieve README or docs if you think it fits. Happy to adjust the API or add anything that would make it a better companion to RivRetrieve.

[kratzert]

Hi @CooperBigFoot

This looks super cool, if you want, you can also open a PR with a change to the docs and README so that you are listed as contributor on RivRetrieve, in case this means anything to you. Otherwise I can do it in my next update. I'll wait for your reply first

[CooperBigFoot]

Hi @kratzert

The PR is open: #110. Thank you very much for the opportunity to contribute!