Hydrology#

Warning

NaN cells act as impassable barriers in all hydrology functions. Flow cannot cross them. If your DEM has NaN holes (e.g. water bodies masked out), fill or interpolate them first, or expect disconnected drainage networks.

Each family exposes a single public function. The routing algorithm ('d8', 'dinf', or 'mfd') is chosen with the routing keyword, which defaults to 'd8':

import xrspatial
fdir = xrspatial.flow_direction(dem, routing='dinf')
acc = xrspatial.flow_accumulation(fdir, routing='dinf')

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.

Flow Direction#

xrspatial.flow_direction(agg, *, routing='d8', **kwargs)#

Direction of steepest descent out of each cell. routing selects 'd8', 'dinf', or 'mfd' (default 'd8').

Routing variants:

xrspatial.hydro.flow_direction_d8.flow_direction_d8(agg)

Compute D8 flow direction for each cell.

xrspatial.hydro.flow_direction_dinf.flow_direction_dinf(agg)

Compute D-infinity flow direction for each cell.

xrspatial.hydro.flow_direction_mfd.flow_direction_mfd(agg)

Compute multiple flow direction fractions for each cell.

Flow Accumulation#

xrspatial.flow_accumulation(flow_dir, *, routing='d8', **kwargs)#

Upstream cells or area draining through each cell. routing selects 'd8', 'dinf', or 'mfd' (default 'd8').

Routing variants:

xrspatial.hydro.flow_accumulation_d8.flow_accumulation_d8(...)

Compute flow accumulation from a D8 flow direction grid.

xrspatial.hydro.flow_accumulation_dinf.flow_accumulation_dinf(...)

Compute flow accumulation from a D-infinity flow direction grid.

xrspatial.hydro.flow_accumulation_mfd.flow_accumulation_mfd(...)

Compute flow accumulation from an MFD flow direction grid.

Flow Length#

xrspatial.flow_length(flow_dir, *, routing='d8', **kwargs)#

Distance along the flow path to the outlet or from the divide. routing selects 'd8', 'dinf', or 'mfd' (default 'd8').

Routing variants:

xrspatial.hydro.flow_length_d8.flow_length_d8(...)

Compute D8 flow length from a flow direction grid.

xrspatial.hydro.flow_length_dinf.flow_length_dinf(...)

Compute flow length from a D-infinity flow direction grid.

xrspatial.hydro.flow_length_mfd.flow_length_mfd(...)

Compute flow length from an MFD flow direction grid.

Flow Path#

xrspatial.flow_path(flow_dir, start_points, *, routing='d8', **kwargs)#

Trace downstream flow paths from a set of start points. routing selects 'd8', 'dinf', or 'mfd' (default 'd8').

Routing variants:

xrspatial.hydro.flow_path_d8.flow_path_d8(...)

Trace downstream flow paths from start points through a D8 grid.

xrspatial.hydro.flow_path_dinf.flow_path_dinf(...)

Trace downstream flow paths using D-infinity dominant neighbor.

xrspatial.hydro.flow_path_mfd.flow_path_mfd(...)

Trace downstream flow paths using MFD dominant neighbor.

Watershed#

xrspatial.watershed(flow_dir, pour_points, *, routing='d8', **kwargs)#

Label each cell with the pour point it drains to. routing selects 'd8', 'dinf', or 'mfd' (default 'd8').

Routing variants:

xrspatial.hydro.watershed_d8.watershed_d8(...)

Label each cell with the pour point it drains to.

xrspatial.hydro.watershed_dinf.watershed_dinf(...)

Label each cell with the pour point it drains to (D-inf).

xrspatial.hydro.watershed_mfd.watershed_mfd(...)

Label each cell with the pour point it drains to (MFD).

xrspatial.hydro.watershed_d8.basins_d8(flow_dir)

Backward-compatible wrapper; use basin() instead.

Stream Order#

xrspatial.stream_order(flow_dir, flow_accum, *, routing='d8', ordering='strahler', threshold=100, **kwargs)#

Strahler or Shreve stream ordering of the stream network. routing selects 'd8', 'dinf', or 'mfd' (default 'd8'); ordering selects 'strahler' or 'shreve'.

Routing variants:

xrspatial.hydro.stream_order_d8.stream_order_d8(...)

Compute stream order from D8 flow direction and accumulation grids.

xrspatial.hydro.stream_order_dinf.stream_order_dinf(...)

Compute stream order from D-infinity flow direction and accumulation.

xrspatial.hydro.stream_order_mfd.stream_order_mfd(...)

Compute stream order from MFD flow direction and accumulation grids.

Height Above Nearest Drainage (HAND)#

xrspatial.hand(flow_dir, flow_accum, elevation, *, routing='d8', threshold=100, **kwargs)#

Height above the nearest drainage. routing selects 'd8', 'dinf', or 'mfd' (default 'd8').

Routing variants:

xrspatial.hydro.hand_d8.hand_d8(flow_dir, ...)

Compute Height Above Nearest Drainage (HAND).

xrspatial.hydro.hand_dinf.hand_dinf(...[, ...])

Compute HAND using D-infinity flow direction.

xrspatial.hydro.hand_mfd.hand_mfd(...[, ...])

Compute HAND using MFD flow direction.

D8-only functions#

These families currently implement D8 routing only. They take the same routing keyword for forward compatibility, where 'd8' is the only accepted value.

xrspatial.hydro.fill_d8.fill_d8(dem[, ...])

Fill depressions in a DEM using Planchon-Darboux iterative flooding.

xrspatial.hydro.sink_d8.sink_d8(flow_dir[, name])

Identify and label depression cells in a D8 flow direction grid.

xrspatial.hydro.basin_d8.basin_d8(flow_dir)

Delineate drainage basins: every cell labeled with its outlet ID.

xrspatial.hydro.snap_pour_point_d8.snap_pour_point_d8(...)

Snap pour points to the highest-accumulation cell within a radius.

xrspatial.hydro.twi_d8.twi_d8(flow_accum, ...)

Compute the Topographic Wetness Index.