xrspatial.corridor.least_cost_corridor#

xrspatial.corridor.least_cost_corridor(friction: DataArray, source_a: DataArray | None = None, source_b: DataArray | None = None, *, sources: list[DataArray] | None = None, pairwise: bool = False, threshold: float | None = None, relative: bool = False, precomputed: bool = False, x: str = 'x', y: str = 'y', connectivity: int = 8, max_cost: float = inf) → DataArray | Dataset[source]#

Compute a least-cost corridor between two source regions.

A corridor surface is the sum of two cost-distance fields (one from each source), normalized by the minimum corridor cost. Cells where the normalized value falls within threshold form the corridor.

Parameters:

  • friction (xr.DataArray) – 2-D friction (cost) surface. Positive finite values are passable; NaN or <= 0 marks barriers. Ignored when precomputed is True.

  • source_a (xr.DataArray, optional) – Source rasters identifying start and end regions. Non-zero finite values mark source cells (same convention as cost_distance). Required unless sources is given. When precomputed is True these are treated as pre-computed cost-distance surfaces.

  • source_b (xr.DataArray, optional) – Source rasters identifying start and end regions. Non-zero finite values mark source cells (same convention as cost_distance). Required unless sources is given. When precomputed is True these are treated as pre-computed cost-distance surfaces.

  • sources (list of xr.DataArray, optional) – Multiple source rasters for pairwise corridor computation. Mutually exclusive with source_a / source_b.

  • pairwise (bool, default False) – When True and sources has more than two entries, compute corridors for every unique pair and return an xr.Dataset with one variable per pair (named corridor_i_j).

  • threshold (float, optional) – Cost threshold for masking the corridor. Cells whose normalized corridor cost exceeds this value are set to NaN.

  • relative (bool, default False) – If True, threshold is a fraction of the minimum corridor cost (e.g. 0.10 means within 10 % of optimal). If False, threshold is in absolute cost units.

  • precomputed (bool, default False) – If True, source_a / source_b (or entries in sources) are already cost-distance surfaces. Skips the internal cost_distance calls.

  • x (str) – Coordinate names forwarded to cost_distance.

  • y (str) – Coordinate names forwarded to cost_distance.

  • connectivity (int, default 8) – Pixel connectivity (4 or 8), forwarded to cost_distance.

  • max_cost (float, default np.inf) – Maximum cost budget, forwarded to cost_distance.

Returns:

Normalized corridor surface (float). Values start at 0 along the optimal corridor and increase with deviation from it. When threshold is set, cells beyond the cutoff are NaN. With pairwise=True and multiple sources, returns a Dataset keyed by pair indices (corridor_0_1, corridor_0_2, …).

Return type:

xr.DataArray or xr.Dataset