% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/benchmark-lucas-2018.R
\name{benchmark_lucas_2018}
\alias{benchmark_lucas_2018}
\title{Run the LUCAS Soil 2018 / ESDB WRB benchmark}
\usage{
benchmark_lucas_2018(
  pedons,
  esdb_root,
  attribute = "WRBLV1",
  fill_texture_from = NULL,
  fill_topsoil_from = c("none", "soilgrids", "spectra"),
  fill_subsoil_from = c("none", "soilgrids"),
  fill_properties = c("clay", "sand", "silt", "phh2o", "soc", "cec", "bdod", "nitrogen",
    "cfvo"),
  ossl_models = NULL,
  classify_with = c("wrb2022", "sibcs"),
  max_n = NULL,
  soilgrids_lookup_fn = lookup_soilgrids,
  verbose = TRUE
)
}
\arguments{
\item{pedons}{List of \code{\link{PedonRecord}} objects, typically
from \code{\link{load_lucas_soil_2018}}.}

\item{esdb_root}{Path to the unpacked ESDB raster directory
(containing the \code{WRBLV1/} sub-folder).}

\item{attribute}{ESDB attribute to use as reference. Default
\code{"WRBLV1"} (Reference Soil Group, 31 codes). Other
sensible choices: \code{"FAO90LV1"} (legacy FAO 1990).}

\item{fill_texture_from}{Deprecated alias for
\code{fill_topsoil_from} (v0.9.49 signature). When
\code{"soilgrids"}, treated as
\code{fill_topsoil_from = "soilgrids"} with
\code{fill_properties = c("clay", "sand", "silt")} and
\code{fill_subsoil_from = "none"}.}

\item{fill_topsoil_from}{One of \code{"none"} (default),
\code{"soilgrids"} (fills topsoil 0-20 cm from SoilGrids
250m at 0-5 cm), or \code{"spectra"} (runs
\code{\link{predict_from_spectra}} with the supplied
\code{ossl_models}; pedons must have
\code{$spectra$vnir} attached, e.g. via
\code{\link{attach_lucas_spectra}}).}

\item{fill_subsoil_from}{One of \code{"none"} (default) or
\code{"soilgrids"} (synthesises a 30-60 cm B horizon from
SoilGrids 250m). Unlocks WRB diagnostic horizons that
depend on subsoil features (cambic, argic, mollic).}

\item{fill_properties}{Character vector of SoilGrids properties
to fill when \code{fill_topsoil_from = "soilgrids"} or
\code{fill_subsoil_from = "soilgrids"}. Default uses all
9 properties: clay, sand, silt, phh2o, soc, cec, bdod,
nitrogen, cfvo. Set to \code{c("clay", "sand", "silt")}
to recover the v0.9.49 behaviour. \code{cfvo} is mapped
to \code{coarse_fragments_pct}, which drives the
Leptosols diagnostic (>= 90 within 25 cm).}

\item{ossl_models}{Required when \code{fill_topsoil_from =
"spectra"}. A list of \code{soilKey_pls_model} objects
from \code{\link{train_pls_from_ossl}} (v0.9.46).}

\item{classify_with}{One of \code{"wrb2022"} (default) or
\code{"sibcs"}.}

\item{max_n}{Optional integer cap on the number of pedons
benchmarked. Useful for quick development runs.}

\item{soilgrids_lookup_fn}{Internal: SoilGrids lookup function
(defaults to \code{\link{lookup_soilgrids}}). Override
for unit tests to inject a deterministic stub.}

\item{verbose}{If \code{TRUE} (default), prints progress.}
}
\value{
A list with elements:
  \describe{
    \item{\code{predictions}}{data.frame with one row per pedon:
          \code{point_id, lon, lat, country, predicted,
          reference_code, reference_name, agree}.}
    \item{\code{confusion}}{Confusion table (predicted vs
          reference) over in-scope rows.}
    \item{\code{accuracy}}{Overall fraction of correct
          classifications among in-scope rows.}
    \item{\code{per_rsg}}{Per-RSG recall data.frame.}
    \item{\code{n_in_scope}}{Number of pedons with both
          predicted and reference set.}
    \item{\code{n_total}}{Total pedons benchmarked.}
    \item{\code{n_errors}}{Number of pedons where the classifier
          errored out.}
    \item{\code{errors}}{List of \code{(i, id, error)} tuples for
          classifier errors.}
    \item{\code{config}}{Recap of arguments used.}
  }
}
\description{
For each pedon in \code{pedons}, attaches the canonical Reference
Soil Group at its coordinate via \code{\link{lookup_esdb}}, runs
\code{\link{classify_wrb2022}} (or \code{\link{classify_sibcs}}),
and tabulates predicted vs reference. Optionally fills missing
texture from ISRIC SoilGrids 250m before classifying so that
WRB diagnostic horizons that depend on clay (argic, ferralic,
nitic) are reachable.
}
\details{
This closes Route B of the v0.9.27 EU-LUCAS roadmap end-to-end:
v0.9.44 \code{\link{lookup_esdb}} provides the reference label;
v0.9.49 (this) provides the loader and the comparison loop;
v0.9.48 \code{\link{lookup_soilgrids}} fills texture; v0.9.46
\code{\link{predict_from_spectra}} and v0.9.47
\code{\link{predict_munsell_from_spectra}} can fill the
chemistry / Munsell gaps when Vis-NIR is available.
}
\examples{
\dontrun{
pedons <- load_lucas_soil_2018(
  "soil_data/eu_lucas/LUCAS-SOIL-2018-data-report-readme-v2/LUCAS-SOIL-2018-v2",
  countries = c("ES"), max_n = 50)
bench <- benchmark_lucas_2018(
  pedons,
  esdb_root = "soil_data/eu_lucas/ESDB-Raster-Library-1k-GeoTIFF-20240507",
  fill_texture_from = "soilgrids")
bench$accuracy
bench$per_rsg
}
}
\seealso{
\code{\link{load_lucas_soil_2018}},
         \code{\link{lookup_esdb}},
         \code{\link{lookup_soilgrids}}.
}
