% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/graph_crossval.R
\name{cross_validation}
\alias{cross_validation}
\title{Perform cross-validation on a list of fitted inlabru models on metric graphs.}
\usage{
cross_validation(
  models,
  model_names = NULL,
  scores = c("mae", "mse", "crps", "scrps", "dss"),
  cv_type = c("k-fold", "loo", "lpo"),
  weight_thr = NULL,
  k = 5,
  percentage = 20,
  number_folds = 10,
  n_samples = 1000,
  return_scores_folds = FALSE,
  orientation_results = c("negative", "positive"),
  include_best = TRUE,
  train_test_indexes = NULL,
  return_train_test = FALSE,
  return_post_samples = FALSE,
  return_true_test_values = FALSE,
  parallelize_RP = FALSE,
  n_cores_RP = parallel::detectCores() - 1,
  true_CV = TRUE,
  save_settings = FALSE,
  model_options_bru = list(),
  print = TRUE,
  fit_verbose = FALSE
)
}
\arguments{
\item{models}{A fitted model from \code{inlabru::bru()} or a list of such models.
All models must have the same number of likelihoods and be fitted to
identical datasets.}

\item{model_names}{Character vector of model names. Defaults to \code{names(models)}
or \verb{Model 1}, \verb{Model 2}, ... if absent.}

\item{scores}{Subset of \code{c("mae", "mse", "crps", "scrps", "dss", "wcrps", "swcrps")}.}

\item{cv_type}{One of \code{"k-fold"}, \code{"loo"}, \code{"lpo"}.}

\item{weight_thr}{Threshold for \code{wcrps} / \code{swcrps}. Required if either is requested.}

\item{k}{Number of folds for \code{k-fold}.}

\item{percentage}{Train percentage (1-99) for \code{lpo}.}

\item{number_folds}{Number of folds for \code{lpo}.}

\item{n_samples}{Number of posterior samples for sample-based scoring.}

\item{return_scores_folds}{If \code{TRUE}, return per-fold score matrices.}

\item{orientation_results}{One of \code{"negative"} (lower is better) or
\code{"positive"} (higher is better).}

\item{include_best}{Add a \code{Best} row indicating the best model per score.}

\item{train_test_indexes}{Optional pre-built fold list. If supplied,
\code{cv_type}, \code{k}, \code{percentage}, \code{number_folds} are ignored.}

\item{return_train_test}{Return the train/test indices used.}

\item{return_post_samples}{Return posterior response samples (forces
\code{return_scores_folds = TRUE}).}

\item{return_true_test_values}{Return the true response values at test points.}

\item{parallelize_RP}{Parallelize CRPS/SCRPS pairwise integrals.}

\item{n_cores_RP}{Number of cores for \code{parallelize_RP}.}

\item{true_CV}{If \code{TRUE}, refit the model on each training fold; if \code{FALSE},
sample directly from the supplied fit without refitting.}

\item{save_settings}{If \code{TRUE}, return the CV settings used.}

\item{model_options_bru}{List of options passed to inlabru.}

\item{print}{Print partial progress.}

\item{fit_verbose}{Pass \code{verbose} through to INLA when refitting.}
}
\value{
Either a \code{data.frame} (default), or a list with \code{scores_df} plus the
optional components requested by \verb{return_*} / \code{save_settings} arguments.
}
\description{
Mirrors \code{\link[rSPDE:cross_validation]{rSPDE::cross_validation()}} for \code{bru} fits (output from \code{inlabru::bru()}),
with built-in support for the exact, non-FEM SPDE models in
\pkg{MetricGraph} (objects of class \code{inla_metric_graph_spde}). For models
fit with such a component, the function rebuilds the SPDE on a graph clone
with held-out responses set to NA, refits when \code{true_CV = TRUE}, and draws
posterior samples via the \code{inlabru::generate} path used by
\code{\link{predict.inla_metric_graph_spde}}. For models without a metric-graph SPDE
component (e.g. FEM-based rSPDE models), it uses the standard
\code{inlabru::bru_set_missing()} + \code{bru_rerun()} + \code{inlabru::generate()} path
shared with \code{\link[rSPDE:cross_validation]{rSPDE::cross_validation()}}.
}
