Scikit-learn compatible tools for spatial model validation.

geovalidate provides spatial point samplers, spatially-aware cross-validators, and prediction-quality metrics that slot directly into sklearn pipelines and cross_val_score workflows.

pip install -e ".[raster]"   # include rasterio for raster-based samplers

Split King County house-price data with HilbertKFold, hold out one fold, sample new prediction locations in that fold's footprint, impute feature values with a locally-weighted bootstrap from the training data, predict, and check the Area of Applicability.

from geovalidate import HilbertKFold, PoissonSampler, LocalBootstrap, area_of_applicability

import geopandas, geodatasets, numpy, pandas
gdf_full = geopandas.read_file(geodatasets.get_path("geoda.home_sales")).to_crs("EPSG:32610")
gdf_full["log_price"] = numpy.log(gdf_full["price"])
gdf_full["decile"] = (
    gdf_full["log_price"].rank(pct=True).multiply(10).clip(upper=9.99).astype(int)
)
idx = (
    gdf_full.groupby("decile")
    .apply(lambda g: g.sample(min(60, len(g)), random_state=42), include_groups=False)
    .index.get_level_values(1)
)
gdf = gdf_full.loc[idx].reset_index(drop=True)
feat_cols = ["sqft_liv", "bedrooms", "bathrooms", "grade"]

1. Spatially balanced split — split into 5 folds; hold out fold 0 as the prediction target and train on the remaining four:

from geovalidate import HilbertKFold
hkf = HilbertKFold(n_splits=5, random_state=0)
train_idx, holdout_idx = list(hkf.split(gdf))[0]
gdf_train   = gdf.iloc[train_idx].reset_index(drop=True)
gdf_holdout = gdf.iloc[holdout_idx].reset_index(drop=True)
X_train = gdf_train[feat_cols].fillna(0)
y_train = numpy.log(gdf_train["price"])

2. Fit a model on the training folds using a geographically weighted random forest:

from gwlearn.ensemble import GWRandomForestRegressor
model = GWRandomForestRegressor(
    bandwidth=10000, fixed=True, kernel="bisquare",
    keep_models=True, coplanar="clique", random_state=0,
)
model.fit(X_train, y_train, geometry=gdf_train.geometry)

3. Accuracy assessment — predict at the known holdout locations and compare to observed prices:

X_holdout = gdf_holdout[feat_cols].fillna(0)
y_holdout  = numpy.log(gdf_holdout["price"])
y_holdout_pred = model.predict(X_holdout, geometry=gdf_holdout.geometry)

4. Sample new prediction locations across the full study area using an inhomogeneous Poisson process — intensity is a KDE fitted to the full dataset's point density:

from geovalidate import PoissonSampler
new_pts = PoissonSampler(n_expected=100, random_state=1).sample(
    gdf.geometry,
    intensity=gdf.geometry,
)

5. Impute feature values at the new locations from the training data — LocalBootstrap draws donor rows from gdf_train, weighted by distance to each new point:

from geovalidate import LocalBootstrap
lb = LocalBootstrap(k=15, kernel="bisquare", n_bootstraps=50, random_state=2)
boot_samples = list(lb.sample(new_pts, donor=gdf_train))
X_new = pandas.DataFrame(
    numpy.mean([s[feat_cols].fillna(0).values for s in boot_samples], axis=0),
    columns=feat_cols,
)

6. Predict log(price) at the new locations:

log_price_pred = model.predict(X_new, geometry=new_pts.geometry)

7. Check the Area of Applicability — which new locations are close enough to the training distribution for the model to be trusted?

applicable = area_of_applicability(X_new.values, X_train.values, feature_weights="uniform")
print(f"{applicable.sum()} / {len(applicable)} new points within AOA")
# 79 / 100 new points within AOA

Generate spatial point samples from geometries, rasters, or intensity surfaces.

All samplers accept quasi_random="sobol", "halton", or "r2" for low-discrepancy sequences with better spatial coverage than pure random sampling.

All cross-validators follow the sklearn splitter protocol (split(X) yields (train_idx, test_idx) pairs) and work directly with cross_val_score.

correlogram_range and knn_range auto-detect a sensible bandwidth / k from the empirical spatial autocorrelation of the response variable.

Runnable notebooks are in the documentation:

Every class is a BaseEstimator subclass — get_params() / set_params() and GridSearchCV work out of the box.

Claude code has been used to assist with test and documentation development, in addition to implementing additional features within human-authored classes.