Cross-validate a model that adds a spatial random field to its fixed predictors. A spatial random field is a smooth surface of spatially correlated variation that the predictors do not explain. In each fold the function estimates the field, its correlation range, the regression coefficients, and optionally the scales of effect from the analysis rows. It then scores the joint distribution of each held-out block, so that correlation among nearby held-out observations counts. Gaussian responses use exact Gaussian conditioning at the fitted parameters. Count, binary, and positive responses use Laplace integration.
Usage
cross_validate_field(
formula,
data,
coords,
folds,
audit_dir,
crs = NULL,
covariance = c("exponential", "gaussian"),
kernel_inputs = NULL,
optim_args = list(),
control = list(iter.max = 1000L, eval.max = 1500L, rel.tol = 1e-10, x.tol = 1e-08),
metrics = c("rmse", "mae", "neg_log_score"),
max_refits = 200L,
max_memory_mb = 512,
keep_fits = FALSE,
family = c("gaussian", "poisson", "binomial", "nbinom2", "Gamma")
)Arguments
- formula
Two-sided fixed-effects formula whose response is a numeric column of
data. Products, interactions, factors, offsets, and the data-dependent termsscale(),poly(),splines::ns(), andsplines::bs()keep their usual meanings, with their constants learned from the analysis rows. Do not add random effects or penalized smooths, because the function adds the one shared field itself.- data
Data frame of raw responses and predictors, with unique row names that match the fold IDs, in the same row order as
coords. Supply raw predictors, not transformations learned from all rows. Every row has a case weight of one.- coords
Locations of the observations, one per row of
data, as projectedsfpoints, aterra::SpatVectorof points, or a numeric two-column table. Rows with identical coordinates share one field value, so repeated surveys of a location are linked.- folds
Named list of explicit splits, usually from
spatial_cv_folds(). A location cannot appear in both the analysis and the assessment rows of one split, so keep repeated surveys of a location together. Rows excluded from a split, for example by a buffer, enter neither its fit nor its score.- audit_dir
Directory where compact, write-once records of each native fit and its starting values are saved, one subfolder per fold. Records of failed fits are kept too. No models, tapes, or dense covariance matrices are saved. Give each candidate model its own directory to keep the records apart.
- crs
Projected coordinate reference system, in any form accepted by
sf::st_crs(). It is required whencoordsis a coordinate table. The defaultNULLuses the CRS of spatialcoords, which must be projected, and a suppliedcrsmust match it. Coordinates are never transformed, so the correlation range is reported in the CRS units.- covariance
Correlation function of the field, either
"exponential"(default), with correlation exp(-d / range) at distance d, or"gaussian", with correlation exp(-(d / range)^2). The range and the field SD are estimated in every fold, as is the observation dispersion for Gaussian, NB2, and Gamma models.- kernel_inputs
Optional
multiScaleR_dataobject fromkernel_prep()with the cell-level data kept and row names matchingdata. The defaultNULLfits a field model without estimating scales. When it is supplied, each fold also estimates the scales of the optimized covariates that appear informula(list them withmsr_vars()) by refitting the field model.- optim_args
Named list of extra
multiScale_optim()arguments for the scale fit, used only withkernel_inputs. The default is an empty list. This function fixes the backend ("refit"), the data, the refit function, and the single worker, so those cannot be replaced.- control
Named list of native
nlminb()optimizer settings for each field fit. Accepted names areiter.max,eval.max,rel.tol,x.tol, andabs.tol, each a positive number. The defaults areiter.max = 1000,eval.max = 1500,rel.tol = 1e-10, andx.tol = 1e-8. The settings are stored with each fit, and the convergence and curvature checks apply whatever they are.- metrics
Scores to record, any of
"rmse","mae", and"neg_log_score"(all three by default). The negative log score uses one joint density, or one joint probability for counts and 0/1 data, per assessment block. The pooled score sums the block losses and divides by the number of assessment observations.- max_refits
Positive whole number, the most native refits allowed in one fold during the scale search (default 200). Each refit checks two starting values. A fold that exceeds the budget fails.
- max_memory_mb
Positive number, a conservative budget in MiB for the covariance calculations of one fold (default 512), checked before any fitting. Repeated surveys at one location share one field value, so they do not enlarge the training covariance matrix. This is a planning check, not an operating-system memory limit.
- keep_fits
Logical.
TRUEkeeps the complete training model of each fold infits. The defaultFALSEsaves memory. The compact training records thatselect_cv()reads are kept either way.- family
Response family and link. Use
"gaussian"(identity, the default) for continuous observations,"poisson"or"nbinom2"(log) for counts,"binomial"(logit) for numeric 0/1 observations, or"Gamma"(log) for strictly positive continuous observations. All families other than"gaussian"are experimental.
Value
A list of class multiScaleR_field_cv, which inherits from
multiScaleR_cv. summary holds the pooled scores, predictions the
predicted mean, errors, and variance components of each held-out
observation, joint_scores the joint loss of each held-out block, and
training the field SD, correlation range (in coordinate units),
dispersion, and coefficients of each fold. Compact selection_records
are always kept. The spatial field section of multiScaleR_cv
describes every element and its scale.
Details
The count, binary, and positive response families are experimental. Their arguments and results may change in a later release without a deprecation period.
What each fold estimates
The native fits use glmmTMB and TMB with maximum likelihood. The model has
one shared latent Gaussian field with exponential or Gaussian correlation,
and a constant observation dispersion where the family has one. From the
analysis rows each fold estimates the regression coefficients, the field
SD, the correlation range, the observation dispersion, and, with
kernel_inputs, the scales of effect. Distance bins, standardization, and
the constants of learned formula terms also come from the analysis rows
only. Custom preprocessing that depends on the data must be learned inside
each training fold too, because formula evaluation cannot detect outside
information passed in through your own functions. No missing rows are
dropped silently.
The correlation range is the distance, in coordinate units, over which the unexplained variation stays correlated. It is separate from the kernel scale of effect, which describes how far the landscape around a point affects it.
Every fit tries two deterministic starting values chosen from the training
data and records the package versions, convergence, marginal score, and
curvature checks of each. For Gaussian responses both starts must pass and
agree, or the fold fails. For the other families the passing start with
the highest likelihood is used, and the outcome of each start is kept.
With few locations in a training fold, the field's standard deviation and
range are often weakly identified, and the two Gaussian starts can stop at
different points of a nearly flat likelihood. Those folds fail by design
("starts disagree") rather than report one arbitrary solution. Use more
locations per fold, or fewer folds, and inspect audit_dir to see how far
apart the starts ended.
Build folds for a field model
Hold out complete locations, so that no location has observations in both
parts of a split. Spatial blocks with a buffer test prediction at new
places. The field locations in coords can differ from the focal points
used for the landscape covariates, but each location must be given by its
actual, consistent coordinates, and coords is required even when
kernel_inputs is supplied. A template that compares two correlation
functions on the same folds:
folds <- spatial_cv_folds(field_xy, block_size = 10000, k = 5,
buffer = 1000, crs = 32617, ids = rownames(raw_data))
covariances <- c(exponential = "exponential", gaussian = "gaussian")
candidates <- lapply(covariances, function(covariance) {
cross_validate_field(y ~ habitat * cover + offset(log(exposure)),
raw_data, field_xy, folds, crs = 32617, covariance = covariance,
kernel_inputs = inputs,
audit_dir = file.path("field-cv-audits", covariance))
})
cv_tab(candidates, metric = "neg_log_score")
selected <- select_cv(candidates, criterion = "AICc")
selected$selection$chosen # chosen by the training criterion in each foldHow the joint score works
The negative log score treats the held-out observations of each fold as one block. For Gaussian responses it is the negative log of one multivariate normal density. Its covariance holds the field variation that remains after conditioning on the analysis responses, plus the observation noise. For the other families the score is the Laplace log marginal likelihood of the analysis responses alone minus that of the analysis and assessment responses together. Both calculations use parameters estimated from the analysis rows only, including the field covariance, coefficients, dispersion, and scales, so the score keeps the dependence among held-out locations and repeated observations. For counts and 0/1 data, a block probability above one beyond numerical roundoff is recorded as a failed score.
The pooled score is the total block loss divided by the number of
assessment observations, and smaller is better. RMSE and MAE summarize the
errors of the predicted response means. Multiplying separate marginal
densities would ignore the field dependence and define a different score,
so cv_tab() keeps these scores apart from the per-observation scores of
ordinary GLMs.
Predicted means and spreads
For 0/1 responses, predicted means and observation SDs integrate over a Gaussian approximation to the field given the analysis responses. For log-link families, the first two response moments come from Laplace ratios of exponentially tilted analysis likelihoods, with two additional latent solves per distinct assessment location and the training covariance factor held fixed. This improves the accuracy of the moments in low-dimensional numerical comparisons, particularly for sparse observations with strong fields. The joint block score uses its own integration.
observation_predictive_SE combines the conditional observation noise
with the variation of the response mean. For a nonlinear link, square it
to get the total response variance. The two field variance columns
describe the field on the linear-predictor scale. All of these condition
on the estimated parameters. Use them as predictive spreads for new
observations, not as standard errors of the predicted mean.
Check calibration separately
A scored fold has an eligible native fit and a valid score. It does not show that the predictive spreads are reliable. Assess that on the held-out locations, and count failed folds in the denominator when you report how often the method succeeds. In simulations with buffered held-out locations, squared prediction errors averaged 1.5 (Gaussian), 2.7 (Poisson), and 1.9 (NB2) times the predicted observation variance, against 1 for a calibrated prediction. Treat the returned spreads as optimistic when parameters are estimated.
Compare and select field models
Use cv_tab() to rank field results fitted to the same responses, folds,
and coordinates. Poisson and NB2 results share a count target. Use
select_cv() to score a training AIC, AICc, or BIC rule from the compact
records. The coefficients, field SD, estimated range, and any observation
dispersion count toward K, while the integrated field values add nothing.
Field scores do not integrate parameter or scale uncertainty and do not
establish calibration. vignette("v08-cross-validation", package = "multiScaleR") explains fold design and how to read the scores, and
vignette("v11-spatial-fields", package = "multiScaleR") covers spatial
field models.
Examples
# \donttest{
if (requireNamespace("glmmTMB", quietly = TRUE)) {
data("landscape_counts")
data("surv_pts")
xy <- crds(vect(surv_pts)) # simulated coordinates in meters
folds <- spatial_cv_folds(xy, block_size = 1000, k = 3, crs = 32617)
# Poisson counts with a site covariate and an exponential field. The
# Poisson family is experimental.
field_cv <- cross_validate_field(counts ~ site, landscape_counts, xy,
folds, audit_dir = file.path(tempdir(), "field-cv"), crs = 32617,
family = "poisson")
print(field_cv) # the log score is a joint score per held-out survey
# Field SD (log-link scale) and correlation range (m) in each fold
print(sapply(field_cv$training, function(fold)
unlist(fold$parameters[c("field_SD", "range")])))
}
#> Cross-validation: 3 of 3 folds scored; 100 of 100 input rows assessed.
#> metric estimate n_assessment unit complete
#> rmse 1.760629 100 response TRUE
#> mae 1.328896 100 response TRUE
#> neg_log_score 1.703037 100 joint_block_mass_per_observation TRUE
#> fold1 fold2 fold3
#> field_SD 0.9617028 0.812557 0.8259306
#> range 1346.5835180 624.511124 859.2548280
# }
