Make routing the sole public hydrology API surface (#3528)

README.md

@@ -310,35 +310,19 @@ Built-in Numba JIT and CUDA projection kernels bypass pyproj for per-pixel coord
 
 | Name | Description | Source | NumPy xr.DataArray | Dask xr.DataArray | CuPy GPU xr.DataArray | Dask GPU xr.DataArray |
 |:----------:|:------------|:------:|:----------------------:|:--------------------:|:-------------------:|:------:|
-| [Flow Direction (D8)](xrspatial/hydro/flow_direction_d8.py) | Computes D8 flow direction from each cell toward the steepest downhill neighbor | O'Callaghan & Mark 1984 | ✅ | 🔼 | 🔼 | 🔼 |
-| [Flow Direction (Dinf)](xrspatial/hydro/flow_direction_dinf.py) | Computes D-infinity flow direction as a continuous angle toward the steepest downslope facet | Tarboton 1997 | ✅ | 🔼 | 🔼 | 🔼 |
-| [Flow Direction (MFD)](xrspatial/hydro/flow_direction_mfd.py) | Partitions flow to all downslope neighbors with an adaptive exponent (Qin et al. 2007) | Qin et al. 2007 | ✅ | 🔼 | 🔼 | 🔼 |
-| [Flow Accumulation (D8)](xrspatial/hydro/flow_accumulation_d8.py) | Counts upstream cells draining through each cell in a D8 flow direction grid | Jenson & Domingue 1988 | ✅ | 🔼 | 🔼 | 🔼 |
-| [Flow Accumulation (Dinf)](xrspatial/hydro/flow_accumulation_dinf.py) | Accumulates upstream area by splitting flow proportionally between two neighbors (Tarboton 1997) | Tarboton 1997 | ✅ | 🔼 | 🔼 | 🔼 |
-| [Flow Accumulation (MFD)](xrspatial/hydro/flow_accumulation_mfd.py) | Accumulates upstream area through all MFD flow paths weighted by directional fractions | Qin et al. 2007 | ✅ | 🔼 | 🔼 | 🔼 |
-| [Flow Length (D8)](xrspatial/hydro/flow_length_d8.py) | Computes D8 flow path length from each cell to outlet (downstream) or from divide (upstream) | Standard (D8 tracing) | 🔼 | 🔼 | 🔼 | 🔼 |
-| [Flow Length (Dinf)](xrspatial/hydro/flow_length_dinf.py) | Proportion-weighted flow path length using D-inf angle decomposition (downstream or upstream) | Tarboton 1997 | 🔼 | 🔼 | 🔼 | 🔼 |
-| [Flow Length (MFD)](xrspatial/hydro/flow_length_mfd.py) | Proportion-weighted flow path length using MFD fractions (downstream or upstream) | Qin et al. 2007 | 🔼 | 🔼 | 🔼 | 🔼 |
-| [Fill (D8)](xrspatial/hydro/fill_d8.py) | Fills depressions in a DEM using Planchon-Darboux iterative flooding | Planchon & Darboux 2002 | ✅ | 🔼 | 🔼 | 🔼 |
-| [Sink (D8)](xrspatial/hydro/sink_d8.py) | Identifies and labels depression cells in a D8 flow direction grid | Standard (D8 tracing) | ✅ | 🔼 | 🔼 | 🔼 |
-| [Watershed (D8)](xrspatial/hydro/watershed_d8.py) | Labels each cell with the pour point it drains to via D8 flow direction | Standard (D8 tracing) | ✅ | 🔼 | 🔼 | 🔼 |
-| [Watershed (Dinf)](xrspatial/hydro/watershed_dinf.py) | Labels each cell with the pour point it drains to via D-infinity flow direction | Tarboton 1997 | ✅ | 🔼 | 🔼 | 🔼 |
-| [Watershed (MFD)](xrspatial/hydro/watershed_mfd.py) | Labels each cell with the pour point it drains to via MFD fractions | Qin et al. 2007 | ✅ | 🔼 | 🔼 | 🔼 |
-| [Basins](xrspatial/hydro/watershed_d8.py) | Delineates drainage basins by labeling each cell with its outlet ID | Standard (D8 tracing) | ✅ | 🔼 | 🔼 | 🔼 |
-| [Stream Order (D8)](xrspatial/hydro/stream_order_d8.py) | Assigns Strahler or Shreve stream order to cells in a drainage network | Strahler 1957, Shreve 1966 | ✅ | 🔼 | 🔼 | 🔼 |
-| [Stream Order (Dinf)](xrspatial/hydro/stream_order_dinf.py) | Strahler/Shreve stream ordering on D-infinity flow direction grids | Tarboton 1997 | ✅ | 🔼 | 🔼 | 🔼 |
-| [Stream Order (MFD)](xrspatial/hydro/stream_order_mfd.py) | Strahler/Shreve stream ordering on MFD fraction grids | Freeman 1991 | ✅ | 🔼 | 🔼 | 🔼 |
-| [Stream Link (D8)](xrspatial/hydro/stream_link_d8.py) | Assigns unique IDs to each stream segment between junctions | Standard | ✅ | 🔼 | 🔼 | 🔼 |
-| [Stream Link (Dinf)](xrspatial/hydro/stream_link_dinf.py) | Stream link segmentation on D-infinity flow direction grids | Tarboton 1997 | ✅ | 🔼 | 🔼 | 🔼 |
-| [Stream Link (MFD)](xrspatial/hydro/stream_link_mfd.py) | Stream link segmentation on MFD fraction grids | Freeman 1991 | ✅ | 🔼 | 🔼 | 🔼 |
-| [Snap Pour Point](xrspatial/hydro/snap_pour_point_d8.py) | Snaps pour points to the highest-accumulation cell within a search radius | Custom | ✅ | 🔼 | 🔼 | 🔼 |
-| [Flow Path (D8)](xrspatial/hydro/flow_path_d8.py) | Traces downstream flow paths from start points through a D8 direction grid | Standard (D8 tracing) | ✅ | 🔼 | 🔼 | 🔼 |
-| [Flow Path (Dinf)](xrspatial/hydro/flow_path_dinf.py) | Traces downstream flow paths using D-infinity dominant neighbor | Tarboton 1997 | 🔼 | 🔼 | 🔼 | 🔼 |
-| [Flow Path (MFD)](xrspatial/hydro/flow_path_mfd.py) | Traces downstream flow paths through MFD fraction-weighted neighbors | Qin et al. 2007 | 🔼 | 🔼 | 🔼 | 🔼 |
-| [HAND (D8)](xrspatial/hydro/hand_d8.py) | Computes Height Above Nearest Drainage by tracing D8 flow to the nearest stream cell | Nobre et al. 2011 | ✅ | 🔼 | 🔼 | 🔼 |
-| [HAND (Dinf)](xrspatial/hydro/hand_dinf.py) | Computes Height Above Nearest Drainage using D-infinity flow direction | Nobre et al. 2011 | ✅ | 🔼 | 🔼 | 🔼 |
-| [HAND (MFD)](xrspatial/hydro/hand_mfd.py) | Computes Height Above Nearest Drainage using MFD fractions | Nobre et al. 2011 | ✅ | 🔼 | 🔼 | 🔼 |
-| [TWI](xrspatial/hydro/twi_d8.py) | Topographic Wetness Index: ln(specific catchment area / tan(slope)) | Beven & Kirkby 1979 | ✅ | 🔼 | 🔼 | 🔼 |
+| [Flow Direction](xrspatial/hydro/flow_direction_d8.py) | Direction of steepest descent out of each cell (D8 · Dinf · MFD via `routing=`) | O'Callaghan & Mark 1984; Tarboton 1997; Qin et al. 2007 | ✅ | 🔼 | 🔼 | 🔼 |
+| [Flow Accumulation](xrspatial/hydro/flow_accumulation_d8.py) | Upstream cells or area draining through each cell (D8 · Dinf · MFD via `routing=`) | Jenson & Domingue 1988; Tarboton 1997; Qin et al. 2007 | ✅ | 🔼 | 🔼 | 🔼 |
+| [Flow Length](xrspatial/hydro/flow_length_d8.py) | Flow path length to the outlet or from the divide (D8 · Dinf · MFD via `routing=`) | Tarboton 1997; Qin et al. 2007 | 🔼 | 🔼 | 🔼 | 🔼 |
+| [Flow Path](xrspatial/hydro/flow_path_d8.py) | Traces downstream flow paths from start points (D8 · Dinf · MFD via `routing=`) | Tarboton 1997; Qin et al. 2007 | 🔼 | 🔼 | 🔼 | 🔼 |
+| [Watershed](xrspatial/hydro/watershed_d8.py) | Labels each cell with the pour point it drains to (D8 · Dinf · MFD via `routing=`) | Tarboton 1997; Qin et al. 2007 | ✅ | 🔼 | 🔼 | 🔼 |
+| [Stream Link](xrspatial/hydro/stream_link_d8.py) | Assigns unique IDs to stream segments above a threshold (D8 · Dinf · MFD via `routing=`) | Tarboton 1997; Freeman 1991 | ✅ | 🔼 | 🔼 | 🔼 |
+| [Stream Order](xrspatial/hydro/stream_order_d8.py) | Strahler or Shreve stream ordering of the network (D8 · Dinf · MFD via `routing=`) | Strahler 1957, Shreve 1966 | ✅ | 🔼 | 🔼 | 🔼 |
+| [HAND](xrspatial/hydro/hand_d8.py) | Height Above Nearest Drainage (D8 · Dinf · MFD via `routing=`) | Nobre et al. 2011 | ✅ | 🔼 | 🔼 | 🔼 |
+| [Fill](xrspatial/hydro/fill_d8.py) | Fills depressions in a DEM using Planchon-Darboux iterative flooding (D8) | Planchon & Darboux 2002 | ✅ | 🔼 | 🔼 | 🔼 |
+| [Sink](xrspatial/hydro/sink_d8.py) | Identifies and labels depression cells (D8) | Standard (D8 tracing) | ✅ | 🔼 | 🔼 | 🔼 |
+| [Basin](xrspatial/hydro/basin_d8.py) | Labels each cell with the outlet of the basin it drains to (D8) | Standard (D8 tracing) | ✅ | 🔼 | 🔼 | 🔼 |
+| [Snap Pour Point](xrspatial/hydro/snap_pour_point_d8.py) | Snaps pour points to the highest-accumulation cell within a search radius (D8) | Custom | ✅ | 🔼 | 🔼 | 🔼 |
+| [TWI](xrspatial/hydro/twi_d8.py) | Topographic Wetness Index: ln(specific catchment area / tan(slope)) (D8) | Beven & Kirkby 1979 | ✅ | 🔼 | 🔼 | 🔼 |
 
 -----------
 

docs/source/reference/hydrology.rst

@@ -11,206 +11,160 @@ Hydrology
    masked out), fill or interpolate them first, or expect disconnected
    drainage networks.
 
