% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/spectra-ingest.R
\name{benchmark_spectral_fill}
\alias{benchmark_spectral_fill}
\title{Benchmark the accuracy lift of spectral gap-fill (ON vs OFF), k-fold}
\usage{
benchmark_spectral_fill(
  reflectance,
  metadata,
  id_col = "id",
  system = c("sibcs", "wrb2022", "usda"),
  profile_col = NULL,
  folds = 5L,
  properties = NULL,
  method = c("mbl", "plsr_local", "pretrained"),
  wavelengths = NULL,
  resample_to = NULL,
  property_map = NULL,
  label_map = NULL,
  normalize = c("auto", "none", "percent"),
  fold_id = NULL,
  verbose = TRUE
)
}
\arguments{
\item{reflectance}{Reflectance data: a matrix / data.frame with rows =
samples and columns named by wavelength (nm); OR a long data.frame with
\code{id_col}, \code{wavelength_nm}, \code{reflectance}; OR a path to a
CSV in either form.}

\item{metadata}{A data.frame with one row per sample carrying \code{id_col}
plus lab attributes and optional taxonomic labels and \code{lat}/
\code{lon}. Rows are aligned to \code{reflectance} by \code{id_col}.}

\item{id_col}{Sample identifier column shared by both tables (default
\code{"id"}).}

\item{system}{One of \code{"sibcs"} (default), \code{"wrb2022"}, \code{"usda"}.}

\item{profile_col}{Column grouping samples into profiles (default \code{id_col}).}

\item{folds}{Number of CV folds (default 5).}

\item{properties}{Attributes to predict from spectra (default the
\code{\link{fill_from_spectra}} set).}

\item{method}{Spectral model: \code{"mbl"}, \code{"plsr_local"} or
\code{"pretrained"} (passed to \code{\link{fill_from_spectra}}).}

\item{wavelengths}{Optional explicit wavelength vector (nm) when the
reflectance columns are not wavelength-named.}

\item{resample_to}{Optional target wavelength grid (nm) to linearly resample
every spectrum onto (e.g. \code{350:2500}); default keeps the native grid.}

\item{property_map, label_map}{Optional named lists overriding the alias
auto-detection, e.g. \code{property_map = list(clay_pct = "ARGILA")}.}

\item{normalize}{One of \code{"auto"} (divide by 100 when values look like
percent), \code{"percent"}, or \code{"none"}.}

\item{fold_id}{Optional integer vector (one per profile, in sorted-id order)
to use fixed folds instead of the deterministic modulo split.}

\item{verbose}{Print a one-line summary (default \code{TRUE}).}
}
\value{
A list with \code{accuracy_off}, \code{accuracy_on}, \code{delta},
        \code{n}, per-fold rows, and the per-profile \code{predictions} frame.
}
\description{
The honest measurement that has been data-blocked until a spectra-bearing,
labelled dataset exists. For each cross-validation fold it calibrates a
spectral library on the training profiles, then classifies the held-out
profiles twice -- \strong{OFF} (spectra-only pedon, no lab attributes) and
\strong{ON} (\code{\link{fill_from_spectra}} predicts the lab attributes from
the scan first) -- and scores both against the reference label. Non-circular:
the calibration library never includes a test profile.
}
\seealso{
\code{\link{read_spectral_library}}, \code{\link{fill_from_spectra}}
}
