Skip to contents

K-Fold Observed-Support Prediction Diagnostics

cos_cv_observed.Rd

Runs Gaussian K-fold validation for observed-support prediction targets. Each fold refits the model to the training observed supports and predicts the held-out supports using cos_predict_areal. By default, it scores observed-support responses with nugget variation included. In simulation studies, it can also score latent held-out means when latent truth is supplied.

Usage

cos_cv_observed(fit, X_rast, B_sf = NULL, response_col = NULL,
  y_B = NULL, target = "observed", latent_col = NULL, k = 10L,
  fold_id = NULL, missing = c("error", "drop", "renormalize"),
  row_sum_tol = 1e-5, fit_args = list(), recover_args = list(),
  seed = NULL, keep_fits = FALSE, verbose = TRUE)

Arguments

fit

A "cos_fit" object. The fitted object is used as the model template: spatial/non-spatial status, taper settings, priors, and sampler defaults are inherited from it.

X_rast

A raster RasterLayer, RasterStack, or RasterBrick containing fine-support covariates.

B_sf

Optional sf polygon object containing observed-support polygons. If NULL, fit$prep$B_sf is used.

response_col

Optional name of the response column in B_sf.

y_B

Optional numeric response vector. If supplied, this is used instead of response_col. If neither y_B nor response_col is supplied, fit$prep$y_B is used.

target

Prediction target or targets to score. "observed" scores support responses with nugget variation included against held-out y_B. "latent" scores latent means against B_sf[[latent_col]]. Supply c("observed", "latent") to score both targets from the same fold fits.

latent_col

Name of the latent truth column in B_sf. Required when target includes "latent". This is mainly for simulation studies where latent eta_B is known.

k

Number of folds.

fold_id

Optional integer vector assigning each observed unit to a fold in 1:k. If NULL, folds are generated at random.

missing

How to handle incomplete raster covariate cells in training or held-out supports. Passed to cos_prepare and cos_make_areal_blocks.

row_sum_tol

Tolerance used when checking support-weight row sums.

fit_args

Named list of additional arguments passed to cos_fit. Values supplied here override sampler defaults inherited from fit.

recover_args

Named list of additional arguments passed to cos_recover_B.

seed

Optional seed used for random fold assignment and default per-fold fit/recovery seeds.

keep_fits

Logical; if TRUE, keep fitted fold models in the returned object.

verbose

Logical; if TRUE, print fold progress.

Details

Held-out observed supports are treated as areal prediction units. The function does not automatically propagate the family, trial counts, size, or offsets of a non-Gaussian fit to fold refits. Use this workflow for Gaussian models. The function uses cos_predict_areal(spatial_uncertainty = "marginal", keep_samples = TRUE) to draw latent areal means. For target = "observed", it then adds independent nugget draws with variance tau_sq * sum(h^2) for each held-out support, where h contains the held-out support's fine-cell area weights.

For target = "latent", the latent areal mean samples are scored against B_sf[[latent_col]]. This target is useful in simulation studies for separating recovery of the underlying support mean from prediction of the support response with nugget variation included.

The CRPS is computed from posterior predictive samples using the empirical scoring rule $$CRPS(F, y) = E_F |Y - y| - \frac{1}{2} E_F |Y - Y'|.$$

This function is intended for model assessment and simulation studies rather than lightweight examples. For simulation-based checks, generate data with cos_simulate_data and pass the simulated B_sf and X_rast to this function after fitting a model to the simulated data.

Value

A list with class "cos_cv_observed" containing:

  • summary: overall RMSPE, CRPS, coverage, interval width, and error summaries. A target column is included.

  • fold_summary: fold-level diagnostics and selected parameter medians, by target.

  • predictions: held-out predictions, intervals, CRPS, errors, and coverage indicators, by target.

  • fold_id: fold assignments.

  • fits: optional fitted fold models when keep_fits = TRUE.

  • timing: named numeric vector with user, system, and elapsed seconds.

Examples

if (FALSE) { # \dontrun{
cv <- cos_cv_observed(
  fit = fit,
  X_rast = X_rast,
  k = 10,
  fit_args = list(n_batch = 50, batch_length = 8),
  recover_args = list(burn_in = 100, n_samples = 60),
  seed = 1
)

summary(cv)
cv$predictions
} # }