Add least-cost corridor analysis (#965) (#968)

* Add least-cost corridor function (#965)

Computes corridors of low cumulative cost between source locations
by summing two cost-distance surfaces and normalizing. Supports
absolute and relative thresholding, pre-computed cost-distance
inputs, and multi-source pairwise corridors.

* Add tests for least_cost_corridor (#965)

Covers symmetry, optimal path minimum, absolute and relative
thresholding, precomputed surfaces, multi-source pairwise,
barriers, unreachable sources, single-cell input, and input
validation. All parametrized across numpy and dask+numpy backends.

* Add corridor docs, user guide notebook, and README entry (#965)

Adds API reference entry under Proximity, a user guide notebook
(20_Corridor_Analysis) covering all major features, and a row
in the README feature matrix.

Author: brendancol

README.md

@@ -241,6 +241,7 @@ In the GIS world, rasters are used for representing continuous phenomena (e.g. e
 | [Allocation](xrspatial/proximity.py) | Assigns each cell to the identity of the nearest source feature | ✅️ | ✅ | ✅️ | ✅️ |
 | [Balanced Allocation](xrspatial/balanced_allocation.py) | Partitions a cost surface into territories of roughly equal cost-weighted area | ✅️ | ✅ | ✅️ | ✅️ |
 | [Cost Distance](xrspatial/cost_distance.py) | Computes minimum accumulated cost to the nearest source through a friction surface | ✅️ | ✅ | ✅️ | ✅️ |
+| [Least-Cost Corridor](xrspatial/corridor.py) | Identifies zones of low cumulative cost between two source locations | ✅️ | ✅ | ✅️ | ✅️ |
 | [Direction](xrspatial/proximity.py) | Computes the direction from each cell to the nearest source feature | ✅️ | ✅ | ✅️ | ✅️ |
 | [Proximity](xrspatial/proximity.py) | Computes the distance from each cell to the nearest source feature | ✅️ | ✅ | ✅️ | ✅️ |
 | [Surface Distance](xrspatial/surface_distance.py) | Computes distance along the 3D terrain surface to the nearest source | ✅️ | ✅ | ✅️ | ✅️ |

docs/source/reference/proximity.rst

@@ -35,6 +35,13 @@ Cost Distance
 
     xrspatial.cost_distance.cost_distance
 
+Least-Cost Corridor
+====================
+.. autosummary::
+    :toctree: _autosummary
+
+    xrspatial.corridor.least_cost_corridor
+
 Balanced Allocation
 ====================
 .. autosummary::