spatialcv 0.1.0__py3-none-any.whl

spatialcv/__init__.py

@@ -0,0 +1,59 @@
+"""spatialcv: honest cross-validation for models on spatial data.
+
+scikit-learn compatible splitters that keep spatially autocorrelated neighbours out of
+the training data of each test fold, plus tools to choose the block size or buffer and to
+check whether the CV is as hard as the real prediction task.
+"""
+
+from ._coords import EARTH_RADIUS_M, pairwise_distances
+from .blocks import SpatialBlockKFold
+from .buffer import BufferedLeaveOneOut, SpatialKFoldWithBuffer
+from .cluster import EnvironmentalBlockKFold, SpatialClusterKFold
+from .datasets import gaussian_random_field, make_prediction_grid, make_spatial_regression
+from .diagnostics import FoldDiagnostics, fold_diagnostics
+from .nndm import (
+    KNNDMKFold,
+    KNNDMResult,
+    NNDMLeaveOneOut,
+    NNDMResult,
+    knndm,
+    nndm,
+    wasserstein_distance,
+)
+from .plotting import plot_folds
+from .variogram import (
+    Variogram,
+    empirical_variogram,
+    estimate_autocorrelation_range,
+    fit_variogram_model,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "EARTH_RADIUS_M",
+    "BufferedLeaveOneOut",
+    "EnvironmentalBlockKFold",
+    "FoldDiagnostics",
+    "KNNDMKFold",
+    "KNNDMResult",
+    "NNDMLeaveOneOut",
+    "NNDMResult",
+    "SpatialBlockKFold",
+    "SpatialClusterKFold",
+    "SpatialKFoldWithBuffer",
+    "Variogram",
+    "__version__",
+    "empirical_variogram",
+    "estimate_autocorrelation_range",
+    "fit_variogram_model",
+    "fold_diagnostics",
+    "gaussian_random_field",
+    "knndm",
+    "make_prediction_grid",
+    "make_spatial_regression",
+    "nndm",
+    "pairwise_distances",
+    "plot_folds",
+    "wasserstein_distance",
+]

spatialcv/_base.py

