02SpatialML carries one predictive-mapping study from samples to a map with known limits inside QGIS. The input is a point or polygon layer with an observed target (a number for regression, a class for classification) and covariates from the attribute table or from a stack of covariate rasters. The study runs in seven steps: build the sample table, explore the data, choose a validation design, cross-validate the models on the same folds, explain them on held-out data, predict a map with an interval and the area of applicability, and write a model card with a run manifest that replays the study.
The same study is available in two ways: the lab dock (one page per step, with charts and styled layers) and the Processing provider (one algorithm per step plus a whole-study algorithm, usable in models and batch runs). Every engine is written in NumPy: the histogram tree builder shared by the random forest and gradient boosting, TreeSHAP, GWR and MGWR, the variogram fit, kNNDM and the area of applicability. SciPy and scikit-learn are used when present; nothing has to be installed beyond QGIS.
Predictive mapping with machine learning has a well-documented failure mode: models are validated with random cross-validation on clustered samples, the error estimate is far too optimistic, and the map is then extrapolated into covariate space the model has never seen (Ploton et al. 2020; Meyer & Pebesma 2022). The R ecosystem has the remedies (CAST with the area of applicability and kNNDM, blockCV, spatialsample, mlr3spatiotempcv, sperrorest, GWmodel, SpatialML) and Python has PySAL mgwr, shap, verde and spatial-kfold, but none of these runs as a study inside QGIS. QGIS plugins cover single slices: image classification into land cover (dzetsaka, GeoClassify, the Semi-Automatic Classification Plugin), imaging spectroscopy (EnMAP-Box), one random forest (ml4qgis), (M)GWR on a vector table (mgwr_plugin), one model each with external packages (GPBoost Spatial Predictor, Downscale Anything) or species distribution only (QMaxent). None computes an area of applicability, compares validation designs by their nearest-neighbour distance distributions, or writes a replayable model record.
Hot spots, LISA, spatial econometrics, kriging, clustering and other learners (SVM, MLP, EBM) are not part of 02SpatialML; they are in GeoStats Lab, linked from the Help page.
| Package | Used for | When missing |
|---|---|---|
| SciPy | k-d tree neighbour queries, linear solves | NumPy fallback with identical results (to \(10^{-10}\)) |
| scikit-learn | engine scikit-learn for the random forest on large sample sets; its trees are converted to the native format, so quantile intervals, TreeSHAP and the AOA still work | native engine |
| shap, mgwr | developer cross-checks only | checks skipped |
"<QGIS Python>" -m pip install --user scikit-learn with the path of the Python that runs QGIS filled in, to copy into the OSGeo4W Shell (or a terminal); restart QGIS afterwards.Limits of the native engines: a sample table above 50 000 rows or a target with more than 30 classes is refused with a readable message; GWR is skipped (and logged) above 20 000 samples and MGWR above 10 000; MGWR standard errors are computed up to 3 000 samples; GWR and MGWR raster prediction is limited to 250 000 valid cells unless the covariates are aggregated.
Every distance (block size, buffer radius, GWR fixed bandwidth, variogram lags, nearest-neighbour distances) is in metres in a projected CRS. The working CRS is the CRS of the first covariate raster when it is projected in metres, else the CRS of the sample layer when it is projected in metres, else the UTM zone of the centre of the sample extent (EPSG:326xx north, 327xx south). Sample coordinates are transformed into it. Covariate rasters that differ from the template (the first raster) in CRS, cell size, extent or alignment are resampled onto its grid with GDAL Warp into the run folder: bilinear for continuous rasters, nearest neighbour for categorical rasters, nodata merged. The Data page badge, the run log, the manifest and the model card record the working CRS, the template grid and every resampling step.
The lab is a dock on the right of the QGIS window. A vertical icon rail switches between seven numbered pages; Settings and Help sit at the bottom of the rail. Each page runs one step as a QGIS background task with a progress bar and a Cancel button, so QGIS stays responsive. Changing the settings of an earlier step clears the results of every later step (order: data, explore, design, validate, explain, predict).
Choose the samples layer (points or polygons, one row per observation) and the target field. The task is detected from the field and shown as a chip: numbers give a regression, text or an integer field with at most 10 distinct values gives a classification (at most 30 classes); the chips Regression and Classification override it. Attribute covariates are numeric fields of the samples layer; covariate rasters are raster layers of the project, each with a Categorical toggle. For polygon samples choose the polygon statistic (mean of cells, majority of cells, centroid cell); for point samples the point buffer (0 reads the cell under the point, a radius in metres averages the cells within it). The CRS badge shows the working CRS and why it was chosen; the grid badge shows the template grid and whether the rasters must be harmonised. Load demo landscape builds the synthetic landscape of section 15. Build sample table reads the covariates at every sample; KPI cards show the samples kept, the rows dropped with their reasons, the number of covariates and the target range (or the classes). Run whole study runs every step with the settings of every page.
The target histogram; the Pearson correlation between covariates as a heat map with the variance inflation factor of each covariate, \(\mathrm{VIF}_j = 1/(1 - R_j^2)\), where \(R_j^2\) is the coefficient of determination of covariate \(j\) regressed on the others (values above 5 are marked, and ALE is then preferred over PDP); the empirical variogram of the target and of the OLS residuals with the fitted model and its practical range, shown as the suggested block size.
Design chips (random k-fold, spatial blocks, hexagonal blocks, coordinate clusters, buffered leave-one-out, kNNDM), the number of folds \(k\), the block size or buffer radius (prefilled from the variogram range when Size from the variogram range is ticked) and Also run random k-fold, which cross-validates with random folds too so that the optimism gap can be reported. Make folds builds the folds of the chosen design (and random folds) and the distance diagnostics; Preview folds on map adds the block or cluster polygons with their fold id. The chart shows the nearest-neighbour distance distributions of section 7 (samples, prediction locations, each design) and a table gives the Wasserstein distance \(W\) per design; lower is better. A hint appears when random k-fold has the lower \(W\) (samples spread like the prediction locations). KPI cards: folds of the chosen design, samples per fold, smallest and largest test fold.
A checklist of the five models (OLS, random forest, gradient boosting, GWR, MGWR), each with its formula and reference as a tooltip; GWR and MGWR are regression only. The engine chip (native or scikit-learn) is enabled only when scikit-learn is installed. Tune hyperparameters (nested CV) runs the grids of section 9. MGWR minimum bandwidth sets the lower bound of each MGWR term's bandwidth search (0 keeps the default of 42 neighbours; the demo sets 100, see section 8). Run validation tunes and cross-validates every ticked model on the same folds and refits each on all samples. The leaderboard has one row per model and design, sorted by the spatial-CV error. KPI cards for the best model: spatial-CV \(R^2\) (or balanced accuracy), spatial RMSE, interval coverage and residual Moran's \(I\). A bar per model shows the optimism gap (spatial-CV RMSE minus random-CV RMSE; for classes random minus spatial balanced accuracy). Show residuals on map styles the samples by their held-out residual.
Choose the model (the best one by default) and the budget: permutation repeats \(R\), the rows and the first trees used by TreeSHAP, and the grid points of the effect curves. Run explanations computes the permutation importance (bars with whiskers for the spread over folds), the TreeSHAP summary (mean \(|\phi_j|\) bars and a strip plot of the per-sample values) and the effect plot of any covariate with the chips PDP, ICE and ALE (the covariate picker lists the six most important). For GWR and MGWR the local coefficient layer is added, a picker maps any coefficient, and a table lists the bandwidth of every term (neighbours for the adaptive kernel, metres for the fixed kernel).
Prediction target: Raster grid (every valid cell of the harmonised covariate grid), Prediction layer (a copy of a vector layer receives the prediction fields; covariates are read the same way as for the samples) or Skip the prediction. Settings: interval level (nominal central coverage), area of applicability, tile size (edge of the raster window read and predicted at once), GWR aggregation factor (GWR and MGWR raster prediction aggregates the covariates by a block mean of factor \(\times\) factor cells; it is refused above 250 000 valid cells without aggregation). Predict uses the best model and writes Float32 GeoTIFFs into the run folder. KPI cards: cells predicted, share inside the AOA, median interval width. The layers are added to a 02SpatialML group: mean (viridis), interval width (magma), AOA (inside teal, outside amber) and the dissimilarity index.
Choose the output folder and a file prefix, tick the outputs and press Write outputs: the model card (HTML with KaTeX), the run manifest (JSON), the CV predictions (CSV: observed, predicted, interval and fold of every held-out prediction, per model and design) and the layers (GeoPackage: samples with CV predictions, fold polygons, local coefficients). Replay manifest takes a manifest written by this plugin, rebuilds the table, checks the hashes, refits and compares the metrics, and shows a pass or fail card with any mismatch.
Settings lists the optional packages (found, version, not found) with the copyable install command and Check again, the default seed (one NumPy generator per random step) and the run folder for harmonised rasters and predictions. Help gives a short guide, the method references and links to this manual, the repository and GeoStats Lab.
Point samples read the covariate value of the cell under the point, or the mean of the cells whose centre lies within the point buffer. The radius is in ground metres also when the template raster is geographic (degrees) or in feet: it is converted with the length of one degree of longitude and latitude on the WGS 84 ellipsoid at the sample, or with the linear unit. Polygon samples take the mean (or the majority, for categorical covariates and on request) of the cells whose centre lies inside the polygon, or the value at the centroid. Each kept sample is placed at its point or polygon centroid in the working CRS. Rows with a NULL target, a NULL attribute covariate or nodata in any raster are dropped and counted by reason. Categorical covariates are stored as integer codes \(0,\dots,L-1\) of their sorted levels; trees split on the codes, while OLS, GWR and MGWR expand them to one-hot columns with the first level dropped. A level not seen in training gets the code \(-1\).
The empirical semivariogram uses the Matheron estimator in 15 distance classes up to half the largest sample distance, where \(N(h)\) is the number of pairs in class \(h\):
Matheron semivariogram
\[\hat{\gamma}(h) = \frac{1}{2N(h)} \sum_{\lVert s_i - s_j \rVert \in h} \left(z_i - z_j\right)^2 \tag{1}\]A spherical and an exponential model with nugget \(c_0\), partial sill \(c\) and practical range \(a\) are fitted,
\[\gamma_{\mathrm{sph}}(h) = c_0 + c\left(\tfrac{3h}{2a} - \tfrac{h^3}{2a^3}\right) \text{ for } h \le a,\qquad \gamma_{\mathrm{exp}}(h) = c_0 + c\left(1 - e^{-3h/a}\right), \tag{2}\]by the weighted least squares of Cressie (1985), and the model with the lower residual is kept:
Cressie weighted least squares
\[\min_{\theta} \sum_k N(h_k)\left(\frac{\hat{\gamma}(h_k)}{\gamma(h_k;\theta)} - 1\right)^2 \tag{3}\]The variogram is computed on the target and on the OLS residuals. The practical range of the residual variogram (of the target for classification) is the default block size and buffer radius (Roberts et al. 2017; Valavi et al. 2019): samples closer than the range are correlated, so testing on them overstates accuracy.
| Design | Rule | Reference |
|---|---|---|
| Random k-fold | samples assigned to \(k\) folds at random | - |
| Spatial blocks | square grid of side \(s\) anchored at the minimum of the sample extent (so a translation of all coordinates gives the same folds); whole blocks are dealt to \(k\) folds by a seeded greedy balance of the sample counts | Valavi et al. 2019 |
| Hexagonal blocks | the same with hexagons of area \(s^2\) | Valavi et al. 2019 |
| Coordinate clusters | k-means++ on the coordinates into \(k\) clusters, one fold each | Brenning 2012 |
| Buffered leave-one-out | each sample \(i\) is tested alone; its training set excludes every sample within radius \(r\) of \(i\) | Le Rest et al. 2014; Pohjankukka et al. 2017 |
| kNNDM | \(k\)-fold assignment from a hierarchical clustering of the coordinates whose cut minimises \(W\) (equation (4)) between the CV distances and the prediction distances | Linnenbrink et al. 2024 |
kNNDM follows CAST::knndm: the number of clusters is searched on 100 log-spaced values from \(k\) to \(n-2\); clusters are ordered along the first principal axis of their centroids, clusters larger than \(n/k\) are kept whole and the rest are dealt round-robin to the folds, with no fold above half of the samples. When a one-sided Kolmogorov-Smirnov test does not show that the prediction distances exceed the sample distances, the samples already cover the prediction area and random k-fold is returned (the log says so).
Three empirical cumulative distribution functions of nearest-neighbour distances are compared (Milà et al. 2022): sample to nearest other sample, \(\hat{G}_j\); prediction location to nearest sample, \(\hat{G}_{ij}\); and test sample to nearest training sample under the design, \(\hat{G}^{*}_{j}\). Prediction locations are the valid cells of the template raster (a regular subsample of at most 20 000 cells) or the centroids of the prediction layer. A design whose \(\hat{G}^{*}_{j}\) lies on \(\hat{G}_{ij}\) tests at the distances the map predicts at. The gap is the Wasserstein-1 distance (in metres):
Wasserstein distance between distance distributions
\[W = \int_0^{\infty} \left|\hat{G}_{ij}(d) - \hat{G}^{*}_{j}(d)\right|\,\mathrm{d}d \tag{4}\]Random k-fold on clustered samples gives a \(\hat{G}^{*}_{j}\) far to the left of \(\hat{G}_{ij}\) and a large \(W\); spatial designs move it right. \(W\) is reported for every design run.
All five models are fitted on the same folds. In the formulas \(X\) is the \(n \times k\) design matrix (with intercept), \(y\) the target, \(T\) the number of trees and \(\alpha = 1 -\) the interval level.
Fitted by QR decomposition, with adjusted \(R^2\), AICc and the VIF per covariate; the prediction interval is analytic:
Ordinary least squares
\[\hat{\beta} = (X^\top X)^{-1} X^\top y,\qquad \hat{y}_0 \pm t_{1-\alpha/2,\,n-k}\, s\sqrt{1 + x_0^\top (X^\top X)^{-1} x_0} \tag{5}\]Every other model must beat this baseline under the spatial design to be worth its complexity.
Bootstrap samples, \(m_{\mathrm{try}} = \lceil p/3 \rceil\) covariates per split for regression and \(\lceil \sqrt{p}\, \rceil\) for classification, minimum leaf size 5 (regression) or 1 (classification), 300 trees, squared-error or Gini impurity. Splits are searched on at most 64 quantile bins per covariate (histogram builder, as in LightGBM, Ke et al. 2017); categorical codes are split after ordering the levels by their mean target (Fisher 1958). The out-of-bag score is reported; impurity importance is reported but not used for ranking.
Random forest
\[\hat{f}(x) = \frac{1}{T}\sum_{t=1}^{T} f_t(x) \tag{6}\]Intervals come from the quantile regression forest (Meinshausen 2006): each in-bag sample \(i\) gets a weight from the leaves \(L_t(x)\) that \(x\) falls into, with \(c_{ti}\) its bootstrap count in tree \(t\), and the interval bounds are quantiles of the weighted distribution of \(y\):
Quantile regression forest weights
\[w_i(x) = \frac{1}{T}\sum_{t=1}^{T} \frac{c_{ti}\,\mathbf{1}[i \in L_t(x)]}{\sum_{j} c_{tj}\,\mathbf{1}[j \in L_t(x)]},\qquad \hat{F}(y \mid x) = \sum_i w_i(x)\,\mathbf{1}[y_i \le y] \tag{7}\]For classes the probability is the mean leaf class share, and the uncertainty is the normalised entropy \(H(x) = -\sum_{c} p_c \ln p_c / \ln C\) of the \(C\) class probabilities.
Squared-error or binary logistic loss with gradients \(g_i\) and Hessians \(h_i\), Newton leaf values, shrinkage \(\nu = 0.05\), depth 4, subsample 0.8, \(\lambda = 1\) and the number of rounds chosen by early stopping on an inner split that respects the outer design (Friedman 2001, 2002). Multiclass boosting is not available; a target with more than two classes is refused for this model.
Gradient boosting with Newton leaves
\[F_m(x) = F_{m-1}(x) + \nu\,\gamma_{l(x)},\qquad \gamma_l = \frac{\sum_{i \in l} g_i}{\sum_{i \in l} h_i + \lambda} \tag{8}\]Gradient boosting, GWR and MGWR get split-conformal intervals from the absolute cross-validation residuals \(|r|\) under the chosen design (Lei et al. 2018). The half-width \(q\) is the \(\lceil (n+1)(1-\alpha) \rceil\)-th smallest absolute residual:
Split-conformal interval
\[\hat{y} \pm q,\qquad q = |r|_{(\lceil (n+1)(1-\alpha) \rceil)} \tag{9}\]When \(\lceil (n+1)(1-\alpha) \rceil > n\) the interval is unbounded and is written as NULL (nodata), never as infinity. The guarantee assumes exchangeable residuals, which spatial autocorrelation can break; the model card states this caveat.
Geographically weighted regression (Brunsdon, Fotheringham & Charlton 1996; Fotheringham et al. 2002) fits a local regression at every location \(u_i\). The default kernel is adaptive bisquare with \(d_k\) the distance to the \(k\)-th nearest neighbour; the alternative is the fixed Gaussian kernel \(w_{ij} = \exp\!\left(-\tfrac{1}{2}(d_{ij}/b)^2\right)\) with bandwidth \(b\) in metres.
Geographically weighted regression
\[\hat{\beta}(u_i) = (X^\top W_i X)^{-1} X^\top W_i y,\qquad w_{ij} = \left(1 - (d_{ij}/d_{k})^2\right)^2 \mathbf{1}[d_{ij} < d_{k}] \tag{10}\]The bandwidth is chosen by golden-section search on the corrected AIC (Hurvich, Simonoff & Tsai 1998), where \(S\) is the hat matrix, or on the CV score:
Corrected AIC for GWR
\[\mathrm{AIC_c} = 2n\ln\hat{\sigma} + n\ln 2\pi + n\,\frac{n + \operatorname{tr}S}{n - 2 - \operatorname{tr}S} \tag{11}\]Outputs per location: coefficients, local \(t\)-values judged against the adjusted \(\alpha\) of da Silva & Fotheringham (2016), local \(R^2\) and the condition number. Prediction at new locations uses the same kernel on the training samples. Regression only.
Multiscale GWR (Fotheringham, Yang & Kang 2017; Oshan et al. 2019) gives each covariate \(j\) its own bandwidth \(b_j\). \(X\) and \(y\) are standardised; back-fitting updates one term at a time with a golden-section AICc search per term until the score of change falls below \(10^{-5}\) or 200 iterations are reached (the model card states whether it converged). Each term's bandwidth is searched between 42 neighbours (\(40 + 2k\) with \(k = 1\), as PySAL mgwr) and \(n\); the MGWR minimum bandwidth raises that lower bound. With clustered samples a kernel that stays inside one cluster makes the intercept and the slopes nearly collinear, and back-fitting then creeps towards the tolerance without reaching it: on the demo landscape (400 samples in 8 clusters of 50, a one-hot categorical covariate) the default bound stops at 200 iterations, while a bound of 100 neighbours (two clusters) converges. Loading the demo sets 100; the model card states the bound used. Covariate effective numbers of parameters and standard errors use the operator method of Yu et al. (2020) for the refit on all samples (\(n \le 3\,000\)); coefficients are on the standardised scale.
Multiscale GWR
\[y_i = \sum_{j=0}^{k} \beta_{b_j j}(u_i)\, x_{ij} + \varepsilon_i \tag{12}\]Small documented grids are evaluated with nested cross-validation, so the reported score never sees the test fold: inside each outer training set an inner design of the same kind (\(k = 3\) folds by default) scores every grid point. Grids: random forest \(m_{\mathrm{try}} \in \{\lceil\sqrt{p}\,\rceil, \lceil p/3\rceil, \lceil p/2\rceil\}\) and minimum leaf size \(\in \{1, 5, 10\}\) (100 trees while tuning); gradient boosting depth \(\in \{2, 4, 6\}\) and \(\nu \in \{0.03, 0.1\}\) (at most 300 rounds while tuning); GWR kernel \(\in\) {adaptive bisquare, fixed Gaussian}. kNNDM uses coordinate clusters as the inner design, and so do blocks when there are too few blocks; buffered leave-one-out is not tuned (defaults, logged). The final hyperparameters are the grid point with the lowest mean inner loss over the outer folds; the random-CV comparison uses them without nesting.
All metrics are computed on the pooled held-out predictions. Regression: \(\mathrm{RMSE} = \sqrt{\tfrac{1}{n}\sum_i (y_i - \hat{y}_i)^2}\), \(\mathrm{MAE} = \tfrac{1}{n}\sum_i |y_i - \hat{y}_i|\), bias \(= \tfrac{1}{n}\sum_i (\hat{y}_i - y_i)\) (mean error),
Coefficient of determination
\[R^2 = 1 - \frac{\sum_i (y_i - \hat{y}_i)^2}{\sum_i (y_i - \bar{y})^2} \tag{13}\]and Lin's concordance correlation between observed and predicted values (Lin 1989):
Lin's concordance correlation
\[\rho_c = \frac{2 s_{xy}}{s_x^2 + s_y^2 + (\bar{x} - \bar{y})^2} \tag{14}\]Classification: accuracy, balanced accuracy (mean recall over classes), Cohen's \(\kappa\), macro \(F_1\), log loss \(-\tfrac{1}{n}\sum_i \ln \hat{p}_{i,y_i}\) and Brier score \(\tfrac{1}{n}\sum_i \sum_c (\hat{p}_{ic} - \mathbf{1}[y_i = c])^2\). The interval coverage is the share of held-out values inside the nominal interval. Residual Moran's \(I\) (Moran 1950) uses 8 nearest neighbours with row-standardised weights \(w_{ij}\), \(S_0 = \sum_i\sum_j w_{ij}\), residuals \(z_i\) centred on their mean, and a 999-permutation seeded \(p\)-value:
Moran's I of residuals
\[I = \frac{n}{S_0}\,\frac{\sum_i \sum_j w_{ij} z_i z_j}{\sum_i z_i^2} \tag{15}\]The optimism gap (Ploton et al. 2020) is the difference between the spatial-CV and the random-CV error of the same model and hyperparameters:
Optimism gap
\[\Delta = \mathrm{RMSE}_{\text{spatial CV}} - \mathrm{RMSE}_{\text{random CV}} \tag{16}\]A positive gap means random cross-validation overstates the map accuracy. Spatial cross-validation estimates the error of predicting at the distances of the chosen design; it is not a design-based estimate of map accuracy (Wadoux et al. 2021).
For each covariate \(j\) and each test fold, the covariate is permuted inside the test fold and the increase of the held-out loss \(L\) (RMSE, or log loss for classes) is averaged over \(R\) repeats (Breiman 2001; Fisher, Rudin & Dominici 2019). It is computed on held-out data under the chosen design, so it describes what the model uses to predict new places. Whiskers show the spread over folds.
Permutation importance
\[I_j = \frac{1}{R}\sum_{r=1}^{R} \left[L\big(y, f(X^{(j,r)})\big) - L\big(y, f(X)\big)\right] \tag{17}\]Exact path-dependent TreeSHAP (Lundberg et al. 2020, Algorithm 2) for the random forest and gradient boosting gives Shapley values \(\phi_j(x)\) that add up to the model output with the base value \(\phi_0\) (local accuracy):
SHAP local accuracy
\[f(x) = \phi_0 + \sum_{j=1}^{p} \phi_j(x) \tag{18}\]To keep the cost bounded it runs on a stratified subset of rows (500 by default) and on the first trees of the ensemble (100 by default); the model card states the numbers used. For OLS and GWR the linear SHAP value is exact (Lundberg & Lee 2017):
Linear SHAP
\[\phi_j(x) = \beta_j(u)\,(x_j - \bar{x}_j) \tag{19}\]Partial dependence (Friedman 2001) sets covariate \(j\) to a grid value \(z\) for every sample and averages the predictions; ICE curves (Goldstein et al. 2015) show the same for 100 single samples:
Partial dependence
\[\bar{f}_j(z) = \frac{1}{n}\sum_{i=1}^{n} f(z, x_{i,-j}) \tag{20}\]Accumulated local effects (Apley & Zhu 2020) accumulate the mean finite differences inside quantile bins \((z_{k-1}, z_k]\) with \(n_k\) samples, centred by \(c\) to mean zero. They stay valid when covariates are correlated (VIF above 5), where partial dependence evaluates the model on unrealistic combinations:
Accumulated local effects
\[\hat{f}_j(z) = \sum_{k=1}^{k(z)} \frac{1}{n_k}\sum_{i:\,x_{ij} \in (z_{k-1}, z_k]} \left[f(z_k, x_{i,-j}) - f(z_{k-1}, x_{i,-j})\right] - c \tag{21}\]For GWR and MGWR the explanations also include the local coefficient layer (section 14).
Following Meyer & Pebesma (2021) and CAST, covariates are scaled by the training mean and standard deviation and multiplied by weights \(w_j\), the permutation importances of the model (negative values set to 0; equal weights if none is positive). The dissimilarity index of a location is the distance to the nearest training sample in this weighted space, divided by the mean distance \(\bar{d}\) between training samples. For the training samples themselves the nearest sample is searched outside the sample's own CV fold, so the AOA changes when the design changes. The threshold is the upper whisker of the training DI, capped at its maximum: \(\min(Q_3 + 1.5\,\mathrm{IQR},\ \max \mathrm{DI}_{\mathrm{train}})\), with type-7 quantiles as in R.
Dissimilarity index
\[\mathrm{DI}(x) = \frac{\min_i d(x, x_i)}{\bar{d}},\qquad \text{AOA} = \{x : \mathrm{DI}(x) \le Q_3 + 1.5\,\mathrm{IQR}\} \tag{22}\]Inside the AOA the cross-validation error applies; outside it the model extrapolates into covariate combinations it has not seen and the map should not be read.
Raster prediction reads the harmonised stack in windows of tile \(\times\) tile cells; a cell with nodata in any covariate is nodata in every output. Outputs are Float32 GeoTIFFs (deflate, tiled) on the template grid. Regression: mean, lower, upper, width (upper minus lower). Classification: class (Int16), prob_max, entropy. With the AOA option: di, aoa (Byte: 1 inside, 0 outside, 255 nodata) and the prediction masked to the AOA, mean_aoa (regression) or class_aoa (classification), whose cells outside the AOA are nodata: the map to publish, as Meyer & Pebesma (2021) recommend. The dock shows the masked map on top and keeps the full prediction, on the same colour scale, hidden below it. Layer prediction writes the same values as fields of a copy of the layer (section 14).
The model card is one self-contained HTML file in the structure of Mitchell et al. (2019): intended use, data (samples kept and dropped, covariates, working CRS and grid), validation design with the distance diagnostics, the leaderboard with the optimism gap, explanations, the AOA share, limitations (including the caveat of Wadoux et al. 2021) and every reference. Its formulas are typeset with the bundled KaTeX and use the same LaTeX as this manual, so it renders offline.
The run manifest (JSON, schema docs/manifest.schema.json) records the plugin, QGIS, Python, NumPy and GDAL versions; the working CRS and template grid; the SHA-256 hash of the sample table and of each harmonised raster (first 64 MB, size and header); every parameter and seed; the fold vector and block rings of each design; the chosen and per-fold hyperparameters; and the metrics. The sample table is saved beside it as <name>.table.npz, so studies built from memory layers replay too. Replay reloads the table, checks the hashes, reruns every recorded cross-validation with the recorded folds, seeds and per-fold hyperparameters and compares every metric: exact equality for the native engines, \(10^{-9}\) relative for scikit-learn. Any difference is listed by name.
Provider 02SpatialML. Every algorithm calls the same core functions as the dock. Inputs are copied into private memory layers; results go to feature sinks with real field types (doubles keep full precision in GeoPackage) and to GeoTIFF files in an output folder; outputs are not styled by the algorithms. Model objects pass between algorithms as a run manifest path. Each algorithm's help panel in QGIS repeats its method summary and references. Parameters marked advanced are under Advanced parameters; optional parameters may stay empty.
Shared parameter groups, used by several algorithms:
The whole study in one run, through the same staged functions as the dock: sample table and harmonised stack, variogram, the chosen design plus random k-fold with distance diagnostics, every chosen model cross-validated on the same folds (nested tuning) and refitted, permutation importance, TreeSHAP of the best tree model, PDP / ICE / ALE of the best model, GWR / MGWR local coefficients, prediction on the raster grid or a layer with interval, DI and AOA, the run manifest and, when a path is given, the model card. Models that do not support the task are skipped and logged. Sections 5 to 12.
| Parameter | Label | Type | Default |
|---|---|---|---|
SAMPLES | Samples (points or polygons) | vector layer | |
TARGET | Target field | field | |
COV_FIELDS | Covariate fields (attribute table) optional | field | |
RASTERS | Covariate rasters optional | layers | |
CATEGORICAL | Categorical covariates (comma-separated names) optional | text | |
TASK | Task advanced | choice: Detect from the target field; Regression; Classification | Detect from the target field |
POLYGON_STAT | Polygon samples: covariate value advanced | choice: Cell mean; Cell majority; Value at the centroid | Cell mean |
POINT_BUFFER | Point samples: mean within this radius (m, 0 = cell value) advanced | number, at least 0 | 0 |
SCHEME | Validation design | choice: Random k-fold; Spatial blocks; Hexagonal blocks; Coordinate clusters; Buffered leave-one-out; kNNDM | Spatial blocks |
K | Folds k | number, 2 to 100 | 5 |
SIZE | Block size (m, 0 = variogram range) | number, at least 0 | 0 |
RADIUS | Buffered LOO radius (m, 0 = variogram range) advanced | number, at least 0 | 0 |
PREDICTION_LAYER | Prediction locations for kNNDM (optional; default: valid raster cells) optional | vector layer | |
SEED | Random seed advanced | number, at least 0 | 42 |
MODELS | Models | choice (several): OLS baseline; Random forest; Gradient boosting; GWR; MGWR | OLS baseline, Random forest, Gradient boosting, GWR |
TUNE | Tune hyperparameters by nested cross-validation | yes / no | yes |
ENGINE | Random forest engine advanced | choice: Native (numpy); scikit-learn (when installed) | Native (numpy) |
MGWR_MIN_BW | MGWR minimum bandwidth (neighbours, 0 = default 42) advanced | number, 0 to 10000 | 0 |
COMPARE_RANDOM | Also run random k-fold (optimism gap) | yes / no | yes |
REPEATS | Permutation repeats advanced | number, 1 to 100 | 10 |
SHAP_ROWS | TreeSHAP rows advanced | number, 10 to 50000 | 500 |
SHAP_TREES | TreeSHAP trees advanced | number, 1 to 5000 | 100 |
PREDICT_ON | Predict on | choice: Covariate raster grid; Prediction layer; Nothing | Covariate raster grid |
PREDICT_LAYER | Prediction layer optional | vector layer | |
INTERVAL | Interval level | number, 0.5 to 0.99 | 0.9 |
AOA | Dissimilarity index and area of applicability | yes / no | yes |
TILE | Tile size (cells) advanced | number, 16 to 8192 | 512 |
AGGREGATE | GWR / MGWR aggregation factor advanced | number, 1 to 10 | 1 |
OUTPUT_FOLDER | Run folder | folder output | |
SAMPLES_OUT | Cross-validated samples (best model) | vector output | |
LEADERBOARD | Leaderboard | vector output | |
FOLDS | Fold polygons optional | vector output | |
LOCAL | Local coefficients (GWR / MGWR) optional | vector output | |
PREDICTED | Prediction layer with predictions optional | vector output | |
REPORT | Model card (HTML) optional | file output |
Further outputs:
| Output | Meaning |
|---|---|
BEST | Best model |
MANIFEST | Run manifest |
AOA_SHARE | Share inside the AOA |
MEAN | Prediction (mean) |
LOWER | Interval lower bound |
UPPER | Interval upper bound |
WIDTH | Interval width |
CLASS | Predicted class |
PROB_MAX | Largest class probability |
ENTROPY | Normalised entropy |
DI | Dissimilarity index |
AOA_RASTER | Area of applicability |
MEAN_AOA | Prediction inside the AOA |
CLASS_AOA | Predicted class inside the AOA |
Reads the target and every covariate at the samples (section 5) and writes one point per kept sample in the working CRS (section 3). Rows dropped are counted by reason in the log.
| Parameter | Label | Type | Default |
|---|---|---|---|
SAMPLES | Samples (points or polygons) | vector layer | |
TARGET | Target field | field | |
COV_FIELDS | Covariate fields (attribute table) optional | field | |
RASTERS | Covariate rasters optional | layers | |
CATEGORICAL | Categorical covariates (comma-separated names) optional | text | |
TASK | Task advanced | choice: Detect from the target field; Regression; Classification | Detect from the target field |
POLYGON_STAT | Polygon samples: covariate value advanced | choice: Cell mean; Cell majority; Value at the centroid | Cell mean |
POINT_BUFFER | Point samples: mean within this radius (m, 0 = cell value) advanced | number, at least 0 | 0 |
SEED | Random seed advanced | number, at least 0 | 42 |
OUTPUT | Sample table | vector output |
Further outputs:
| Output | Meaning |
|---|---|
N_SAMPLES | Samples kept |
N_DROPPED | Samples dropped |
N_COVARIATES | Covariates |
TASK_DETECTED | Task |
WORKING_CRS | Working CRS |
Resamples covariate rasters onto the grid of a template raster with GDAL Warp (bilinear; nearest neighbour for the rasters named as categorical). Rasters already on the grid are returned unchanged.
| Parameter | Label | Type | Default |
|---|---|---|---|
RASTERS | Covariate rasters | layers | |
TEMPLATE | Template raster (empty: the first raster) optional | raster layer | |
CATEGORICAL | Categorical rasters (comma-separated names) optional | text | |
OUTPUT_FOLDER | Output folder | folder output |
Further outputs:
| Output | Meaning |
|---|---|
OUTPUT | Harmonised rasters |
RESAMPLED | Rasters resampled |
The Matheron variogram of a numeric field with spherical and exponential fits, equations (1) to (3) (section 6).
| Parameter | Label | Type | Default |
|---|---|---|---|
SAMPLES | Samples (points or polygons) | vector layer | |
FIELD | Field | field | |
N_LAGS | Distance classes | number, 3 to 100 | 15 |
MAX_DIST | Largest distance (m, 0 = half the largest sample distance) | number, at least 0 | 0 |
MODEL | Model | choice: Better of spherical and exponential; Spherical; Exponential | Better of spherical and exponential |
OUTPUT | Variogram | vector output |
Further outputs:
| Output | Meaning |
|---|---|
MODEL_CHOSEN | Model |
NUGGET | Nugget |
SILL | Sill |
RANGE | Practical range (m) |
Builds the folds of one design (section 7) and, when prediction locations are given, the Wasserstein distance \(W\) of the design. A size or radius of 0 takes the practical range of the variogram of the chosen field.
| Parameter | Label | Type | Default |
|---|---|---|---|
SAMPLES | Samples (points or polygons) | vector layer | |
SCHEME | Validation design | choice: Random k-fold; Spatial blocks; Hexagonal blocks; Coordinate clusters; Buffered leave-one-out; kNNDM | Spatial blocks |
K | Folds k | number, 2 to 100 | 5 |
SIZE | Block size (m, 0 = variogram range) | number, at least 0 | 0 |
RADIUS | Buffered LOO radius (m, 0 = variogram range) | number, at least 0 | 0 |
FIELD | Variogram field (for a 0 size or radius) optional | field | |
PREDICTION_RASTER | Prediction raster (valid cells) optional | raster layer | |
PREDICTION_LAYER | Prediction layer (centroids) optional | vector layer | |
SEED | Random seed advanced | number, at least 0 | 42 |
OUTPUT | Samples with folds | vector output | |
BLOCKS | Fold polygons optional | vector output |
Further outputs:
| Output | Meaning |
|---|---|
FOLDS | Folds |
W | Wasserstein distance to the prediction distances (m) |
SIZE_USED | Block size or radius used (m) |
NOTE | Design |
The three nearest-neighbour distance distributions of section 7 for an existing fold field (or buffered LOO with a radius) and the Wasserstein distance between them.
| Parameter | Label | Type | Default |
|---|---|---|---|
SAMPLES | Samples (points or polygons) | vector layer | |
FOLD_FIELD | Fold field optional | field | fold |
RADIUS | Buffered LOO radius (m, 0 = use the fold field) | number, at least 0 | 0 |
PREDICTION_RASTER | Prediction raster (valid cells) optional | raster layer | |
PREDICTION_LAYER | Prediction layer (centroids) optional | vector layer | |
POINTS | Curve points advanced | number, 10 to 2000 | 100 |
OUTPUT | Distance curves | vector output |
Further outputs:
| Output | Meaning |
|---|---|
W_CV | W between prediction and CV distances (m) |
W_SAMPLE | W between prediction and sample distances (m) |
MEDIAN_PREDICTION | Median prediction-to-sample distance (m) |
MEDIAN_CV | Median CV test-to-training distance (m) |
Cross-validates one model (section 8) under the design and, optionally, under random k-fold with the same hyperparameters, so the optimism gap is visible (section 9). The model is refitted on all samples; the run manifest can be saved for replay.
| Parameter | Label | Type | Default |
|---|---|---|---|
SAMPLES | Samples (points or polygons) | vector layer | |
TARGET | Target field | field | |
COV_FIELDS | Covariate fields (attribute table) optional | field | |
RASTERS | Covariate rasters optional | layers | |
CATEGORICAL | Categorical covariates (comma-separated names) optional | text | |
TASK | Task advanced | choice: Detect from the target field; Regression; Classification | Detect from the target field |
POLYGON_STAT | Polygon samples: covariate value advanced | choice: Cell mean; Cell majority; Value at the centroid | Cell mean |
POINT_BUFFER | Point samples: mean within this radius (m, 0 = cell value) advanced | number, at least 0 | 0 |
SCHEME | Validation design | choice: Random k-fold; Spatial blocks; Hexagonal blocks; Coordinate clusters; Buffered leave-one-out; kNNDM | Spatial blocks |
K | Folds k | number, 2 to 100 | 5 |
SIZE | Block size (m, 0 = variogram range) | number, at least 0 | 0 |
RADIUS | Buffered LOO radius (m, 0 = variogram range) advanced | number, at least 0 | 0 |
PREDICTION_LAYER | Prediction locations for kNNDM (optional; default: valid raster cells) optional | vector layer | |
SEED | Random seed advanced | number, at least 0 | 42 |
MODEL | Model | choice: OLS baseline; Random forest; Gradient boosting; GWR; MGWR | Random forest |
TUNE | Tune hyperparameters by nested cross-validation | yes / no | no |
ENGINE | Random forest engine advanced | choice: Native (numpy); scikit-learn (when installed) | Native (numpy) |
MGWR_MIN_BW | MGWR minimum bandwidth (neighbours, 0 = default 42) advanced | number, 0 to 10000 | 0 |
COMPARE_RANDOM | Also run random k-fold (optimism gap) | yes / no | yes |
INTERVAL | Interval level | number, 0.5 to 0.99 | 0.9 |
OUTPUT | Cross-validated samples | vector output | |
LEADERBOARD | Scores optional | vector output | |
MANIFEST | Run manifest optional | file output |
Further outputs:
| Output | Meaning |
|---|---|
RMSE | RMSE |
MAE | MAE |
R2 | R squared |
BIAS | Bias (mean error) |
CCC | Lin's concordance correlation |
ACCURACY | Accuracy |
BALANCED_ACCURACY | Balanced accuracy |
KAPPA | Cohen's kappa |
MORAN_I | Residual Moran's I |
COVERAGE | Interval coverage |
OPTIMISM_GAP | Optimism gap |
Cross-validates one model, refits it and explains it (section 10): permutation importance on held-out folds, TreeSHAP for tree models, PDP and ALE curves, local coefficients for GWR / MGWR.
| Parameter | Label | Type | Default |
|---|---|---|---|
SAMPLES | Samples (points or polygons) | vector layer | |
TARGET | Target field | field | |
COV_FIELDS | Covariate fields (attribute table) optional | field | |
RASTERS | Covariate rasters optional | layers | |
CATEGORICAL | Categorical covariates (comma-separated names) optional | text | |
TASK | Task advanced | choice: Detect from the target field; Regression; Classification | Detect from the target field |
POLYGON_STAT | Polygon samples: covariate value advanced | choice: Cell mean; Cell majority; Value at the centroid | Cell mean |
POINT_BUFFER | Point samples: mean within this radius (m, 0 = cell value) advanced | number, at least 0 | 0 |
SCHEME | Validation design | choice: Random k-fold; Spatial blocks; Hexagonal blocks; Coordinate clusters; Buffered leave-one-out; kNNDM | Spatial blocks |
K | Folds k | number, 2 to 100 | 5 |
SIZE | Block size (m, 0 = variogram range) | number, at least 0 | 0 |
RADIUS | Buffered LOO radius (m, 0 = variogram range) advanced | number, at least 0 | 0 |
PREDICTION_LAYER | Prediction locations for kNNDM (optional; default: valid raster cells) optional | vector layer | |
SEED | Random seed advanced | number, at least 0 | 42 |
MODEL | Model | choice: OLS baseline; Random forest; Gradient boosting; GWR; MGWR | Random forest |
TUNE | Tune hyperparameters by nested cross-validation | yes / no | no |
ENGINE | Random forest engine advanced | choice: Native (numpy); scikit-learn (when installed) | Native (numpy) |
MGWR_MIN_BW | MGWR minimum bandwidth (neighbours, 0 = default 42) advanced | number, 0 to 10000 | 0 |
REPEATS | Permutation repeats | number, 1 to 100 | 10 |
FEATURES | Effect covariates (comma-separated, empty = six most important) optional | text | |
GRID | Partial dependence grid points advanced | number, 5 to 200 | 25 |
SHAP_ROWS | TreeSHAP rows advanced | number, 10 to 50000 | 500 |
SHAP_TREES | TreeSHAP trees advanced | number, 1 to 5000 | 100 |
IMPORTANCE | Permutation importance | vector output | |
EFFECTS | Effect curves optional | vector output | |
SHAP | SHAP values optional | vector output | |
LOCAL | Local coefficients (GWR / MGWR) optional | vector output |
Further outputs:
| Output | Meaning |
|---|---|
TOP | Most important covariate |
Cross-validates one model, refits it on all samples and predicts every cell of the covariate grid tile by tile, with interval, DI and AOA (section 11). The run manifest is written into the output folder.
| Parameter | Label | Type | Default |
|---|---|---|---|
SAMPLES | Samples (points or polygons) | vector layer | |
TARGET | Target field | field | |
RASTERS | Covariate rasters | layers | |
CATEGORICAL | Categorical covariates (comma-separated names) optional | text | |
TASK | Task advanced | choice: Detect from the target field; Regression; Classification | Detect from the target field |
POLYGON_STAT | Polygon samples: covariate value advanced | choice: Cell mean; Cell majority; Value at the centroid | Cell mean |
POINT_BUFFER | Point samples: mean within this radius (m, 0 = cell value) advanced | number, at least 0 | 0 |
SCHEME | Validation design | choice: Random k-fold; Spatial blocks; Hexagonal blocks; Coordinate clusters; Buffered leave-one-out; kNNDM | Spatial blocks |
K | Folds k | number, 2 to 100 | 5 |
SIZE | Block size (m, 0 = variogram range) | number, at least 0 | 0 |
RADIUS | Buffered LOO radius (m, 0 = variogram range) advanced | number, at least 0 | 0 |
SEED | Random seed advanced | number, at least 0 | 42 |
MODEL | Model | choice: OLS baseline; Random forest; Gradient boosting; GWR; MGWR | Random forest |
TUNE | Tune hyperparameters by nested cross-validation | yes / no | no |
ENGINE | Random forest engine advanced | choice: Native (numpy); scikit-learn (when installed) | Native (numpy) |
MGWR_MIN_BW | MGWR minimum bandwidth (neighbours, 0 = default 42) advanced | number, 0 to 10000 | 0 |
INTERVAL | Interval level | number, 0.5 to 0.99 | 0.9 |
AOA | Dissimilarity index and area of applicability | yes / no | yes |
TILE | Tile size (cells) advanced | number, 16 to 8192 | 512 |
AGGREGATE | GWR / MGWR aggregation factor advanced | number, 1 to 10 | 1 |
OUTPUT_FOLDER | Output folder | folder output |
Further outputs:
| Output | Meaning |
|---|---|
MEAN | Prediction (mean) |
LOWER | Interval lower bound |
UPPER | Interval upper bound |
WIDTH | Interval width |
CLASS | Predicted class |
PROB_MAX | Largest class probability |
ENTROPY | Normalised entropy |
DI | Dissimilarity index |
AOA_RASTER | Area of applicability |
MEAN_AOA | Prediction inside the AOA |
CLASS_AOA | Predicted class inside the AOA |
AOA_SHARE | Share of cells inside the AOA |
MANIFEST | Run manifest |
RMSE | RMSE |
MAE | MAE |
R2 | R squared |
BIAS | Bias (mean error) |
CCC | Lin's concordance correlation |
ACCURACY | Accuracy |
BALANCED_ACCURACY | Balanced accuracy |
KAPPA | Cohen's kappa |
MORAN_I | Residual Moran's I |
COVERAGE | Interval coverage |
The dissimilarity index and the AOA on the covariate grid (section 11), with the permutation importance of a model under the design as weights, or equal weights. Also writes the training samples with their DI.
| Parameter | Label | Type | Default |
|---|---|---|---|
SAMPLES | Samples (points or polygons) | vector layer | |
TARGET | Target field | field | |
RASTERS | Covariate rasters | layers | |
CATEGORICAL | Categorical covariates (comma-separated names) optional | text | |
TASK | Task advanced | choice: Detect from the target field; Regression; Classification | Detect from the target field |
POLYGON_STAT | Polygon samples: covariate value advanced | choice: Cell mean; Cell majority; Value at the centroid | Cell mean |
POINT_BUFFER | Point samples: mean within this radius (m, 0 = cell value) advanced | number, at least 0 | 0 |
SCHEME | Validation design | choice: Random k-fold; Spatial blocks; Hexagonal blocks; Coordinate clusters; Buffered leave-one-out; kNNDM | Spatial blocks |
K | Folds k | number, 2 to 100 | 5 |
SIZE | Block size (m, 0 = variogram range) | number, at least 0 | 0 |
RADIUS | Buffered LOO radius (m, 0 = variogram range) advanced | number, at least 0 | 0 |
SEED | Random seed advanced | number, at least 0 | 42 |
WEIGHTS | Covariate weights | choice: Permutation importance of the model; Equal weights | Permutation importance of the model |
MODEL | Model | choice: OLS baseline; Random forest; Gradient boosting; GWR; MGWR | Random forest |
TUNE | Tune hyperparameters by nested cross-validation | yes / no | no |
ENGINE | Random forest engine advanced | choice: Native (numpy); scikit-learn (when installed) | Native (numpy) |
MGWR_MIN_BW | MGWR minimum bandwidth (neighbours, 0 = default 42) advanced | number, 0 to 10000 | 0 |
REPEATS | Permutation repeats advanced | number, 1 to 100 | 10 |
TILE | Tile size (cells) advanced | number, 16 to 8192 | 512 |
OUTPUT_FOLDER | Output folder | folder output | |
TRAINING | Training samples with DI optional | vector output |
Further outputs:
| Output | Meaning |
|---|---|
DI | Dissimilarity index |
AOA_RASTER | Area of applicability |
THRESHOLD | DI threshold |
AOA_SHARE | Share of cells inside the AOA |
Replays a run manifest (section 12): checks the hashes, reruns every recorded cross-validation and compares every metric.
| Parameter | Label | Type | Default |
|---|---|---|---|
MANIFEST | Run manifest | file | |
OUTPUT | Replayed metrics optional | vector output |
Further outputs:
| Output | Meaning |
|---|---|
OK | Replay passed (1) or failed (0) |
MISMATCHES | Mismatches |
DETAILS | Mismatch details |
| Output | Fields or bands |
|---|---|
| Sample table | fid, target, one field per covariate (raw values; categorical levels as their value) |
| Samples (CV) / cross-validated samples | the sample table plus fold (buffered LOO: the row number; \(-1\) never tested), cv_pred, residual (observed minus predicted), lower, upper; classes: cv_class, prob_max |
| Fold polygons | block squares or hexagons, or cluster hulls, with fold |
| Distance curves | distance (m), g_sample, g_prediction, g_cv |
| Variogram | lag (m), gamma (semivariance), npairs, fitted (model value at the lag) |
| Leaderboard / scores | model, scheme, params (JSON of the hyperparameters) and one field per metric: rmse, mae, r2, bias, ccc, accuracy, balanced_accuracy, kappa, macro_f1, log_loss, brier, moran_i_residual, moran_p, coverage |
| Permutation importance | covariate, mean, std, rank |
| Effect curves | kind (pdp or ale), feature, class, x, value |
| SHAP values | fid, class, base, output, one phi_ field per covariate |
| Local coefficients (GWR, MGWR) | fid, b_<term> per term (one-hot terms as c4_2), t_<term> when standard errors are available, and for GWR local_r2 and cond (condition number) |
| Prediction rasters | mean.tif, lower.tif, upper.tif, width.tif or class.tif, prob_max.tif, entropy.tif; di.tif, aoa.tif, mean_aoa.tif or class_aoa.tif (the prediction masked to the AOA) |
| Prediction layer | the layer's own fields plus pred_mean, pred_lower, pred_upper, pred_width, pred_di, aoa; classes: pred_class, pred_prob_max, pred_entropy |
| Replayed metrics | run (model:design), metric, saved, replayed, equal |
Load demo landscape on the Data page builds a deterministic synthetic study (seed 7) in EPSG:32635, with the origin at (500 000, 4 250 000) so that coordinates are far from the projection origin. The grid has \(240 \times 240\) cells of 50 m (12 km by 12 km) and five covariate rasters:
c1: a smooth west-east trend, \(c_1 = 3u/L + 0.2\sin(\pi v/H)\), with \(u, v\) the cell coordinates from the north-west corner and \(L = H = 12\) km;c2, c3: standardised Gaussian random fields with practical ranges 1.5 km and 4 km; in the eastern third c3 is shifted by \(+8\) standard deviations, outside every sampled value (a planted extrapolation zone);c4: four classes from the quartiles of a third random field (categorical);c5: pure noise, which no model should use.The target has a planted spatially varying coefficient \(\beta_1(u) = 1 + 2u/L\), a spatially correlated term \(\varepsilon_s\) (range 3 km, standard deviation 0.5) and noise \(\varepsilon \sim N(0, 0.3^2)\):
\[y = 2 + 3\sin(\pi c_2) + \beta_1(u)\,c_1 + 1.5\,\mathbf{1}[c_4 = 2] + \varepsilon_s + \varepsilon\]The 400 samples lie in 8 clusters of radius 700 m spread over the western two thirds, so random k-fold tests a sample next to its own cluster while the map must predict up to several kilometres away.
Tick c4 as categorical and press Run whole study (defaults: spatial blocks, \(k = 5\), size from the variogram, random k-fold for comparison, OLS, random forest, gradient boosting and GWR with nested tuning, 90 % intervals, AOA). On a desktop i7-13700 under QGIS 3.44 the run takes about two minutes, most of it the nested tuning of the random forest. The numbers below are those of this run.
tests/fixtures/reference_v1/metrics.json). For a map of the whole landscape, kNNDM or coordinate clusters are the designs that mimic the prediction task.| Model | Tuned parameters | RMSE blocks | RMSE random | Gap | \(R^2\) blocks | CCC blocks | 90 % coverage blocks | Moran's \(I\) blocks |
|---|---|---|---|---|---|---|---|---|
| Gradient boosting | depth 2, \(\nu = 0.1\) | 0.764 | 0.588 | 0.176 | 0.893 | 0.939 | 0.898 | 0.32 |
| Random forest | \(m_{\mathrm{try}} = \lceil\sqrt{p}\,\rceil\), min leaf 1 | 1.000 | 0.717 | 0.283 | 0.816 | 0.886 | 0.905 | 0.35 |
| OLS | - | 2.415 | 2.167 | 0.247 | \(-0.07\) | 0.115 | 0.880 | 0.55 |
| GWR | adaptive bisquare | 2.439 | 2.049 | 0.390 | \(-0.09\) | 0.163 | 0.900 | 0.47 |
c2 2.01, c1 0.48, c4 0.42, c3 0.28, c5 \(-0.001\). The noise covariate gets no importance and the planted \(\sin(\pi c_2)\) term ranks first. TreeSHAP ran on all 400 samples with the first 100 of the 382 boosting rounds. The PDP of c2 follows the planted sine: maxima near \(c_2 = -1.5\) and \(c_2 = 0.5\), minima near \(c_2 = -0.4\) and \(c_2 = 1.4\). ALE is drawn for the continuous covariates; the categorical c4 has PDP and ICE only. The GWR local coefficient layer (bandwidth 214 neighbours, AICc 1 700.6) carries one b_ field per term. On this landscape c1 is itself a west-east trend, so its local coefficient cannot be separated from the local intercept and b_c1 does not trace \(\beta_1(u)\); the recovery of a planted coefficient field by GWR is checked on a separate problem in the test suite.c3 there lies beyond every training value and c3 carries importance weight; in the western two thirds 82 % of the cells are inside.In Processing, the same study is one call of Spatial machine learning lab (whole study) with the demo samples, target y, the five rasters and c4 as categorical covariate.
Eminoğlu, Y. (2026). 02SpatialML - Spatial Machine Learning Lab (version 0.1.1) [QGIS plugin]. https://gitlab.com/geophilo1/zero2spatialml. https://doi.org/10.5281/zenodo.24263652. The DOI 10.5281/zenodo.24263652 always resolves to the latest version; version 0.1.1 has DOI https://doi.org/10.5281/zenodo.24263653. Please also cite the references of the designs, models and explanations you use.
Licence: GPL-2.0-or-later. Copyright (C) 2026 Yusuf Eminoğlu (Geophilo). KaTeX (bundled in resources/katex) is MIT licensed.
Repository: gitlab.com/geophilo1/zero2spatialml · Issues: work items · Homepage: geophilo.com/zero2spatialml