spatialcv 0.1.0__py3-none-any.whl

spatialcv/variogram.py

@@ -0,0 +1,273 @@
+"""Empirical semivariogram and model fitting to estimate the autocorrelation range.
+
+Pure numpy. The empirical semivariogram (Matheron's estimator)
+
+    gamma(h) = 1 / (2 N(h)) * sum_{|s_i - s_j| in bin h} (z_i - z_j)^2
+
+is fitted with a spherical or exponential model plus nugget by weighted least squares
+with weights ``N(h) / h^2`` (Cressie 1985; gstat's default ``fit.method = 7``). For a
+fixed range the model is linear in nugget and partial sill, so those are solved exactly
+(non-negative) while the range is found by a grid search followed by refinement.
+
+The *effective range* (distance where the model reaches ~95 % of the sill; equal to the
+range parameter for the spherical model and three times it for the exponential model) is
+a sensible minimum block size or buffer distance (Roberts et al. 2017; Valavi et al. 2019).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional, Tuple
+
+import numpy as np
+from sklearn.utils import check_random_state
+
+from ._coords import as_coords, check_metric, pairwise_distances
+
+_MODELS = ("spherical", "exponential")
+
+
+def _basis(h: np.ndarray, a: float, model: str) -> np.ndarray:
+    h = np.asarray(h, dtype=float)
+    if model == "spherical":
+        t = np.minimum(h / a, 1.0)
+        return np.asarray(1.5 * t - 0.5 * t**3)
+    return np.asarray(1.0 - np.exp(-h / a))
+
+
+@dataclass
+class Variogram:
+    """A fitted semivariogram model.
+
+    Attributes
+    ----------
+    model : str
+        ``"spherical"`` or ``"exponential"``.
+    nugget, partial_sill : float
+    range_parameter : float
+        The model's ``a`` parameter.
+    effective_range : float
+        Distance at which spatial autocorrelation becomes negligible: ``a`` (spherical) or
+        ``3 a`` (exponential, 95 % of the sill).
+    lags, gamma : ndarray
+        Mean pair distance and semivariance of each non-empty lag bin.
+    counts : ndarray
+        Number of point pairs in each bin.
+    """
+
+    model: str
+    nugget: float
+    partial_sill: float
+    range_parameter: float
+    effective_range: float
+    lags: np.ndarray
+    gamma: np.ndarray
+    counts: np.ndarray
+    sse: float
+
+    @property
+    def sill(self) -> float:
+        return self.nugget + self.partial_sill
+
+    @property
+    def range(self) -> float:
+        """Alias for :attr:`effective_range`."""
+        return self.effective_range
+
+    def __call__(self, h: Any) -> np.ndarray:
+        """Model semivariance at distance(s) ``h``."""
+        h = np.asarray(h, dtype=float)
+        out = self.nugget + self.partial_sill * _basis(h, self.range_parameter, self.model)
+        return np.where(h == 0, 0.0, out)
+
+    def plot(self, ax: Any = None) -> Any:
+        """Plot the empirical points and the fitted model (requires matplotlib)."""
+        from .plotting import _pyplot
+
+        plt = _pyplot()
+        if ax is None:
+            _, ax = plt.subplots(figsize=(6, 4))
+        ax.scatter(self.lags, self.gamma, color="0.2", s=18, label="empirical", zorder=3)
+        h = np.linspace(0, float(self.lags.max()) * 1.05, 200)
+        ax.plot(h, self(h), color="tab:blue", label=f"{self.model} fit")
+        ax.axvline(self.effective_range, color="tab:red", ls="--", lw=1, label="effective range")
+        ax.set_xlabel("distance")
+        ax.set_ylabel("semivariance")
+        ax.legend(frameon=False)
+        return ax
+
+
+def empirical_variogram(
+    coords: Any,
+    values: Any,
+    *,
+    n_lags: int = 15,
+    max_lag: Optional[float] = None,
+    metric: str = "euclidean",
+    max_points: Optional[int] = 2000,
+    random_state: Any = None,
+) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Matheron semivariogram with ``n_lags`` bins ``((i-1) w, i w]``, ``w = max_lag / n_lags``.
+
+    Returns ``(lags, gamma, counts)`` for the non-empty bins, where ``lags`` is the mean
+    pair distance in each bin. ``max_lag`` defaults to one third of the bounding-box
+    diagonal (gstat's default cutoff). With more than ``max_points`` samples a random
+    subset is used.
+    """
+    check_metric(metric)
+    xy = as_coords(coords, metric)
+    z = np.asarray(values, dtype=float).ravel()
+    if len(z) != len(xy):
+        raise ValueError(f"values has {len(z)} entries but coords has {len(xy)}")
+    finite = np.isfinite(z)
+    xy, z = xy[finite], z[finite]
+    if len(z) < 3:
+        raise ValueError("need at least three finite values")
+    if n_lags < 3:
+        raise ValueError("n_lags must be >= 3")
+    if max_points is not None and len(z) > max_points:
+        idx = check_random_state(random_state).choice(len(z), size=max_points, replace=False)
+        xy, z = xy[idx], z[idx]
+    if max_lag is None:
+        lo, hi = xy.min(axis=0), xy.max(axis=0)
+        diag = float(pairwise_distances(lo[None, :], hi[None, :], metric)[0, 0])
+        max_lag = diag / 3.0
+    if not max_lag > 0:
+        raise ValueError("max_lag must be positive (are all points at one location?)")
+    width = max_lag / n_lags
+    sum_d = np.zeros(n_lags)
+    sum_sq = np.zeros(n_lags)
+    cnt = np.zeros(n_lags)
+    n = len(z)
+    chunk = 256
+    for start in range(0, n - 1, chunk):
+        stop = min(start + chunk, n - 1)
+        d = pairwise_distances(xy[start:stop], xy, metric)
+        sq = (z[start:stop, None] - z[None, :]) ** 2
+        rows = np.arange(start, stop)[:, None]
+        upper = np.arange(n)[None, :] > rows
+        sel = upper & (d > 0) & (d <= max_lag)
+        dd, ss = d[sel], sq[sel]
+        b = np.clip(np.ceil(dd / width).astype(int) - 1, 0, n_lags - 1)
+        sum_d += np.bincount(b, weights=dd, minlength=n_lags)
+        sum_sq += np.bincount(b, weights=ss, minlength=n_lags)
+        cnt += np.bincount(b, minlength=n_lags)
+    keep = cnt > 0
+    if keep.sum() < 3:
+        raise ValueError("fewer than three non-empty lag bins; increase max_lag")
+    lags = sum_d[keep] / cnt[keep]
+    gamma = sum_sq[keep] / (2.0 * cnt[keep])
+    return lags, gamma, cnt[keep].astype(int)
+
+
+def _fit_fixed_range(
+    lags: np.ndarray, gamma: np.ndarray, w: np.ndarray, f: np.ndarray
+) -> Tuple[float, float, float]:
+    """Non-negative WLS of gamma ~ c0 + c1 f. Returns (c0, c1, sse)."""
+    sw = w.sum()
+    swf = (w * f).sum()
+    swff = (w * f * f).sum()
+    swg = (w * gamma).sum()
+    swfg = (w * f * gamma).sum()
+    det = sw * swff - swf * swf
+    c0 = c1 = -1.0
+    if det > 1e-12 * max(sw * swff, 1e-300):
+        c0 = (swff * swg - swf * swfg) / det
+        c1 = (sw * swfg - swf * swg) / det
+    if c0 < 0 or c1 < 0:
+        cand = []
+        c1_only = max(swfg / swff, 0.0) if swff > 0 else 0.0
+        cand.append((0.0, c1_only))
+        cand.append((max(swg / sw, 0.0), 0.0))
+        best = min(cand, key=lambda p: float((w * (gamma - p[0] - p[1] * f) ** 2).sum()))
+        c0, c1 = best
+    sse = float((w * (gamma - c0 - c1 * f) ** 2).sum())
+    return float(c0), float(c1), sse
+
+
+def fit_variogram_model(lags: Any, gamma: Any, counts: Any, model: str = "spherical") -> Variogram:
+    """Fit a spherical or exponential model (with nugget) to an empirical variogram."""
+    if model not in _MODELS:
+        raise ValueError(f"model must be one of {_MODELS}, got {model!r}")
+    lags = np.asarray(lags, dtype=float)
+    gamma = np.asarray(gamma, dtype=float)
+    counts = np.asarray(counts, dtype=float)
+    w = counts / np.maximum(lags, 1e-12) ** 2
+    w = w / w.sum()
+    hmax = float(lags.max())
+    hmin = float(lags.min())
+    # candidate *effective* ranges; the exponential parameter is a third of it
+    eff = np.geomspace(max(hmin * 0.25, hmax * 1e-3), hmax * 3.0, 300)
+    factor = 1.0 if model == "spherical" else 3.0
+
+    def evaluate(e: float) -> Tuple[float, float, float]:
+        return _fit_fixed_range(lags, gamma, w, _basis(lags, e / factor, model))
+
+    sses = np.array([evaluate(e)[2] for e in eff])
+    i = int(np.argmin(sses))
+    lo = eff[max(i - 1, 0)]
+    hi = eff[min(i + 1, len(eff) - 1)]
+    fine = np.linspace(lo, hi, 201)
+    fine_sse = np.array([evaluate(e)[2] for e in fine])
+    e_best = float(fine[int(np.argmin(fine_sse))])
+    c0, c1, sse = evaluate(e_best)
+    return Variogram(
+        model=model,
+        nugget=c0,
+        partial_sill=c1,
+        range_parameter=e_best / factor,
+        effective_range=e_best,
+        lags=lags,
+        gamma=gamma,
+        counts=counts.astype(int),
+        sse=sse,
+    )
+
+
+def estimate_autocorrelation_range(
+    coords: Any,
+    values: Any,
+    *,
+    model: str = "spherical",
+    n_lags: int = 15,
+    max_lag: Optional[float] = None,
+    metric: str = "euclidean",
+    max_points: Optional[int] = 2000,
+    random_state: Any = None,
+) -> Variogram:
+    """Estimate the range of spatial autocorrelation of ``values`` at ``coords``.
+
+    Computes the empirical semivariogram and fits a variogram model. Pass the response,
+    a key predictor, or (best) the residuals of a non-spatial model.
+
+    Parameters
+    ----------
+    coords : array-like (n, 2)
+        Planar coordinates, or ``(lon, lat)`` degrees with ``metric="haversine"`` (the
+        range is then in metres).
+    values : array-like (n,)
+    model : {"spherical", "exponential", "auto"}, default="spherical"
+        ``"auto"`` fits both and keeps the smaller weighted squared error.
+    n_lags, max_lag, max_points, random_state
+        See :func:`empirical_variogram`.
+
+    Returns
+    -------
+    Variogram
+        ``.effective_range`` (alias ``.range``) is the estimated autocorrelation range.
+    """
+    lags, gamma, counts = empirical_variogram(
+        coords,
+        values,
+        n_lags=n_lags,
+        max_lag=max_lag,
+        metric=metric,
+        max_points=max_points,
+        random_state=random_state,
+    )
+    if not np.any(gamma > 0):
+        raise ValueError("values show no variation; the range is undefined")
+    if model == "auto":
+        fits = [fit_variogram_model(lags, gamma, counts, m) for m in _MODELS]
+        return min(fits, key=lambda v: v.sse)
+    return fit_variogram_model(lags, gamma, counts, model)

