Troubleshooting and performance
Justin Chase
Source:vignettes/troubleshooting.Rmd
troubleshooting.RmdThis article lists the messages you are most likely to meet, what
each means and what to do about it. It then covers large layers and long
runs: the work limits, parallel folds, the two caches and the log.
?"spatialkit-conditions" lists every warning and error
class the package raises, with the fields a handler can read.
Each message below is quoted as R prints it, up to the point where it starts to vary. Angle brackets stand for the names and counts that differ from call to call.
A layer for the examples
Two examples below run on a simulated layer: 300 points over a 20 km square in UTM zone 32N, whose unit is the metre.
suppressPackageStartupMessages(library(sf))
library(spatialkit)
set.seed(1)
n <- 300
pts <- st_as_sf(data.frame(x = 5e5 + runif(n, 0, 20000),
y = 5e6 + runif(n, 0, 20000)),
coords = c("x", "y"), crs = 32632)
pts$w <- rnorm(n)
pts$z <- 2 * pts$w + rnorm(n)
st_crs(pts)$units_gdal
#> [1] "metre"Messages you are likely to meet
Preparing the data
build_tessellation(): `boundary` is required for hex/square grids.-
A hex or square grid has no extent of its own. Pass
boundary =a polygon of the study area:st_union()of your source polygons is one way to get it, andclip_target_for()builds the bounding box of the points. Voronoi cells and"triangles"do not need a boundary, since they take their extent from the points, or fromcoverwhen the points are seeds. prep_model_data(): missing required column(s): <names>-
A name in
response_varorpredictor_varsis not a column of the data. The usual causes are a typo, a difference in case, or a column thatread.csv()renamed undercheck.names = TRUE(pop densitybecomespop.density). Checknames(data_sf). The geometry column is not a predictor. prep_model_data(): column name(s) '<names>' are not syntactically valid R names-
Every backend builds a formula from the column names, and a name such as
B5-B4orband 4does not survive that. Rename the columns before fitting, for example withnames(x) <- make.names(names(x)). prep_model_data(): response '<name>' is also listed in 'predictor_vars'.-
A model cannot use its own response as a predictor, and none of the
backends would stop it, so
prep_model_data()refuses the call before any fit. Drop the response frompredictor_vars.
Fitting a model
fit_rf_model(): response '<name>' is not numeric.-
The random forest and GWR backends fit a regression, so they refuse a
logical, factor or character response. The GWR message starts
fit_gwr_model(): response '<name>' is not numeric (it is <class>).A number read from a file as text needsas.numeric()first; check for a thousands separator or an"NA"string if that givesNAs.fit_gwr_model()also refuses a response with two whole-number values, and namesGWmodel::ggwr.basic()for it.fit_bayesian_spatial_model()takes a factor or character response underbrms::categorical()or an ordinal family, and refuses it under any other family with a message that startsfit_bayesian_spatial_model(): response '<name>' is <class>, not numeric. fit_rf_model(): `num.trees` is already set by this function and cannot be passed through `...` as well-
ranger’s own spelling of an argument that
fit_rf_model()sets would reachranger::ranger()twice. Use the wrapper’s spelling, which the message names, and it passes the value on, for examplenum_treesfornum.treesorsample_fractionforsample.fraction.cv_rf()andcompare_models_cv(rf_args = )pass their arguments tofit_rf_model(), so the same rule applies there.
Units and distances
Distances, bandwidths and block sizes are in the units of the CRS a
function works in. When one looks absurd, check that unit first with
st_crs(x)$units_gdal. A block size of 1,000 meant in metres
is about 305 m on a layer in US survey feet, and a layer in lon/lat is
moved into a projected CRS that ensure_projected() chooses,
whose unit is the metre. ?"spatialkit-geometry" gives the
rules, and vignette("getting-started") shows them on a real
layer.
make_folds(block_kfold): the requested grid is <nx> x <ny> = <n> cells, above the 1,000,000 this function will build.-
A
block_sizein the wrong unit asks for a grid far finer than meant. The message gives the extent and the CRS unit to compare it with:# A block size of 10, meant in kilometres, on a layer in metres. # The message is wrapped to fit the page. tryCatch( make_folds(pts, k = 5, method = "block_kfold", block_size = 10), error = function(e) writeLines(strwrap(conditionMessage(e), 76)) ) #> make_folds(block_kfold): the requested grid is 1959 x 1988 = 3,894,492 #> cells, above the 1,000,000 this function will build. Check that #> `block_size` (10) is expressed in the data's CRS units (metre) over an #> extent of 19590 x 19880; a value in the wrong unit is the usual cause.predict_surface()refuses a grid of more than 5,000,000 cells for the same reason, and “Large layers” below lists the other limits.
Cross-validation
cv_*(): all folds failed (all <n> folds failed to produce predictions); cross-validation results contain no predictions.-
The call returns with this warning,
$overallallNAandn_pred = 0, and the log line of each fold names its cause. A missing backend is one cause:cv_bayes()without brms fails every fold this way, whilecv_rf()andcv_gwr()stop at once when ranger or sp is missing. A fit that stops on one fold’s training rows fails that fold the same way. Here the learner stops on every fold:folds <- make_folds(pts, k = 5, method = "block_kfold", seed = 1) cv <- cv_spatial(pts, "z", "w", folds = folds, fit_fn = function(train) stop("the backend is not installed")) #> WARN [2026-11-12 12:26:23] cross-validation: fold 1 fit failed; skipping. Cause: the backend is not installed #> WARN [2026-11-12 12:26:23] cross-validation: fold 2 fit failed; skipping. Cause: the backend is not installed #> WARN [2026-11-12 12:26:23] cross-validation: fold 3 fit failed; skipping. Cause: the backend is not installed #> WARN [2026-11-12 12:26:23] cross-validation: fold 4 fit failed; skipping. Cause: the backend is not installed #> WARN [2026-11-12 12:26:23] cross-validation: fold 5 fit failed; skipping. Cause: the backend is not installed #> Warning: cv_spatial(): all folds failed (all 5 folds failed to produce #> predictions); cross-validation results contain no predictions. First error: the #> backend is not installed c(attempted = cv$n_folds_attempted, succeeded = cv$n_folds_succeeded) #> attempted succeeded #> 5 0 cv$overall #> RMSE MAE MAPE SMAPE R2 Adj_R2 n_pred n_MAPE n_SMAPE #> 1 NA NA NA NA NA NA 0 0 0 cv_*(): <k> of <n> fold(s) failed (<causes>), so `overall` pools the other folds only-
Some folds failed and the rest were scored.
$overallthen pools the folds that ran, and covers fewer rows than the data hold;fold_statusgives the cause of each failure. Everycv_*()result recordsn_folds_attemptedandn_folds_succeeded, so compare the two before you read$overall, on runs that look fine as well. compare_models_cv(): no recognised model requested.-
None of the names in
modelsis"GWR","Bayesian"or"RF", which are matched exactly, case included. The warningignoring unknown model(s)printed with the error names the ones it ignored. compare_models_cv(): no viable models.-
At least one name was recognised, but no recognised backend is
installed. Each prints
dropping <name> (package/function unavailable)before the error, and any name not recognised is named in a warning. Install the backend, or ask for one you have.
Autocorrelation and resolution
-
estimate_sac_range()returnedNA -
The range was not identified, so none is reported.
attr(x, "rejected_reason")says why, and?estimate_sac_rangelists the reasons. When the variogram was computed,plot()on the result (?plot.sac_range) draws it, so you can see why the range was refused. AnNAreturned before the variogram was computed (gstat missing, or fewer than 30 points or locations, for example) carries the reason alone.vignette("spatial-cross-validation")covers choosing a block size. determine_optimal_levels(): the model-aware criteria score only the elbow's neighbourhood, k = <a> to <b>, and carry no information at nine cells or fewer-
A logged warning. Every candidate around the elbow has nine cells or
fewer, where Moran’s I carries no information, so the call falls back to
the geometric ranking. On points with no cluster structure, under
on_no_elbow = "warn", the elbow sits nearsqrt(max_levels), and the neighbourhood reaches ten cells from aboutmax_levels = 40. At the default,on_no_elbow = "na", such points returnNAwith a warning of classspatialkit_no_elbowbefore any neighbourhood is scored. A line logged before the k-means sweep says the same when the ladder itself ends at nine cells or fewer.resolution_profile()scores Moran’s z at every level of its ladder; seevignette("resolution"). determine_optimal_levels(): Moran's I could not be computed at any k from <a> to <b> in the elbow's neighbourhood-
A logged warning. The neighbourhood reaches past nine cells, but too few
cells hold a row with a response and every predictor, the regression of
the cell means on the predictors is singular (a predictor constant or
collinear across cells), or the cell means differ by rounding alone.
Check for missing values first. Under
criterion = "morans_i"the call then falls back to the geometric ranking; under"combined"it ranks the counts as usual, withmoran_iandmoran_zNAin the diagnostics.
Checking a fit
n = <n> requires FNN for k-NN weights, and Matrix to hold them sparsely-
residual_morans_i()on more than 5,000 observations needs FNN to find the neighbours and Matrix to store the weights; without them it would allocate a dense n by n matrix, so it stops instead. FNN installs with spatialkit, so the missing one is usually Matrix:install.packages("Matrix"). The message names the one it could not load.
Large layers
Most steps take time and memory that grow with the rows or the cells. The table lists where a function stops, subsamples or leaves a column out on a large layer. A limit given as an argument is that argument’s default.
| function | limit | at the limit | to change it |
|---|---|---|---|
make_folds(method = "block_kfold"), and the
cv_*() functions that build blocks |
a grid of 1,000,000 blocks | error naming the extent and the CRS unit | a larger block_size in the CRS unit, fewer
block_nx and block_ny, or a smaller
block_multiplier
|
cv_block_size_sweep() |
a grid of 1,000,000 blocks at a size | error for the sizes you pass; a size on the default ladder is dropped, with a log line | larger block_sizes
|
make_folds(method = "nndm") |
5,000 rows | error |
method = "knndm", which has no row limit, or
"block_kfold"
|
predict_surface() |
5,000,000 grid cells | error | a larger cell_size or a smaller n_cells;
chunk_size, 5,000 rows, sets the rows per prediction
call |
create_grid_polygons(), and
build_tessellation() for hex and square cells |
max_cells, 1,000,000 cells, estimated from the bounding
box |
error | a larger cellsize;
create_grid_polygons(max_cells = ) raises the limit, which
build_tessellation() keeps at its default |
residual_morans_i() |
5,000 observations without FNN and Matrix; 20,000,000 weights
(k times the observations) |
error | install Matrix; a smaller k
|
resolution_profile() |
a level with more than 5,000 cells holding a scored row, without FNN and Matrix |
moran_i and moran_z NA at
that level, with a warning of class
spatialkit_moran_skipped
|
install Matrix |
resolution_profile() on a ladder of sizes, the
default |
spatialkit.fit_work_max, 1e10 point-to-centre
comparisons |
error of class spatialkit_work_limit before any
fit |
a smaller nstart, a coarser obs_per_cell,
init = "random", or a higher
spatialkit.fit_work_max
|
searches made without FNN in resolution_profile(),
cell_values_at(), summarize_by_cell() and
select_resolution()
|
spatialkit.exact_pairs_max, 2e9 pairs |
by function: an error, NA pooled columns with a
warning, or the subsample’s centres with a log line |
reinstall FNN, or a higher
spatialkit.exact_pairs_max
|
estimate_sac_range() |
n_max, 5,000 rows |
a seeded random subsample, counted in the attributes
n_used and n_subsampled
|
n_max, or Inf for no limit |
area_of_applicability() |
normalizer_max_n, 5,000 training rows |
the mean pairwise distance is taken on a subsample | normalizer_max_n |
summarize_by_cell(deff = "variogram") |
deff_max_n, 500 points in a cell |
the cell’s correlation matrix is built on a seeded subsample of its points | deff_max_n |
determine_optimal_levels(), and
resolution_profile() on a ladder of counts |
sample_n, 1,500 points |
the k-means fits run on a subsample | sample_n |
fit_bayesian_spatial_model(gp_resolution = ) |
50 basis functions per dimension, 2,500 in all | error giving the basis the range needs | a longer gp_resolution; the cost grows with the square
of gp_k
|
?"spatialkit-options" describes the two options and what
each step does above its limit.
Parallel folds
cv_rf(), cv_bayes() and
cv_spatial() take parallel. TRUE
uses the physical cores less one, or getOption("mc.cores")
when that is lower, and a whole number above 1 uses that many workers,
up to the cores the machine has. The folds then run in forked workers
through parallel::mclapply() on macOS and Linux. On Windows
the call runs them one after another, with a message.
cv_gwr() takes the argument and runs its folds in turn,
with a warning when more than one worker is asked for. Parallel folds
help most in cv_bayes(), where every fold compiles and
samples a Stan model.
cv <- cv_rf(pts, "z", "w", k = 5, parallel = 4L) # four workers
cv <- cv_bayes(pts, "z", "w", k = 5, parallel = TRUE) # detects the coresThe result depends on seed and the fold index alone. The
call draws one seed per fold in the parent process, so
parallel = TRUE returns what parallel = FALSE
returns. With seed = NULL the per-fold seeds come from the
session’s random stream, and set.seed() before the call
makes both runs reproducible.
Caches
The package keeps two results in the session so that it does not compute them twice.
create_grid_polygons_cached() keeps each grid it builds,
keyed on the boundary’s geometry and CRS, the cell count and the other
arguments, and returns the kept grid when the same call comes again. It
holds 50 grids (max_entries) and drops the oldest first;
clear_grid_cache() empties it. Its grids pass through
ensure_stable_poly_id(), which reorders and renumbers the
cells, so the same cell can carry a different poly_id from
create_grid_polygons(). Use one of the two builders
throughout an analysis: a summary keyed on IDs from one and joined to
the geometry of the other can draw the values on the wrong cells.
fitted() on a Bayesian GP fit
(?fitted.bayesian_fit) keeps the posterior expectations it
computes, in an environment the fit carries, because
summary() (?summary.spatial_fit),
residuals() (?residuals.bayesian_fit),
model_metrics() and compare_models() each call
it. clear_fitted_cache(fit) drops them. You need it only
after editing the brmsfit engine in place; a change to
data_sf, or a refit, invalidates the entry on its own.
The log
The package keeps a log through logger, apart from R’s
warnings. Lines at the INFO level and above go to
file.path(tempdir(), "spatialkit_model_log.log"), a file
that lasts as long as the R session, and lines at WARN and above are
also printed to the console. The log has its own
"spatialkit" namespace: it leaves your global
logger configuration alone, and a global configuration set
before the package loads does not carry over into it.
The last line of the file is the warning the failed cross-validation above ended on:
log_file <- file.path(tempdir(), "spatialkit_model_log.log")
# The line is wrapped to fit the page.
writeLines(strwrap(tail(readLines(log_file), 1), 76))
#> WARN [2026-11-12 12:26:23] cv_spatial(): all folds failed (all 5 folds
#> failed to produce predictions); cross-validation results contain no
#> predictions. First error: the backend is not installedspatialkit_quiet() turns the console echo off and
returns the threshold that was in force, which puts it back:
old <- spatialkit_quiet()
spatialkit_quiet(old)The file and the console are two logger appenders, index
1 and index 2. logger::log_appender() and
logger::log_threshold() change index 1, the file, unless
you name index 2. Each line below is a separate choice:
# Write the log file to my_analysis.log (index 1)
logger::log_appender(logger::appender_file("my_analysis.log"),
namespace = "spatialkit")
# Send the console lines to a file instead of the console (index 2)
logger::log_appender(logger::appender_file("my_console.log"),
namespace = "spatialkit", index = 2)
# Or print only FATAL lines on the console (index 2)
logger::log_threshold(logger::FATAL, namespace = "spatialkit", index = 2)A log line is not an R condition: tryCatch(warning = )
does not catch it and suppressWarnings() does not silence
it. “Warnings and log lines” in ?"spatialkit-conditions"
says how the help pages tell the two apart.
knitr does not capture what is written to the console’s error stream,
so while a document is knitted (R Markdown, Quarto, pkgdown) each
console line is also sent as an R message, as the examples above show. A
line the package also raises as an R warning is not repeated, and the
chunk option message = FALSE keeps the rest out of the
document.
Next
vignette("glossary") comes next: short definitions of
the terms the articles and help pages use. This article relied on
?"spatialkit-conditions",
?"spatialkit-options", ?"spatialkit-geometry",
?spatialkit_quiet, ?make_folds,
?cv_spatial, ?compare_models_cv,
?estimate_sac_range,
?determine_optimal_levels, ?residual_morans_i,
?predict_surface, ?create_grid_polygons_cached
and ?clear_fitted_cache.