% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/validate.R
\name{spatial_block_cv}
\alias{spatial_block_cv}
\title{Spatial block cross-validation for suitability model evaluation}
\usage{
spatial_block_cv(
  predicted,
  records,
  presence_col = "presence",
  n_blocks = 5L,
  match_radius_deg = 0.002,
  seed = 42L,
  plot = TRUE,
  verbose = TRUE
)
}
\arguments{
\item{predicted}{Dataframe from \code{\link[=predict_oyster]{predict_oyster()}} containing \code{lat}, \code{lon},
\code{suitability}.}

\item{records}{Dataframe of known presence/absence records. Must contain
\code{lat}, \code{lon}, and a presence/absence column.}

\item{presence_col}{Character. Name of presence/absence column (default
\code{"presence"}).}

\item{n_blocks}{Integer. Number of spatial blocks (default 5). More blocks
= finer spatial resolution but smaller test sets per fold.}

\item{match_radius_deg}{Numeric. Matching radius in degrees (default 0.002
approx. 220 m). Passed to inner matching step.}

\item{seed}{Integer. Random seed for reproducibility (default 42).}

\item{plot}{Logical. Reserved for future visualisation output; currently
unused (default TRUE).}

\item{verbose}{Logical. Print fold-level diagnostics (default TRUE).}
}
\value{
A named list:
\itemize{
\item \code{mean_auc}: mean AUC across blocks (primary reporting metric)
\item \code{auc_sd}: standard deviation of per-block AUC
\item \code{mean_tss}, \code{tss_sd}: mean / SD of True Skill Statistic
\item \code{brier_mean}, \code{brier_sd}: mean / SD of Brier score
\item \code{n_blocks_actual}: number of blocks with >= 5 records (used in CV)
\item \code{fold_results}: dataframe with per-fold metrics
\item \code{spatial_autocorr_range_deg}: estimated autocorrelation range (degrees)
\item \code{spatial_bias_warning}: logical, TRUE if random CV would be misleading
}
}
\description{
Evaluates model performance using spatial block cross-validation (Roberts
et al. 2017), which avoids inflated performance estimates that arise when
nearby train and test records share similar environments.

Records are partitioned into \code{n_blocks} contiguous geographic blocks. In
each fold, one block is held out as test data and the remaining blocks
provide training data to re-score the suitability model. AUC, TSS, and
Brier score are computed per fold and summarised across folds.

This function is purely evaluative -- it does not refit a new model. Instead,
it uses the spatial heterogeneity in the existing \code{predicted} suitability
surface to estimate out-of-block performance.
}
\section{Interpreting results}{

Compare \code{mean_auc} from spatial CV with standard AUC from
\code{\link[=validate_against_records]{validate_against_records()}}. A large drop (> 0.10) indicates strong
spatial autocorrelation and means the model is less transferable than
the standard validation suggested. This is common for coastal surveys
with spatially clustered records.
}

\examples{
\donttest{
records <- read.csv("nbn_ostrea_edulis.csv")
result  <- predict_oyster(survey, "ostrea_edulis")

# Standard validation
std_val <- validate_against_records(result, records)
std_val$auc  # may be optimistically high

# Spatial block CV
sp_cv <- spatial_block_cv(result, records, n_blocks = 5)
sp_cv$mean_auc  # more honest estimate of transferability

# Compare -- if sp_cv$mean_auc << std_val$auc, model is spatially
# autocorrelated and transfers less well than initially apparent.
}
}
\references{
Roberts et al. (2017) Ecography 40:913-929.
doi:10.1111/ecog.02881
}
