Summary
The public MFD functions document a specific input contract: each cell's 8 fraction bands lie in [0, 1] and sum to either 1.0 (flow) or 0.0 (pit/flat/sink), with all-NaN bands at edges and nodata cells. The functions don't enforce any of that. They check the array is shape (8, H, W) and nothing else about the values.
So a caller can pass negative fractions, per-cell sums above 1.0, or a cell where some of the 8 bands are NaN and the rest are finite, and the function will happily run accumulation, length, order, or link math on it and hand back hydrology that looks fine but isn't. These are public APIs. Bad input should raise early with a clear message instead of producing quietly wrong output.
Affected functions
The public fraction-grid consumers in xrspatial/hydro:
flow_accumulation_mfdflow_length_mfdstream_order_mfdstream_link_mfdflow_path_mfdhand_mfdwatershed_mfd
Proposal
Add fraction-value validation that runs right after the existing (8, H, W) shape check in each function. Check three things:
- No negative fractions.
- Each cell's band sum is 1.0 (flow) or 0.0 (pit/flat/sink), within a small tolerance.
- NaN bands are all-or-nothing per cell: either all 8 directions are NaN (edge/nodata) or none are. Reject the partially-NaN case.
Raise ValueError on any violation. Keep the documented semantics (sum == 1.0 or 0.0). The tolerance needs to be loose enough that valid grids out of flow_direction_mfd still pass.
Scope
Fraction value and topology only (negative, sum, NaN consistency). Secondary-raster shape validation, cyclic-graph detection, and dask-laziness work are separate issues.
Summary
The public MFD functions document a specific input contract: each cell's 8 fraction bands lie in [0, 1] and sum to either 1.0 (flow) or 0.0 (pit/flat/sink), with all-NaN bands at edges and nodata cells. The functions don't enforce any of that. They check the array is shape (8, H, W) and nothing else about the values.
So a caller can pass negative fractions, per-cell sums above 1.0, or a cell where some of the 8 bands are NaN and the rest are finite, and the function will happily run accumulation, length, order, or link math on it and hand back hydrology that looks fine but isn't. These are public APIs. Bad input should raise early with a clear message instead of producing quietly wrong output.
Affected functions
The public fraction-grid consumers in
xrspatial/hydro:flow_accumulation_mfdflow_length_mfdstream_order_mfdstream_link_mfdflow_path_mfdhand_mfdwatershed_mfdProposal
Add fraction-value validation that runs right after the existing (8, H, W) shape check in each function. Check three things:
Raise
ValueErroron any violation. Keep the documented semantics (sum == 1.0 or 0.0). The tolerance needs to be loose enough that valid grids out offlow_direction_mfdstill pass.Scope
Fraction value and topology only (negative, sum, NaN consistency). Secondary-raster shape validation, cyclic-graph detection, and dask-laziness work are separate issues.