-Flow Direction (D8)
-===================
-.. autosummary::
-    :toctree: _autosummary
+Each family exposes a single public function. The routing algorithm
+(``'d8'``, ``'dinf'``, or ``'mfd'``) is chosen with the ``routing`` keyword,
+which defaults to ``'d8'``::
 
-    xrspatial.hydro.flow_direction_d8.flow_direction_d8
+    import xrspatial
+    fdir = xrspatial.flow_direction(dem, routing='dinf')
+    acc = xrspatial.flow_accumulation(fdir, routing='dinf')
 
-Flow Direction (D-infinity)
-===========================
-.. autosummary::
-    :toctree: _autosummary
+The wrapper dispatches to the per-routing implementations listed under each
+family. Those implementations live in ``xrspatial.hydro`` and carry the full
+parameter list and algorithm references.
 
-    xrspatial.hydro.flow_direction_dinf.flow_direction_dinf
+Flow Direction
+==============
+.. py:function:: xrspatial.flow_direction(agg, *, routing='d8', **kwargs)
 
-Flow Direction (MFD)
-====================
-.. autosummary::
-    :toctree: _autosummary
+   Direction of steepest descent out of each cell.  ``routing`` selects
+   ``'d8'``, ``'dinf'``, or ``'mfd'`` (default ``'d8'``).
 
