xrspatial.balanced_allocation.balanced_allocation#

xrspatial.balanced_allocation.balanced_allocation(raster: DataArray, friction: DataArray, x: str = 'x', y: str = 'y', target_values: list = [], max_cost: float = inf, connectivity: int = 8, tolerance: float = 0.05, max_iterations: int = 100, learning_rate: float = 0.5) → DataArray[source]#

Partition a cost surface into balanced service territories.

Assigns each cell to a source such that all territories have roughly equal cost-weighted area (sum of friction values). This extends standard cost-distance allocation by iteratively adjusting per-source biases until the workload is balanced.

Parameters:

  • raster (xr.DataArray) – 2-D source raster. Source pixels are identified by non-zero finite values (or values in target_values). Each unique value is treated as a separate source.

  • friction (xr.DataArray) – 2-D friction (cost) surface. Must have the same shape and coordinates as raster.

  • x (str, default='x') – Name of the x coordinate.

  • y (str, default='y') – Name of the y coordinate.

  • target_values (list, optional) – Specific pixel values in raster to treat as sources. If empty, all non-zero finite pixels are sources.

  • max_cost (float, default=np.inf) – Maximum accumulated cost passed to cost_distance.

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

  • tolerance (float, default=0.05) – Convergence threshold. The loop stops when every territory’s cost-weighted area is within tolerance of the mean (as a fraction of the mean).

  • max_iterations (int, default=100) – Maximum number of bias-adjustment iterations.

  • learning_rate (float, default=0.5) – Controls how aggressively biases are updated each iteration. Smaller values are more stable; larger values converge faster.

Returns:

2-D array of source IDs (float32). Each cell contains the ID of the source it is assigned to. Unreachable cells are NaN.

Return type:

xr.DataArray