@@ -0,0 +1,105 @@
+"""Shared base class for the spatial splitters."""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any, Iterator, List, Optional, Sequence, Tuple
+
+import numpy as np
+from sklearn.model_selection import BaseCrossValidator
+
+from ._coords import check_metric, resolve_coords
+
+
+def _short(value: Any) -> str:
+    if isinstance(value, np.ndarray):
+        return f"array(shape={value.shape})"
+    if hasattr(value, "shape") and hasattr(value, "__len__"):
+        return f"{type(value).__name__}(shape={tuple(value.shape)})"
+    return repr(value)
+
+
+class SpatialSplitter(BaseCrossValidator):  # type: ignore[misc]
+    """Base class: scikit-learn ``split`` / ``get_n_splits`` API plus coordinate lookup.
+
+    Subclasses either implement :meth:`_fold_labels` (partitioning splitters) or override
+    :meth:`split` directly (splitters that drop training points, such as buffered ones).
+    """
+
+    coords: Any = None
+    coord_columns: Optional[Sequence[Any]] = None
+    metric: str = "euclidean"
+
+    def _get_coords(self, X: Any) -> np.ndarray:
+        check_metric(self.metric)
+        return resolve_coords(X, self.coords, self.coord_columns, self.metric)
+
+    # -- partitioning splitters -------------------------------------------------------
+    def _fold_labels(self, X: Any, y: Any = None, groups: Any = None) -> np.ndarray:
+        raise NotImplementedError
+
+    def assign_folds(self, X: Any = None, y: Any = None, groups: Any = None) -> np.ndarray:
+        """Return the test-fold index (0 .. n_splits-1) of every sample."""
+        return self._fold_labels(X, y, groups)
+
+    def split(
+        self, X: Any, y: Any = None, groups: Any = None
+    ) -> Iterator[Tuple[np.ndarray, np.ndarray]]:
+        """Generate ``(train_index, test_index)`` pairs, one per fold."""
+        labels = self._fold_labels(X, y, groups)
+        indices = np.arange(len(labels))
+        for fold in range(int(labels.max()) + 1):
+            test = labels == fold
+            yield indices[~test], indices[test]
+
+    def get_n_splits(self, X: Any = None, y: Any = None, groups: Any = None) -> int:
+        """Number of splitting iterations."""
+        return int(self.n_splits)
+
+    def __repr__(self) -> str:
+        sig = inspect.signature(type(self).__init__)
+        parts: List[str] = []
+        for name in sig.parameters:
+            if name == "self":
+                continue
+            parts.append(f"{name}={_short(getattr(self, name, None))}")
+        return f"{type(self).__name__}({', '.join(parts)})"
+
+
+def check_n_splits(n_splits: int) -> int:
+    if not isinstance(n_splits, (int, np.integer)) or isinstance(n_splits, bool):
+        raise ValueError(f"n_splits must be an integer, got {n_splits!r}")
+    if n_splits < 2:
+        raise ValueError(f"n_splits must be at least 2, got {n_splits}")
+    return int(n_splits)
+
+
+def assign_groups_to_folds(
+    sizes: np.ndarray, n_splits: int, rng: np.random.RandomState, balance: bool
+) -> np.ndarray:
+    """Assign ``len(sizes)`` groups (blocks or clusters) to ``n_splits`` folds.
+
+    ``balance=False``: groups are shuffled and dealt round-robin, so every fold receives the
+    same number of groups (+/- 1). ``balance=True``: groups are visited from largest to
+    smallest (random order among equal sizes) and each goes to the fold that currently holds
+    the fewest samples (longest-processing-time greedy), which equalises fold sizes.
+    """
+    n_groups = len(sizes)
+    if n_groups < n_splits:
+        raise ValueError(
+            f"Only {n_groups} non-empty spatial groups for n_splits={n_splits}; "
+            "use smaller blocks / more clusters or fewer folds."
+        )
+    order = rng.permutation(n_groups)
+    out = np.empty(n_groups, dtype=int)
+    if not balance:
+        out[order] = np.arange(n_groups) % n_splits
+        return out
+    order = order[np.argsort(-sizes[order], kind="stable")]
+    load = np.zeros(n_splits)
+    for g in order:
+        candidates = np.flatnonzero(load == np.min(load))
+        f = int(candidates[rng.randint(len(candidates))])
+        out[g] = f
+        load[f] += sizes[g]
+    return out

spatialcv/_coords.py

