% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/benchmark-unified.R
\name{benchmark_unified}
\alias{benchmark_unified}
\title{Unified cross-dataset benchmark across SiBCS / WRB / USDA}
\usage{
benchmark_unified(
  systems = c("all", "wrb2022", "sibcs", "usda"),
  datasets = c("all", "bdsolos", "febr", "kssl", "lucas_esdb"),
  paths = NULL,
  max_n_per_dataset = NULL,
  engine = c("soilkey", "aqp", "both"),
  harmonize = FALSE,
  gapfill = FALSE,
  verbose = TRUE
)
}
\arguments{
\item{systems}{Character vector. Any subset of \code{c("wrb2022",
"sibcs", "usda")}. Default \code{"all"} runs all three.}

\item{datasets}{Character vector. Any subset of
\code{c("bdsolos", "febr", "kssl", "lucas_esdb")}.
Default \code{"all"} pools every dataset that has
reference labels for the requested systems. Datasets
without reference labels for a system are silently
excluded from that system's pooled result.}

\item{paths}{Named list of dataset paths. Element names should
match those in \code{datasets}. If \code{NULL} (default),
soilKey looks for canonical paths under
\code{"~/soil_data/"}.}

\item{max_n_per_dataset}{Optional integer to cap per-dataset
sample size (useful for development / debugging).
\code{NULL} (default) classifies every available pedon.}

\item{engine}{Currently forwarded to Phase-1 aqp wiring. One of
\code{"soilkey"} (default), \code{"aqp"}, \code{"both"}.
When \code{"aqp"}, sets \code{options(soilKey.diagnostic_engine
= "aqp")} for the duration of the benchmark, which routes
\code{argic()} / \code{cambic()} through the canonical
\code{aqp::getArgillicBounds} / \code{getCambicBounds}.}

\item{harmonize}{If \code{TRUE} (default \code{FALSE}), applies
\code{\link{harmonize_to_gsm}} to each dataset's pedons before
classification, putting all chemistry/texture on the GSM
depth grid (0-5 / 5-15 / 15-30 / 30-60 / 60-100 / 100-200 cm).
Required for cross-dataset pooling integrity (Phase 2.3) but
slow (~1-2 min for 1k pedons) and may degrade per-dataset
accuracy slightly because the splined depths are
approximations.}

\item{gapfill}{If not \code{FALSE} (the default), applies
\code{\link{gapfill_within_pedon}} to each dataset's pedons before
classification, filling interior \code{NA} cells of the continuous
depth-trending attributes by within-pedon linear interpolation.
Accepts the same values as the \code{gapfill} argument of
\code{\link{classify_all}} (\code{TRUE}, a character vector of
attributes, or a named list). Lets you measure the ON/OFF accuracy
lift of gap-fill reproducibly through the harness.}

\item{verbose}{If \code{TRUE} (default), emits cli progress.}
}
\value{
A list with elements:
  \itemize{
    \item \code{per_system} -- per-system pooled
          \code{list(accuracy, n_compared, n_correct, confusion,
          per_class)}.
    \item \code{per_system_per_dataset} -- per-(system, dataset)
          same shape, for breakdown.
    \item \code{coverage} -- per-(system, dataset) sample sizes
          and label coverage.
    \item \code{config} -- captures \code{systems, datasets,
          engine, soilKey_version, timestamp}.
  }
}
\description{
Runs a system's soilKey classifier on every dataset that has
reference labels for that system, then pools the results into a
single nation-/world-wide accuracy estimate.
}
\section{Datasets and their reference labels}{


\tabular{ll}{
  Dataset             \tab Systems with reference labels         \cr
  BDsolos             \tab SiBCS (dense), WRB (sparse), USDA (sparse) \cr
  FEBR superconjunto  \tab SiBCS, WRB, USDA (most rows have all 3)    \cr
  KSSL+NASIS          \tab USDA only (samp_taxsubgrp universal)        \cr
  LUCAS + ESDB raster \tab WRB (via lookup_esdb on coords)             \cr
}

For each (system, dataset) pair, this function:
\enumerate{
  \item Loads pedons via the appropriate \code{load_*} helper.
  \item Filters to pedons with a populated reference label for the
        requested system.
  \item Normalises both reference and predicted labels via
        \code{normalise_febr_*()} / KSSL canonicalisation helpers.
  \item Calls the system's classifier and records pred-vs-ref.
}
Then pools per-system results across datasets.
}

\section{Engine selection (Phase 1 wiring)}{


For datasets with morphological data (BDsolos / FEBR), the
diagnostics that pivot Argissolos / Latossolos / Cambissolos
classification can be run with two engines:
\itemize{
  \item \code{engine = "soilkey"} (default) -- the hand-coded WRB
        6/1.4/20 thresholds.
  \item \code{engine = "aqp"} -- aqp::getArgillicBounds /
        getCambicBounds (KST 13ed 3/1.2/8 thresholds).
}
On the v0.9.62 RJ benchmark (722 perfis), aqp was 14.8 pp stricter
on argic and 40.6 pp more permissive on cambic; the SiBCS
Argissolos / Latossolos / Cambissolos boundary is sensitive to
both. \code{engine} is currently forwarded to a future v0.9.63
wired \code{argic()} / \code{cambic()}; for now,
\code{benchmark_unified()} reports separately per engine when
\code{engine = "both"}.
}

\seealso{
\code{\link{benchmark_bdsolos}}, \code{\link{benchmark_lucas_2018}},
  \code{\link{benchmark_run_classification}},
  \code{\link{harmonize_to_gsm}}.
}