-    xrspatial.hydro.flow_direction_mfd.flow_direction_mfd
+Routing variants:
 
-Flow Accumulation (D8)
-======================
 .. autosummary::
     :toctree: _autosummary
 
-    xrspatial.hydro.flow_accumulation_d8.flow_accumulation_d8
+    xrspatial.hydro.flow_direction_d8.flow_direction_d8
+    xrspatial.hydro.flow_direction_dinf.flow_direction_dinf
+    xrspatial.hydro.flow_direction_mfd.flow_direction_mfd
 
-Flow Accumulation (D-infinity)
-===============================
-.. autosummary::
-    :toctree: _autosummary
+Flow Accumulation
+=================
+.. py:function:: xrspatial.flow_accumulation(flow_dir, *, routing='d8', **kwargs)
 
-    xrspatial.hydro.flow_accumulation_dinf.flow_accumulation_dinf
+   Upstream cells or area draining through each cell.  ``routing`` selects
+   ``'d8'``, ``'dinf'``, or ``'mfd'`` (default ``'d8'``).
+
+Routing variants:
 
-Flow Accumulation (MFD)
-=======================
 .. autosummary::
     :toctree: _autosummary
 
+    xrspatial.hydro.flow_accumulation_d8.flow_accumulation_d8
+    xrspatial.hydro.flow_accumulation_dinf.flow_accumulation_dinf
     xrspatial.hydro.flow_accumulation_mfd.flow_accumulation_mfd
 