@@ -0,0 +1,201 @@
+"""Coordinate handling, distances and nearest-neighbour queries.
+
+Two coordinate systems are supported:
+
+* ``metric="euclidean"``: planar coordinates (for example metres in a projected CRS).
+* ``metric="haversine"``: geographic ``(lon, lat)`` pairs in decimal degrees. Distances are
+  great-circle distances in metres on a sphere with the mean Earth radius.
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Any, List, Optional, Sequence
+
+import numpy as np
+from sklearn.neighbors import BallTree, KDTree
+
+#: Mean Earth radius in metres (IUGG), used for haversine distances.
+EARTH_RADIUS_M = 6_371_008.8
+
+_METRICS = ("euclidean", "haversine")
+
+
+def check_metric(metric: str) -> str:
+    """Validate a distance metric name."""
+    if metric not in _METRICS:
+        raise ValueError(f"metric must be one of {_METRICS}, got {metric!r}")
+    return metric
+
+
+def _is_geo(obj: Any) -> bool:
+    """Duck-type test for a geopandas GeoSeries / GeoDataFrame."""
+    geom = getattr(obj, "geometry", obj)
+    return hasattr(geom, "geom_type") and hasattr(geom, "centroid")
+
+
+def _geo_to_xy(obj: Any) -> np.ndarray:
+    geom = getattr(obj, "geometry", obj)
+    if bool(np.all(np.asarray(geom.geom_type) == "Point")):
+        pts = geom
+    else:
+        with warnings.catch_warnings():
+            # Centroids in a geographic CRS are approximate; that is fine for fold building.
+            warnings.simplefilter("ignore")
+            pts = geom.centroid
+    return np.column_stack([np.asarray(pts.x, dtype=float), np.asarray(pts.y, dtype=float)])
+
+
+def as_coords(coords: Any, metric: str = "euclidean") -> np.ndarray:
+    """Convert ``coords`` (array-like of shape (n, 2) or a GeoSeries) to a float array."""
+    arr = _geo_to_xy(coords) if _is_geo(coords) else np.asarray(coords, dtype=float)
+    if arr.ndim != 2 or arr.shape[1] != 2:
+        raise ValueError(f"coordinates must have shape (n_samples, 2), got {arr.shape}")
+    if not np.all(np.isfinite(arr)):
+        raise ValueError("coordinates contain NaN or infinite values")
+    if metric == "haversine":
+        if np.any(np.abs(arr[:, 1]) > 90.0) or np.any(np.abs(arr[:, 0]) > 360.0):
+            raise ValueError(
+                "metric='haversine' expects (lon, lat) in decimal degrees; "
+                "found latitudes outside [-90, 90] or longitudes outside [-360, 360]"
+            )
+    return arr
+
+
+def resolve_coords(
+    X: Any,
+    coords: Any = None,
+    coord_columns: Optional[Sequence[Any]] = None,
+    metric: str = "euclidean",
+) -> np.ndarray:
+    """Find the sample coordinates for a splitter.
+
+    Resolution order:
+
+    1. ``coords`` given explicitly (array of shape (n, 2) or a GeoSeries/GeoDataFrame);
+    2. ``coord_columns``: two column names (DataFrame) or integer positions inside ``X``;
+    3. ``X`` itself when it is a GeoDataFrame/GeoSeries (point geometry or centroids);
+    4. ``X`` itself when it has exactly two columns.
+    """
+    if coords is not None:
+        arr = as_coords(coords, metric)
+    elif coord_columns is not None:
+        if X is None:
+            raise ValueError("coord_columns requires X")
+        cols = list(coord_columns)
+        if len(cols) != 2:
+            raise ValueError("coord_columns must name exactly two columns")
+        if hasattr(X, "iloc"):
+            if all(c in X.columns for c in cols):
+                arr = np.asarray(X[cols], dtype=float)
+            else:
+                arr = np.asarray(X.iloc[:, cols], dtype=float)
+        else:
+            arr = np.asarray(X)[:, cols].astype(float)
+        arr = as_coords(arr, metric)
+    elif X is not None and _is_geo(X):
+        arr = as_coords(X, metric)
+    elif X is not None:
+        arr = np.asarray(X)
+        if arr.ndim != 2 or arr.shape[1] != 2:
+            raise ValueError(
+                "Cannot find sample coordinates: pass coords=(n, 2) array, "
+                "coord_columns=[x_col, y_col], a GeoDataFrame as X, or an X with "
+                "exactly two columns."
+            )
+        arr = as_coords(arr.astype(float), metric)
+    else:
+        raise ValueError("No coordinates: pass coords= or X")
+    if X is not None and not _is_geo(X) and hasattr(X, "__len__") and len(X) != len(arr):
+        raise ValueError(f"coords has {len(arr)} rows but X has {len(X)} samples")
+    return arr
+
+
+def to_planar(coords: np.ndarray, metric: str) -> np.ndarray:
+    """Return planar coordinates in metres (equirectangular projection for lon/lat)."""
+    if metric == "euclidean":
+        return np.asarray(coords, dtype=float)
+    lon = np.radians(coords[:, 0])
+    lat = np.radians(coords[:, 1])
+    lat0 = float(np.mean(lat))
+    lon0 = float(np.mean(lon))
+    x = EARTH_RADIUS_M * (lon - lon0) * np.cos(lat0)
+    y = EARTH_RADIUS_M * (lat - lat0)
+    return np.column_stack([x, y])
+
+
+def to_unit_sphere(coords: np.ndarray) -> np.ndarray:
+    """(lon, lat) degrees to 3D unit vectors (for clustering on the sphere)."""
+    lon = np.radians(coords[:, 0])
+    lat = np.radians(coords[:, 1])
+    return np.column_stack([np.cos(lat) * np.cos(lon), np.cos(lat) * np.sin(lon), np.sin(lat)])
+
+
+def pairwise_distances(a: np.ndarray, b: np.ndarray, metric: str = "euclidean") -> np.ndarray:
+    """Dense distance matrix of shape (len(a), len(b))."""
+    a = np.asarray(a, dtype=float)
+    b = np.asarray(b, dtype=float)
+    if metric == "euclidean":
+        return np.hypot(a[:, 0, None] - b[None, :, 0], a[:, 1, None] - b[None, :, 1])
+    lon1 = np.radians(a[:, 0])[:, None]
+    lat1 = np.radians(a[:, 1])[:, None]
+    lon2 = np.radians(b[:, 0])[None, :]
+    lat2 = np.radians(b[:, 1])[None, :]
+    h = (
+        np.sin((lat2 - lat1) / 2.0) ** 2
+        + np.cos(lat1) * np.cos(lat2) * np.sin((lon2 - lon1) / 2.0) ** 2
+    )
+    return 2.0 * EARTH_RADIUS_M * np.arcsin(np.sqrt(np.clip(h, 0.0, 1.0)))
+
+
+class _Tree:
+    """Nearest-neighbour index in metres for either metric."""
+
+    def __init__(self, ref: np.ndarray, metric: str) -> None:
+        self.metric = metric
+        if metric == "haversine":
+            self._scale = EARTH_RADIUS_M
+            self._tree: Any = BallTree(np.radians(ref[:, ::-1]), metric="haversine")
+        else:
+            self._scale = 1.0
+            self._tree = KDTree(np.asarray(ref, dtype=float))
+
+    def _q(self, pts: np.ndarray) -> np.ndarray:
+        pts = np.asarray(pts, dtype=float)
+        return np.radians(pts[:, ::-1]) if self.metric == "haversine" else pts
+
+    def query(self, pts: np.ndarray, k: int = 1) -> np.ndarray:
+        dist, _ = self._tree.query(self._q(pts), k=k)
+        return np.asarray(dist) * self._scale
+
+    def query_radius(self, pts: np.ndarray, r: float) -> List[np.ndarray]:
+        ind = self._tree.query_radius(self._q(pts), r=r / self._scale)
+        return list(ind)
+
+
+def nearest_distance(query: np.ndarray, ref: np.ndarray, metric: str = "euclidean") -> np.ndarray:
+    """Distance from each ``query`` point to its nearest ``ref`` point."""
+    if len(ref) == 0:
+        return np.full(len(query), np.inf)
+    if len(query) == 0:
+        return np.empty(0)
+    return _Tree(ref, metric).query(query, k=1)[:, 0]
+
+
+def nearest_neighbour_loo(coords: np.ndarray, metric: str = "euclidean") -> np.ndarray:
+    """Distance from every point to its nearest *other* point (leave-one-out)."""
+    if len(coords) < 2:
+        raise ValueError("need at least two points")
+    return _Tree(coords, metric).query(coords, k=2)[:, 1]
+
+
+def within_distance(
+    query: np.ndarray, ref: np.ndarray, radius: float, metric: str = "euclidean"
+) -> np.ndarray:
+    """Sorted unique indices of ``ref`` points within ``radius`` (inclusive) of any query."""
+    if len(query) == 0 or len(ref) == 0:
+        return np.empty(0, dtype=int)
+    hits = _Tree(ref, metric).query_radius(query, radius)
+    if not hits:
+        return np.empty(0, dtype=int)
+    return np.unique(np.concatenate(hits).astype(int))

spatialcv/blocks.py

@@ -0,0 +1,152 @@
+"""Spatial block cross-validation (Roberts et al. 2017; Valavi et al. 2019)."""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Optional, Sequence, Tuple
+
+import numpy as np
+from sklearn.utils import check_random_state
+
+from ._base import SpatialSplitter, assign_groups_to_folds, check_n_splits
+from ._coords import to_planar
+
+
+def _hex_cells(xy: np.ndarray, size: float) -> Tuple[np.ndarray, np.ndarray]:
+    """Axial (row, column) of pointy-top hexagons with area ``size**2``."""
+    radius = size * math.sqrt(2.0 / (3.0 * math.sqrt(3.0)))
+    x = xy[:, 0]
+    y = xy[:, 1]
+    q = (math.sqrt(3.0) / 3.0 * x - y / 3.0) / radius
+    r = (2.0 / 3.0 * y) / radius
+    # cube rounding
+    cx, cz = q, r
+    cy = -cx - cz
+    rx, ry, rz = np.round(cx), np.round(cy), np.round(cz)
+    dx, dy, dz = np.abs(rx - cx), np.abs(ry - cy), np.abs(rz - cz)
+    fix_x = (dx > dy) & (dx > dz)
+    fix_z = ~fix_x & ~(dy > dz)
+    rx = np.where(fix_x, -ry - rz, rx)
+    rz = np.where(fix_z, -rx - ry, rz)
+    return rz.astype(np.int64), rx.astype(np.int64)
+
+
+def block_ids(
+    xy: np.ndarray, block_size: float, shape: str = "square", origin: Any = None
+) -> Tuple[np.ndarray, np.ndarray]:
+    """Grid (row, column) of the block that contains each planar point."""
+    origin = xy.min(axis=0) if origin is None else np.asarray(origin, dtype=float)
+    rel = xy - origin
+    if shape == "square":
+        col = np.floor(rel[:, 0] / block_size).astype(np.int64)
+        row = np.floor(rel[:, 1] / block_size).astype(np.int64)
+        return row, col
+    if shape == "hex":
+        return _hex_cells(rel, block_size)
+    raise ValueError(f"shape must be 'square' or 'hex', got {shape!r}")
+
+
+class SpatialBlockKFold(SpatialSplitter):
+    """K-fold cross-validation with whole spatial blocks held out together.
+
+    The study area is covered with square or hexagonal blocks of side ``block_size``
+    (hexagons have the same area as the squares). Every block becomes a unit that is
+    assigned to one test fold, so test samples are surrounded by other test samples rather
+    than by training samples. Choose ``block_size`` at least as large as the range of
+    spatial autocorrelation (see :func:`spatialcv.estimate_autocorrelation_range`), as
+    recommended by Roberts et al. (2017) and Valavi et al. (2019).
+
+    Parameters
+    ----------
+    n_splits : int, default=5
+        Number of folds.
+    block_size : float, optional
+        Block side in coordinate units (metres for ``metric="haversine"``). Defaults to
+        the larger side of the bounding box divided by ``2 * n_splits``.
+    shape : {"square", "hex"}, default="square"
+    assignment : {"random", "systematic"}, default="random"
+        ``"random"`` shuffles the occupied blocks into folds. ``"systematic"`` numbers the
+        grid cells row by row and assigns cell ``i`` to fold ``i % n_splits`` (blockCV's
+        systematic selection); it is deterministic.
+    balance : bool, default=False
+        With random assignment, assign blocks greedily (largest first, to the currently
+        smallest fold) so the folds hold similar numbers of samples.
+    coords : array-like of shape (n_samples, 2) or GeoSeries, optional
+        Sample coordinates. See *Coordinates* in the README for the lookup rules.
+    coord_columns : sequence of two column names or positions in ``X``, optional
+    metric : {"euclidean", "haversine"}, default="euclidean"
+        ``"haversine"`` means ``(lon, lat)`` degrees; blocks are then laid out on a local
+        equirectangular projection in metres.
+    origin : (float, float), optional
+        Lower-left corner of the grid (planar units); defaults to the data minimum.
+    random_state : int, RandomState instance or None
+    """
+
+    def __init__(
+        self,
+        n_splits: int = 5,
+        *,
+        block_size: Optional[float] = None,
+        shape: str = "square",
+        assignment: str = "random",
+        balance: bool = False,
+        coords: Any = None,
+        coord_columns: Optional[Sequence[Any]] = None,
+        metric: str = "euclidean",
+        origin: Optional[Tuple[float, float]] = None,
+        random_state: Any = None,
+    ) -> None:
+        self.n_splits = check_n_splits(n_splits)
+        self.block_size = block_size
+        self.shape = shape
+        self.assignment = assignment
+        self.balance = balance
+        self.coords = coords
+        self.coord_columns = coord_columns
+        self.metric = metric
+        self.origin = origin
+        self.random_state = random_state
+
+    def _resolved_block_size(self, xy: np.ndarray) -> float:
+        if self.block_size is None:
+            extent = float(np.max(xy.max(axis=0) - xy.min(axis=0)))
+            if extent <= 0:
+                raise ValueError("all samples share one location; cannot build blocks")
+            return extent / (2 * self.n_splits) * (1.0 + 1e-9)
+        if not self.block_size > 0:
+            raise ValueError(f"block_size must be positive, got {self.block_size}")
+        return float(self.block_size)
+
+    def block_index(self, X: Any = None) -> np.ndarray:
+        """Integer id of the block containing each sample (0 .. n_blocks-1)."""
+        xy = to_planar(self._get_coords(X), self.metric)
+        row, col = block_ids(xy, self._resolved_block_size(xy), self.shape, self.origin)
+        pairs = np.column_stack([row, col])
+        _, inverse = np.unique(pairs, axis=0, return_inverse=True)
+        return np.asarray(inverse).reshape(-1)
+
+    def _fold_labels(self, X: Any, y: Any = None, groups: Any = None) -> np.ndarray:
+        if self.assignment not in ("random", "systematic"):
+            raise ValueError(
+                f"assignment must be 'random' or 'systematic', got {self.assignment!r}"
+            )
+        xy = to_planar(self._get_coords(X), self.metric)
+        size = self._resolved_block_size(xy)
+        row, col = block_ids(xy, size, self.shape, self.origin)
+        if self.assignment == "systematic":
+            if self.balance:
+                raise ValueError("balance=True is only available with assignment='random'")
+            r0, c0 = row - row.min(), col - col.min()
+            ncols = int(c0.max()) + 1
+            labels = ((r0 * ncols + c0) % self.n_splits).astype(int)
+            if len(np.unique(labels)) < self.n_splits:
+                raise ValueError(
+                    "Systematic assignment left a fold empty; use smaller blocks or fewer folds."
+                )
+            return labels
+        pairs = np.column_stack([row, col])
+        _, inverse, counts = np.unique(pairs, axis=0, return_inverse=True, return_counts=True)
+        inverse = np.asarray(inverse).reshape(-1)
+        rng = check_random_state(self.random_state)
+        fold_of_block = assign_groups_to_folds(counts, self.n_splits, rng, self.balance)
+        return fold_of_block[inverse]

spatialcv/buffer.py

@@ -0,0 +1,158 @@
+"""Buffered (dead-zone) cross-validation.
+
+Training samples closer than ``buffer`` to any test sample are dropped from that split, so
+the model cannot learn the test value from its spatially autocorrelated neighbours
+(Le Rest et al. 2014; Roberts et al. 2017; Pohjankukka et al. 2017 "spatial k-fold CV
+with dead zones").
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterator, Optional, Sequence, Tuple
+
+import numpy as np
+from sklearn.model_selection import KFold
+
+from ._base import SpatialSplitter, check_n_splits
+from ._coords import _Tree
+
+
+def _check_buffer(buffer: float) -> float:
+    try:
+        value = float(buffer)
+    except (TypeError, ValueError):
+        raise ValueError(f"buffer must be a non-negative number, got {buffer!r}") from None
+    if not np.isfinite(value) or value < 0:
+        raise ValueError(f"buffer must be a non-negative number, got {buffer!r}")
+    return value
+
+
+def _apply_buffer(
+    tree: _Tree, xy: np.ndarray, train: np.ndarray, test: np.ndarray, buffer: float
+) -> np.ndarray:
+    hits = tree.query_radius(xy[test], buffer)
+    if hits:
+        excluded = np.unique(np.concatenate(hits).astype(int))
+        train = np.setdiff1d(train, excluded, assume_unique=True)
+    return train
+
+
+class BufferedLeaveOneOut(SpatialSplitter):
+    """Leave-one-out with a circular dead zone around the test sample.
+
+    For sample ``i`` the test set is ``[i]`` and the training set is every sample farther
+    than ``buffer`` from it (distance ``<= buffer`` is excluded). Test sets partition the
+    data, so :func:`sklearn.model_selection.cross_val_predict` works.
+
+    Parameters
+    ----------
+    buffer : float
+        Dead-zone radius in coordinate units (metres for ``metric="haversine"``).
+    coords, coord_columns, metric
+        See :class:`SpatialBlockKFold`.
+    """
+
+    def __init__(
+        self,
+        buffer: float,
+        *,
+        coords: Any = None,
+        coord_columns: Optional[Sequence[Any]] = None,
+        metric: str = "euclidean",
+    ) -> None:
+        self.buffer = buffer
+        self.coords = coords
+        self.coord_columns = coord_columns
+        self.metric = metric
+
+    def get_n_splits(self, X: Any = None, y: Any = None, groups: Any = None) -> int:
+        """Number of samples (one split per sample)."""
+        return len(self._get_coords(X))
+
+    def split(
+        self, X: Any, y: Any = None, groups: Any = None
+    ) -> Iterator[Tuple[np.ndarray, np.ndarray]]:
+        buffer = _check_buffer(self.buffer)
+        xy = self._get_coords(X)
+        n = len(xy)
+        tree = _Tree(xy, self.metric)
+        neighbours = tree.query_radius(xy, buffer)
+        indices = np.arange(n)
+        for i in range(n):
+            mask = np.ones(n, dtype=bool)
+            mask[neighbours[i]] = False
+            mask[i] = False
+            train = indices[mask]
+            if len(train) == 0:
+                raise ValueError(f"buffer={buffer} leaves no training data for sample {i}")
+            yield train, np.array([i])
+
+
+class SpatialKFoldWithBuffer(SpatialSplitter):
+    """Any K-fold scheme plus a dead-zone buffer around each test fold.
+
+    By default the folds come from a shuffled :class:`sklearn.model_selection.KFold`
+    (the "spatial buffer v-fold" of ``spatialsample``); pass ``cv`` to buffer any other
+    splitter, for example :class:`SpatialBlockKFold`. For every split, training samples
+    within ``buffer`` (inclusive) of *any* test sample are removed.
+
+    Parameters
+    ----------
+    n_splits : int, default=5
+        Used only when ``cv`` is None.
+    buffer : float, default=0.0
+    cv : cross-validator, optional
+        Splitter that produces the folds. It is called with the same ``X, y, groups``.
+    shuffle : bool, default=True
+        Passed to the default ``KFold``.
+    coords, coord_columns, metric
+        See :class:`SpatialBlockKFold`.
+    random_state : int, RandomState instance or None
+        Passed to the default ``KFold``.
+    """
+
+    def __init__(
+        self,
+        n_splits: int = 5,
+        *,
+        buffer: float = 0.0,
+        cv: Any = None,
+        shuffle: bool = True,
+        coords: Any = None,
+        coord_columns: Optional[Sequence[Any]] = None,
+        metric: str = "euclidean",
+        random_state: Any = None,
+    ) -> None:
+        self.n_splits = check_n_splits(n_splits)
+        self.buffer = buffer
+        self.cv = cv
+        self.shuffle = shuffle
+        self.coords = coords
+        self.coord_columns = coord_columns
+        self.metric = metric
+        self.random_state = random_state
+
+    def _base_cv(self) -> Any:
+        if self.cv is not None:
+            return self.cv
+        return KFold(
+            self.n_splits,
+            shuffle=self.shuffle,
+            random_state=self.random_state if self.shuffle else None,
+        )
+
+    def get_n_splits(self, X: Any = None, y: Any = None, groups: Any = None) -> int:
+        return int(self._base_cv().get_n_splits(X, y, groups))
+
+    def split(
+        self, X: Any, y: Any = None, groups: Any = None
+    ) -> Iterator[Tuple[np.ndarray, np.ndarray]]:
+        buffer = _check_buffer(self.buffer)
+        xy = self._get_coords(X)
+        tree = _Tree(xy, self.metric)
+        data = X if X is not None else xy
+        for train, test in self._base_cv().split(data, y, groups):
+            train = _apply_buffer(tree, xy, np.asarray(train), np.asarray(test), buffer)
+            if len(train) == 0:
+                raise ValueError(f"buffer={buffer} leaves a fold without training data")
+            yield train, np.asarray(test)