spatialcv-0.1.0.dist-info/METADATA

@@ -0,0 +1,311 @@
+Metadata-Version: 2.4
+Name: spatialcv
+Version: 0.1.0
+Summary: Honest cross-validation for spatial machine learning: scikit-learn compatible spatial block, cluster, buffered, NNDM and kNNDM splitters.
+Author-email: Yusuf Eminoğlu <yusufeminoglu@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/YusufEminoglu/spatialcv_sdk
+Project-URL: Repository, https://github.com/YusufEminoglu/spatialcv_sdk
+Project-URL: Issues, https://github.com/YusufEminoglu/spatialcv_sdk/issues
+Project-URL: Documentation, https://github.com/YusufEminoglu/spatialcv_sdk#readme
+Project-URL: Changelog, https://github.com/YusufEminoglu/spatialcv_sdk/blob/main/CHANGELOG.md
+Keywords: spatial-cross-validation,cross-validation,spatial-autocorrelation,geoai,machine-learning,scikit-learn,block-cross-validation,nndm,knndm,variogram,gis,remote-sensing,geostatistics,model-evaluation
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: scikit-learn>=1.0.0
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.5.0; extra == "plot"
+Provides-Extra: geo
+Requires-Dist: geopandas>=0.12.0; extra == "geo"
+Requires-Dist: matplotlib>=3.5.0; extra == "geo"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: pandas>=1.3.0; extra == "dev"
+Dynamic: license-file
+
+# spatialcv
+
+**Honest cross-validation for machine learning on spatial data.**
+
+`spatialcv` provides scikit-learn compatible splitters that keep spatially autocorrelated
+neighbours out of each test fold's training data, plus the tools to choose a block size or
+buffer and to check whether your cross-validation is as hard as the real prediction task.
+
+```bash
+pip install spatialcv              # numpy + scikit-learn
+pip install "spatialcv[plot]"      # + matplotlib for fold maps
+pip install "spatialcv[geo]"       # + geopandas (GeoDataFrame input) and matplotlib
+```
+
+Python 3.9+. Every splitter has `split(X, y, groups)` and `get_n_splits()`, so it plugs into
+`cross_val_score`, `cross_validate`, `cross_val_predict`, `GridSearchCV`,
+`RandomizedSearchCV` and pipelines unchanged.
+
+## Why spatial cross-validation?
+
+Nearby observations are similar (Tobler's first law). Random K-fold puts a sample's
+neighbours in the training set, so a flexible model (random forest, gradient boosting,
+a neural network, anything that sees coordinates or spatially smooth covariates) can
+"look up" the answer instead of learning a transferable relationship. The CV score then
+reflects interpolation between close neighbours, while the map is used far from any
+sample. Large-scale mapping studies have reported random-CV accuracies that collapse
+under spatial validation (Ploton et al. 2020).
+
+Spatial CV makes the test data *as far from the training data as the prediction
+locations are*. The splitters here do this in different ways:
+
+| Splitter | Idea | Test sets | Key parameters | Reference |
+|---|---|---|---|---|
+| `SpatialBlockKFold` | square or hexagonal blocks are held out whole; random, balanced or systematic block-to-fold assignment | partition | `block_size`, `shape`, `assignment`, `balance` | Roberts et al. 2017; Valavi et al. 2019 |
+| `SpatialClusterKFold` | k-means on coordinates (on the sphere for lon/lat); clusters are held out | partition | `n_clusters`, `balance` | Brenning 2012 |
+| `EnvironmentalBlockKFold` | k-means in standardised *feature* space; tests extrapolation to new conditions | partition | `features`, `standardize` | Roberts et al. 2017; Valavi et al. 2019 |
+| `SpatialKFoldWithBuffer` | any K-fold (random by default) plus a dead zone: training points within `buffer` of a test point are dropped | partition | `buffer`, `cv` | Pohjankukka et al. 2017 |
+| `BufferedLeaveOneOut` | leave-one-out with a circular dead zone around each test point | single samples | `buffer` | Le Rest et al. 2014 |
+| `NNDMLeaveOneOut` | LOO whose training sets are thinned until the CV nearest-neighbour distance distribution matches prediction-to-sample distances | single samples | `prediction_points`, `phi`, `min_train` | Milà et al. 2022 |
+| `KNNDMKFold` | k-fold version of NNDM: clusters are merged into folds to minimise the Wasserstein distance W between those distributions | partition | `prediction_points`, `n_splits`, `maxp`, `clustering` | Linnenbrink et al. 2024 |
+
+Helpers:
+
+| Function | Purpose |
+|---|---|
+| `estimate_autocorrelation_range` | empirical semivariogram + fitted spherical / exponential model (pure numpy); gives a block size or buffer |
+| `fold_diagnostics` | nearest-neighbour distance distributions: prediction→train (`Gij`), CV test→train (`Gjstar`), LOO (`Gj`) and the W statistic, for *any* splitter |
+| `plot_folds` | map of folds, or of train / test / excluded points of one split (matplotlib) |
+| `nndm`, `knndm` | the NNDM / kNNDM algorithms as functions returning folds and distances |
+| `make_spatial_regression`, `make_prediction_grid` | synthetic autocorrelated data for experiments |
+
+## Quick start
+
+```python
+import numpy as np
+from sklearn.ensemble import RandomForestRegressor
+from sklearn.model_selection import GridSearchCV, KFold, cross_val_score
+
+import spatialcv as scv
+
+coords, X, y = scv.make_spatial_regression(400, random_state=42)
+features = np.column_stack([X, coords])
+model = RandomForestRegressor(n_estimators=100, random_state=0, n_jobs=-1)
+
+# 1. How far does spatial autocorrelation reach?
+vg = scv.estimate_autocorrelation_range(coords, y, model="auto")
+print(f"range = {vg.effective_range:.0f} m, model = {vg.model}, nugget = {vg.nugget:.2f}")
+
+# 2. Random vs spatial K-fold
+random_cv = KFold(5, shuffle=True, random_state=0)
+block_cv = scv.SpatialBlockKFold(5, block_size=vg.effective_range, coords=coords, random_state=0)
+for name, cv in [("random KFold", random_cv), ("SpatialBlockKFold", block_cv)]:
+    r2 = cross_val_score(model, features, y, cv=cv, scoring="r2")
+    print(f"{name:<18} R2 = {r2.mean():.3f} +/- {r2.std():.3f}")
+
+# 3. Hyper-parameter search with spatial folds
+search = GridSearchCV(model, {"max_features": [0.3, 1.0]}, cv=block_cv, scoring="r2")
+search.fit(features, y)
+print("best:", search.best_params_, f"R2 = {search.best_score_:.3f}")
+
+# 4. Are the CV test points as far from training data as the prediction grid?
+grid = scv.make_prediction_grid(extent=10_000, n_per_side=40)
+for name, cv in [("random KFold", random_cv), ("SpatialBlockKFold", block_cv)]:
+    d = scv.fold_diagnostics(cv, features, prediction_points=grid, coords=coords)
+    print(
+        f"{name:<18} median test->train {np.median(d.Gjstar):6.0f} m | "
+        f"prediction->train {np.median(d.Gij):6.0f} m | W = {d.W:.0f}"
+    )
+```
+
+Output (scikit-learn 1.9, numpy 2.5):
+
+```text
+range = 2760 m, model = spherical, nugget = 0.00
+random KFold       R2 = 0.835 +/- 0.041
+SpatialBlockKFold  R2 = 0.143 +/- 0.299
+best: {'max_features': 0.3} R2 = 0.225
+random KFold       median test->train    122 m | prediction->train    694 m | W = 711
+SpatialBlockKFold  median test->train    827 m | prediction->train    694 m | W = 201
+```
+
+Random K-fold tests points that are typically 122 m from a training sample, while the map
+is predicted 694 m (median) from the nearest sample: its R² of 0.84 measures something the
+model will not be asked to do.
+
+## Which CV matches the true map error?
+
+[`examples/compare_cv.py`](examples/compare_cv.py) generates 300 clustered samples of a
+spatial field together with the *true* values on a 40 × 40 prediction grid over the whole
+10 km × 10 km area, so the real map RMSE is known. Pooled CV predictions
+(`cross_val_predict`) give:
+
+```text
+autocorrelation range of y: 2177 m (spherical)
+true map RMSE: 1.035
+
+splitter                  CV RMSE    error       W
+KFold (random)              0.499   -0.537     974
+SpatialBlockKFold           1.097   +0.062     482
+SpatialClusterKFold         1.173   +0.138     403
+SpatialKFoldWithBuffer      1.216   +0.180     552
+BufferedLeaveOneOut         1.093   +0.058     760
+NNDMLeaveOneOut             0.946   -0.089      71
+KNNDMKFold                  1.210   +0.175     341
+```
+
+Random CV halves the true error. The spatial methods land within ±0.2, and NNDM has by far
+the best-matched distance distribution (lowest W). Spatial CV is not automatically
+"correct" either: strategies that hold out more than the prediction task requires are
+pessimistic (Wadoux et al. 2021), which is why matching the distance distributions
+(NNDM / kNNDM) and checking them with `fold_diagnostics` is worthwhile.
+
+## Coordinates
+
+Splitters look up sample coordinates in this order:
+
+1. `coords=`: an `(n_samples, 2)` array, or a GeoSeries / GeoDataFrame (point
+   coordinates, or centroids for other geometries);
+2. `coord_columns=`: two column names (DataFrame) or positions inside `X`;
+3. `X` itself when it is a GeoDataFrame;
+4. `X` itself when it has exactly two columns.
+
+Units: with `metric="euclidean"` (default) coordinates are planar, e.g. metres in a
+projected CRS, and `block_size` / `buffer` use the same unit. With `metric="haversine"`
+coordinates are `(lon, lat)` in degrees and all distances (`buffer`, `block_size`, `phi`,
+variogram range, diagnostics) are great-circle metres. K-means clustering then runs on 3D
+unit vectors, so clusters are correct across the antimeridian; blocks are laid on a local
+equirectangular projection.
+
+```python
+cv = scv.SpatialKFoldWithBuffer(5, buffer=2_000, coords=lonlat, metric="haversine")
+cv = scv.SpatialClusterKFold(5, coord_columns=["x", "y"])       # columns of a DataFrame X
+cv = scv.SpatialBlockKFold(5, block_size=5_000)                  # X is a GeoDataFrame
+```
+
+## Splitter notes
+
+**Blocks.** `block_size` should be at least the autocorrelation range. Hexagons have the
+same area as squares of side `block_size`. `assignment="systematic"` numbers grid cells row
+by row and sends cell *i* to fold *i* mod `n_splits` (deterministic); `balance=True`
+(random assignment) gives each block, largest first, to the fold with the fewest samples.
+`block_index(X)` returns the block id of each sample, and every partitioning splitter has
+`assign_folds(X)`.
+
+**Buffers.** A training point is dropped when its distance to *any* test point is
+`<= buffer`. Test sets still partition the data, so `cross_val_predict` works; training
+sets shrink, so very large buffers raise an error rather than yield empty training sets.
+Wrap any splitter: `SpatialKFoldWithBuffer(buffer=1000, cv=SpatialBlockKFold(...))`.
+
+**NNDM** (Milà et al. 2022) needs the locations where the model will be applied
+(`prediction_points`, e.g. a regular sample of a few thousand points of the area of
+interest). Starting from LOO, it walks through nearest-neighbour distances `r` in
+increasing order and removes test point *j*'s nearest neighbour from its training set
+whenever the LOO distance CDF `Gj*(r)` would still be at or above the prediction CDF
+`Gij(r)`, keeping more than `min_train` of the data and stopping at `phi` (default: the
+largest distance). It follows CAST's reference `nndm()`. Cost is O(n²) memory.
+
+**kNNDM** (Linnenbrink et al. 2024) clusters the samples (Ward hierarchical clustering, or
+k-means) into *q* clusters for a log-spaced grid of *q* between `n_splits` and *n* − 2.
+Clusters with at least *n*/*k* samples become folds on their own; the rest, ordered along
+the first principal component of the coordinates, are dealt round-robin into the remaining
+folds. Configurations with a fold larger than `maxp` are rejected and the one with the
+smallest Wasserstein distance W between `Gj*` and `Gij` wins. If random CV already matches
+(W < 1e-4) random folds are returned. It follows CAST's reference `knndm()`
+(geographical space).
+
+```python
+res = scv.knndm(coords, grid, n_splits=5, random_state=0)
+res.labels, res.n_clusters, res.W, res.method     # folds, chosen q, W, "hierarchical"
+res = scv.nndm(coords, grid, phi=3_000)
+res.train_indices[0], res.Gjstar, res.W
+```
+
+## Diagnostics and plots
+
+```python
+d = scv.fold_diagnostics(cv, X, prediction_points=grid, coords=coords)
+print(d)            # medians of Gij / Gjstar / Gj, W and W_random
+d.plot()            # ECDFs of the three distance distributions
+scv.plot_folds(cv, X)            # colour = test fold
+scv.plot_folds(cv, X, fold=0)    # train / test / excluded (buffer) points of split 0
+vg.plot()                        # empirical semivariogram and fitted model
+```
+
+`fold_diagnostics` works with any object that has `split`, including scikit-learn's own
+splitters, so you can check a `GroupKFold` built from administrative units too.
+
+## Variogram details
+
+`estimate_autocorrelation_range(coords, values, model="spherical" | "exponential" | "auto")`
+computes Matheron's estimator in `n_lags` equal-width bins up to `max_lag` (default: a
+third of the bounding-box diagonal) and fits nugget + partial sill + range by weighted
+least squares with weights N(h)/h² (Cressie 1985). The returned `Variogram` has
+`effective_range` (the range for the spherical model, 3 × the range parameter for the
+exponential one, i.e. 95 % of the sill), `nugget`, `partial_sill`, `sill`, the empirical
+`lags`/`gamma`/`counts`, and is callable: `vg(h)`. Use model residuals as `values` when
+possible; above 2000 samples a random subset is used (`max_points`).
+
+## References
+
+- Brenning, A. (2012). Spatial cross-validation and bootstrap for the assessment of
+  prediction rules in remote sensing: the R package sperrorest. *IEEE IGARSS 2012*,
+  5372–5375. https://doi.org/10.1109/IGARSS.2012.6352393
+- Cressie, N. (1985). Fitting variogram models by weighted least squares. *Mathematical
+  Geology* 17, 563–586. https://doi.org/10.1007/BF01032109
+- Le Rest, K., Pinaud, D., Monestiez, P., Chadoeuf, J., Bretagnolle, V. (2014). Spatial
+  leave-one-out cross-validation for variable selection in the presence of spatial
+  autocorrelation. *Global Ecology and Biogeography* 23, 811–820.
+  https://doi.org/10.1111/geb.12161
+- Linnenbrink, J., Milà, C., Ludwig, M., Meyer, H. (2024). kNNDM CV: k-fold
+  nearest-neighbour distance matching cross-validation for map accuracy estimation.
+  *Geoscientific Model Development* 17, 5897–5912.
+  https://doi.org/10.5194/gmd-17-5897-2024
+- Milà, C., Mateu, J., Pebesma, E., Meyer, H. (2022). Nearest neighbour distance matching
+  Leave-One-Out Cross-Validation for map validation. *Methods in Ecology and Evolution*
+  13, 1304–1316. https://doi.org/10.1111/2041-210X.13851
+- Ploton, P., et al. (2020). Spatial validation reveals poor predictive performance of
+  large-scale ecological mapping models. *Nature Communications* 11, 4540.
+  https://doi.org/10.1038/s41467-020-18321-y
+- Pohjankukka, J., Pahikkala, T., Nevalainen, P., Heikkonen, J. (2017). Estimating the
+  prediction performance of spatial models via spatial k-fold cross validation.
+  *International Journal of Geographical Information Science* 31, 2001–2019.
+  https://doi.org/10.1080/13658816.2017.1346255
+- Rahimi, A., Recht, B. (2007). Random features for large-scale kernel machines.
+  *Advances in Neural Information Processing Systems* 20 (used by the synthetic data
+  generator).
+- Roberts, D. R., et al. (2017). Cross-validation strategies for data with temporal,
+  spatial, hierarchical, or phylogenetic structure. *Ecography* 40, 913–929.
+  https://doi.org/10.1111/ecog.02881
+- Valavi, R., Elith, J., Lahoz-Monfort, J. J., Guillera-Arroita, G. (2019). blockCV: an R
+  package for generating spatially or environmentally separated folds for k-fold
+  cross-validation of species distribution models. *Methods in Ecology and Evolution* 10,
+  225–232. https://doi.org/10.1111/2041-210X.13107
+- Wadoux, A. M. J.-C., Heuvelink, G. B. M., de Bruin, S., Brus, D. J. (2021). Spatial
+  cross-validation is not the right way to evaluate map accuracy. *Ecological Modelling*
+  457, 109692. https://doi.org/10.1016/j.ecolmodel.2021.109692
+
+The NNDM and kNNDM implementations follow the R package CAST (Meyer, Milà, Ludwig,
+Linnenbrink et al.); block and buffer designs follow blockCV and spatialsample.
+
+## Citation
+
+See [`CITATION.cff`](CITATION.cff). Please also cite the papers of the methods you use.
+
+## License
+
+MIT © Yusuf Eminoğlu

spatialcv-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+spatialcv/__init__.py,sha256=dW7mKKzln6IYPwqHREm3s0zOxz515eVzmLOkUnhbG6w,1622
+spatialcv/_base.py,sha256=KWUXZUsmrKhbs7tjEMkm1yu-Y7bq7gf9SpD0bGfOiWw,4112
+spatialcv/_coords.py,sha256=BW-gd_ndbwAeJPBq9w22OLrnxH4D8auvPuAkq9uB20Q,7867
+spatialcv/blocks.py,sha256=X7_kvkkoKyig-y60hXRCEMADB_36dIfDoK9Dsox90PM,6841
+spatialcv/buffer.py,sha256=TP6t2lloAJHWiUH8DTPsVmOsz4v9y5edO9E4O4lrYq4,5563
+spatialcv/cluster.py,sha256=SPRBelmjGPITKkoBWPKVFQwKSK2Ody3J45epRnYkvR0,5548
+spatialcv/datasets.py,sha256=oYucJRCyKwel_PS_um-a4HttCF8YZ7e__Jdn8h-iun4,3934
+spatialcv/diagnostics.py,sha256=gtlbP_Qu1TGmmnLDtEZb_Ts4Kucox4OaxExR8atybGw,5340
+spatialcv/nndm.py,sha256=sHU-4Z1bfNfGbAgtrer_myKtnK-h6ixkX0MgQY-1Bp0,17932
+spatialcv/plotting.py,sha256=7dWmHAH53b9DuYNsgGd21Ae5XdzF2oKiHL93B4ugTBY,2943
+spatialcv/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+spatialcv/variogram.py,sha256=ntS3u5klG-Eerf_mhWCpIgNCJHUEQMI1rWznH0bXt7w,9950
+spatialcv-0.1.0.dist-info/licenses/LICENSE,sha256=Z9meOk3opsRgHOqC5mA4B8NjZoU5WU1Kqhn82FL4ICs,1072
+spatialcv-0.1.0.dist-info/METADATA,sha256=q16USxEQw1uS8KzLqDSFMs8PXFxkiih7DHflKr93Exg,16976
+spatialcv-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+spatialcv-0.1.0.dist-info/top_level.txt,sha256=GCp6bgxq3Njy1wGWbqCW-T69be6NUkIhwkhx7mNycTM,10
+spatialcv-0.1.0.dist-info/RECORD,,

spatialcv-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

spatialcv-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yusuf Eminoğlu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spatialcv-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+spatialcv