-Flow Length (D8)
-================
-.. autosummary::
-    :toctree: _autosummary
-
-    xrspatial.hydro.flow_length_d8.flow_length_d8
+Flow Length
+===========
+.. py:function:: xrspatial.flow_length(flow_dir, *, routing='d8', **kwargs)
 
-Flow Length (D-infinity)
-========================
-.. autosummary::
-    :toctree: _autosummary
+   Distance along the flow path to the outlet or from the divide.
+   ``routing`` selects ``'d8'``, ``'dinf'``, or ``'mfd'`` (default ``'d8'``).
 
-    xrspatial.hydro.flow_length_dinf.flow_length_dinf
+Routing variants:
 
-Flow Length (MFD)
-=================
 .. autosummary::
     :toctree: _autosummary
 
+    xrspatial.hydro.flow_length_d8.flow_length_d8
+    xrspatial.hydro.flow_length_dinf.flow_length_dinf
     xrspatial.hydro.flow_length_mfd.flow_length_mfd
 
-Flow Path (D8)
-==============
-.. autosummary::
-    :toctree: _autosummary
-
-    xrspatial.hydro.flow_path_d8.flow_path_d8
+Flow Path
+=========
+.. py:function:: xrspatial.flow_path(flow_dir, start_points, *, routing='d8', **kwargs)
 
-Flow Path (D-infinity)
-======================
-.. autosummary::
-    :toctree: _autosummary
+   Trace downstream flow paths from a set of start points.  ``routing``
+   selects ``'d8'``, ``'dinf'``, or ``'mfd'`` (default ``'d8'``).
 
-    xrspatial.hydro.flow_path_dinf.flow_path_dinf
+Routing variants:
 
-Flow Path (MFD)
-===============
 .. autosummary::
     :toctree: _autosummary
 
+    xrspatial.hydro.flow_path_d8.flow_path_d8
+    xrspatial.hydro.flow_path_dinf.flow_path_dinf
     xrspatial.hydro.flow_path_mfd.flow_path_mfd
 
-Fill
-====
-.. autosummary::
-    :toctree: _autosummary
+Watershed
+=========
+.. py:function:: xrspatial.watershed(flow_dir, pour_points, *, routing='d8', **kwargs)
 
-    xrspatial.hydro.fill_d8.fill_d8
+   Label each cell with the pour point it drains to.  ``routing`` selects
+   ``'d8'``, ``'dinf'``, or ``'mfd'`` (default ``'d8'``).
 
-Sink
-====
-.. autosummary::
-    :toctree: _autosummary
+Routing variants:
 
-    xrspatial.hydro.sink_d8.sink_d8
-
-Basin
-=====
-.. autosummary::
-    :toctree: _autosummary
-
-    xrspatial.hydro.basin_d8.basin_d8
-
-Watershed (D8)
-==============
 .. autosummary::
     :toctree: _autosummary
 
     xrspatial.hydro.watershed_d8.watershed_d8
-    xrspatial.hydro.watershed_d8.basins_d8
-
-Watershed (D-infinity)
-======================
-.. autosummary::
-    :toctree: _autosummary
-
     xrspatial.hydro.watershed_dinf.watershed_dinf
