Deprecate local analysis module (xrspatial.local)

[brendancol]

Summary

The xrspatial.local module (cell_stats, combine, lesser_frequency, equal_frequency, greater_frequency, lowest_position, highest_position, popularity, rank) should be deprecated and removed. These functions are thin, unoptimized wrappers around operations that xarray already provides natively.

Rationale

1. No performance value

Every function iterates cell-by-cell using np.nditer + Python loops — the worst-case performance pattern. The native xarray equivalents are vectorized and automatically benefit from dask parallelism and cupy GPU support.

2. Doesn't fit the library's multi-backend architecture

Every other module in xrspatial uses the ArrayTypeFunctionMapping dispatch pattern with numpy/cupy/dask+numpy/dask+cupy backends. The locals module is numpy-only, single-threaded, and CPU-only. Bringing it up to parity would mean reimplementing what xarray already does.

3. Effectively dead code

• Not exported from xrspatial/__init__.py
• Not referenced by any other module
• No functional changes since original addition (only isort reformatting)

4. Native xarray equivalents are one-liners

xrspatial.local	xarray equivalent
cell_stats(ds, func='sum')	ds.to_array('var').sum('var')
cell_stats(ds, func='max')	ds.to_array('var').max('var')
lowest_position(ds)	ds.to_array('var').argmin('var') + 1
highest_position(ds)	ds.to_array('var').argmax('var') + 1
lesser_frequency(ds, ref)	(ds.to_array('var') < ds[ref]).sum('var')
equal_frequency(ds, ref)	(ds.to_array('var') == ds[ref]).sum('var')
greater_frequency(ds, ref)	(ds.to_array('var') > ds[ref]).sum('var')

The xarray versions are arguably more readable to anyone who knows xarray, and they're automatically lazy, parallel, and GPU-compatible.

5. ArcGIS naming parity is a trap, not a feature

These were originally added to map onto ArcGIS Spatial Analyst local tools. But a user migrating from ArcGIS will hit these functions, find they're slow and don't work with dask/cupy, and end up rewriting with native xarray anyway.

Proposed plan

1. Add FutureWarning deprecation notices to each function, pointing users to the xarray equivalents
2. Add a short migration note to the docs
3. Remove after one release cycle: delete xrspatial/local.py, xrspatial/tests/test_local.py, and the notebook guides (docs/source/user_guide/local.ipynb, examples/user_guide/8_Local_Tools.ipynb)

Files affected

• xrspatial/local.py
• xrspatial/tests/test_local.py
• docs/source/user_guide/local.ipynb
• examples/user_guide/8_Local_Tools.ipynb