QGIS plugin · Spatial machine learning · Guide

02SpatialML — Spatial Machine Learning Lab

Predictive mapping with machine learning in QGIS, from point or polygon samples and covariate rasters to a map with known limits: a validation designer that shows whether the folds mimic the prediction task, five models on the same folds, explanations computed on held-out data, a wall-to-wall prediction with interval, dissimilarity index and area of applicability, and a model card with a JSON manifest that replays the study. Every engine is written in NumPy.

Version: 0.1.0 QGIS: 3.28+ / 4.x Licence: GPL-2.0-or-later Developer: Geophilo Language: English
01 · Overview

What 02SpatialML does

Predictive mapping with machine learning in QGIS, from point or polygon samples and covariate rasters to a map with known limits: a validation designer that shows whether the folds mimic the prediction task, five models on the same folds, explanations computed on held-out data, a wall-to-wall prediction with interval, dissimilarity index and area of applicability, and a model card with a JSON manifest that replays the study. Every engine is written in NumPy.

Validation

Folds that mimic the task

Random kk-fold, square and hexagonal blocks, coordinate clusters, buffered leave-one-out and kNNDM; block size from the variogram range; nearest-neighbour distance curves of samples, prediction locations and each design, with the Wasserstein distance WW per design.

Models

Five models, same folds

OLS baseline, random forest with quantile regression forest intervals, gradient boosting with split-conformal intervals, GWR and MGWR, tuned by nested cross-validation; a leaderboard with spatial-CV R2R^2, RMSE, interval coverage, residual Moran's II and the optimism gap.

Explanation and limits

Held-out explanations, AOA

Permutation importance, exact TreeSHAP, partial dependence with ICE, accumulated local effects and local GWR/MGWR coefficients; the prediction is masked to the area of applicability (Meyer & Pebesma 2021).

02 · Install and quick start

Install, then run the demo

In QGIS, open Plugins › Manage and Install Plugins, search for 02SpatialML and install it, or install a release zip with Install from ZIP.

QGIS 3.28 or later (QGIS 4 included). NumPy and GDAL ship with QGIS. SciPy is used for neighbour queries when present, with identical results without it. scikit-learn is optional (a faster random forest engine for large sample sets). The native engines are checked against PySAL mgwr, shap, scikit-learn and CAST.

Open the lab

Click the 02SpatialML toolbar button; the lab opens as a dock on the right.

Load the demo landscape

On Data, press Load demo landscape: 400 point samples in 8 clusters over the western two thirds of a 240×240240 \times 240-cell (50 m) landscape in EPSG:32635, with five covariate rasters. The eastern third holds covariate values outside every sampled value.

Run the study

Press Run whole study, or walk through the pages: Run explore, Make folds, Run validation, Run explanations, Predict.

Read the result

On Models, the random kk-fold error is lower than the spatial-block error (the optimism gap). On Predict, the AOA layer marks the eastern third as outside the area of applicability. On Report, write the model card and the manifest, then press Replay manifest.

03 · The dock

The lab dock, page by page

The lab is a dock on the right of the QGIS window with an icon rail of seven pages, Settings and Help. Long steps run as QGIS background tasks with a progress bar and a Cancel button.

PageWhat it holds
1. DataSamples layer, target field (regression or classification detected, with an override), attribute covariates, covariate rasters with a categorical toggle, polygon statistic and point buffer; a working CRS badge, Load demo landscape and Run whole study.
2. ExploreTarget histogram, correlation heatmap with the variance inflation factor, and the variogram of the target and of the OLS residuals with its practical range.
3. ValidationDesign chips, kk, block size or radius prefilled from the variogram range, Preview folds on map and the distance diagnostics.
4. ModelsModel and engine choice (native NumPy or scikit-learn when installed), nested tuning, Run validation, the leaderboard, KPI cards for the best model and Show residuals on map.
5. ExplainPermutation importance with fold whiskers, a TreeSHAP summary, PDP with ICE curves and ALE for any covariate, the GWR/MGWR local coefficient layer and the bandwidth per term.
6. PredictRaster grid or vector layer, interval level, area of applicability, tile size; layers for the prediction masked to the AOA, the full mean, interval width, dissimilarity index and the AOA mask.
7. ReportModel card (HTML), run manifest (JSON), cross-validation predictions (CSV) and layers (GeoPackage); Replay manifest rebuilds the table, checks the hashes, refits and compares every metric.
Validation page of the 02SpatialML dock with the fold designs and nearest-neighbour distance curves
Validation page of the 02SpatialML dock with the fold designs and nearest-neighbour distance curves.
Models page with the leaderboard and the KPI cards of the best model
Models page with the leaderboard and the KPI cards of the best model.
Explain page with permutation importance and the TreeSHAP summary
Explain page with permutation importance and the TreeSHAP summary.
Predict page with the share of the map inside the area of applicability
Predict page with the share of the map inside the area of applicability.
04 · Processing

Processing provider

The plugin registers a 02SpatialML provider with 11 algorithms in the Processing Toolbox, usable in models, batch mode and scripts.

GroupAlgorithm
Whole studySpatial machine learning lab (whole study)
DataBuild sample table
DataHarmonise covariate rasters
ExploreEmpirical variogram
Validation designMake spatial folds
Validation designNearest-neighbour distance diagnostics
ModelsCross-validate model
ExplanationExplain model (importance, SHAP, PDP / ALE)
PredictionFit and predict raster
PredictionArea of applicability
RecordReplay run manifest
05 · Manual

Full manual

06 · Credits

Citation and licence

Name02SpatialML - Spatial Machine Learning Lab
Packagezero2spatialml
Version0.1.0
QGIS3.28 or newer; QGIS 4 supported
LicenceGPL-2.0-or-later (LICENSE)
DeveloperGeophilo · Yusuf Eminoğlu (ORCID 0009-0005-6000-2934)
Sourcegitlab.com/geophilo1/zero2spatialml
Issuesgitlab.com/geophilo1/zero2spatialml/-/work_items
Hubplugins.qgis.org search: zero2spatialml (listing pending)
RevisionNovember 2026
Eminoğlu, Y. (2026). 02SpatialML - Spatial Machine Learning Lab (version 0.1.0) [QGIS plugin]. https://gitlab.com/geophilo1/zero2spatialml