-
-Watershed (MFD)
-===============
-.. autosummary::
-    :toctree: _autosummary
-
     xrspatial.hydro.watershed_mfd.watershed_mfd
+    xrspatial.hydro.watershed_d8.basins_d8
 
-Snap Pour Point
-===============
-.. autosummary::
-    :toctree: _autosummary
-
-    xrspatial.hydro.snap_pour_point_d8.snap_pour_point_d8
+Stream Link
+===========
+.. py:function:: xrspatial.stream_link(flow_dir, flow_accum, *, routing='d8', threshold=100, **kwargs)
 
-Stream Link (D8)
-================
-.. autosummary::
-    :toctree: _autosummary
+   Assign unique IDs to stream segments above a flow-accumulation threshold.
+   ``routing`` selects ``'d8'``, ``'dinf'``, or ``'mfd'`` (default ``'d8'``).
 
-    xrspatial.hydro.stream_link_d8.stream_link_d8
+Routing variants:
 
-Stream Link (D-infinity)
-========================
 .. autosummary::
     :toctree: _autosummary
 
+    xrspatial.hydro.stream_link_d8.stream_link_d8
     xrspatial.hydro.stream_link_dinf.stream_link_dinf
-
-Stream Link (MFD)
-=================
-.. autosummary::
-    :toctree: _autosummary
-
     xrspatial.hydro.stream_link_mfd.stream_link_mfd
 
-Stream Order (D8)
-=================
-.. autosummary::
-    :toctree: _autosummary
+Stream Order
+============
+.. py:function:: xrspatial.stream_order(flow_dir, flow_accum, *, routing='d8', ordering='strahler', threshold=100, **kwargs)
 
-    xrspatial.hydro.stream_order_d8.stream_order_d8
+   Strahler or Shreve stream ordering of the stream network.  ``routing``
+   selects ``'d8'``, ``'dinf'``, or ``'mfd'`` (default ``'d8'``); ``ordering``
+   selects ``'strahler'`` or ``'shreve'``.
 
-Stream Order (D-infinity)
-=========================
-.. autosummary::
-    :toctree: _autosummary
-
-    xrspatial.hydro.stream_order_dinf.stream_order_dinf
+Routing variants:
 
-Stream Order (MFD)
-==================
 .. autosummary::
     :toctree: _autosummary
 
+    xrspatial.hydro.stream_order_d8.stream_order_d8
+    xrspatial.hydro.stream_order_dinf.stream_order_dinf
     xrspatial.hydro.stream_order_mfd.stream_order_mfd
 
-Height Above Nearest Drainage (D8)
-===================================
-.. autosummary::
-    :toctree: _autosummary
+Height Above Nearest Drainage (HAND)
+====================================
+.. py:function:: xrspatial.hand(flow_dir, flow_accum, elevation, *, routing='d8', threshold=100, **kwargs)
 
-    xrspatial.hydro.hand_d8.hand_d8
+   Height above the nearest drainage.  ``routing`` selects ``'d8'``,
+   ``'dinf'``, or ``'mfd'`` (default ``'d8'``).
+
+Routing variants:
 
-Height Above Nearest Drainage (D-infinity)
-==========================================
 .. autosummary::
     :toctree: _autosummary
 
+    xrspatial.hydro.hand_d8.hand_d8
     xrspatial.hydro.hand_dinf.hand_dinf
+    xrspatial.hydro.hand_mfd.hand_mfd
 
-Height Above Nearest Drainage (MFD)
-====================================
-.. autosummary::
-    :toctree: _autosummary
+D8-only functions
+=================
 
-    xrspatial.hydro.hand_mfd.hand_mfd
+These families currently implement D8 routing only. They take the same
+``routing`` keyword for forward compatibility, where ``'d8'`` is the only
+accepted value.
 
-Topographic Wetness Index (TWI)
-===============================
 .. autosummary::
     :toctree: _autosummary
 
+    xrspatial.hydro.fill_d8.fill_d8
+    xrspatial.hydro.sink_d8.sink_d8
+    xrspatial.hydro.basin_d8.basin_d8
+    xrspatial.hydro.snap_pour_point_d8.snap_pour_point_d8
     xrspatial.hydro.twi_d8.twi_d8