% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/benchmark-bdsolos.R
\name{benchmark_bdsolos}
\alias{benchmark_bdsolos}
\title{Benchmark soilKey classifiers against BDsolos national reference labels}
\usage{
benchmark_bdsolos(
  pedons,
  systems = c("wrb2022", "sibcs", "usda"),
  sibcs_level = c("order", "subordem"),
  max_n = NULL,
  verbose = TRUE
)
}
\arguments{
\item{pedons}{A list of \code{\link{PedonRecord}} objects, typically
produced by \code{\link{load_bdsolos_csv}}.}

\item{systems}{Character vector. Any subset of \code{c("wrb2022",
"sibcs", "usda")}. Default runs all three.}

\item{sibcs_level}{One of \code{"order"} (default) or
\code{"subordem"}. Forwarded to
\code{\link{normalise_febr_sibcs}}.}

\item{max_n}{Optional integer; cap classification at the first
\code{max_n} pedons. \code{NULL} (default) classifies every
pedon.}

\item{verbose}{If \code{TRUE} (default), emits cli progress messages.}
}
\value{
A list with elements:
  \itemize{
    \item \code{per_system} -- named list (one entry per requested
          system) of \code{list(accuracy, n_compared, n_correct,
          n_errors, confusion, per_class)} (or
          \code{list(accuracy = NA_real_, message)} when no
          reference labels were present).
    \item \code{coverage} -- named list of
          \code{list(n_with_ref, n_total, pct)} per system.
    \item \code{config} -- named list capturing
          \code{n_pedons, systems, sibcs_level, soilKey_version,
          timestamp}.
  }
}
\description{
Runs \code{\link{classify_wrb2022}}, \code{\link{classify_sibcs}}, and
\code{\link{classify_usda}} on each \code{\link{PedonRecord}} loaded
from a BDsolos CSV via \code{\link{load_bdsolos_csv}}, then compares
each predicted classification against the corresponding BDsolos
reference label (\code{reference_sibcs}, \code{reference_wrb},
\code{reference_st}) and reports per-system accuracy, per-class
recall, and a confusion matrix.
}
\section{Reference label coverage}{


BDsolos densely populates \code{reference_sibcs} (~82% nation-wide as
of the v0.9.59 audit) but sparsely populates \code{reference_wrb} and
\code{reference_st} (UF-dependent; ~5% on RJ, higher in some other
states). The function always reports the per-system label coverage
(\code{$coverage}) so the caller can judge how representative each
accuracy figure is.
}

\section{Comparison level}{


SiBCS comparison is at \code{level = "order"} by default, which
converts the BDsolos all-caps Portuguese label (e.g.
\code{"ARGISSOLO VERMELHO Tb EUTROFICO ..."}) to the soilKey plural
Title Case form (\code{"Argissolos"}) via
\code{\link{normalise_febr_sibcs}}. Set \code{sibcs_level =
"subordem"} to compare the first two SiBCS tokens (Ordem + Subordem).

WRB and USDA comparisons are at the Reference Soil Group / Order
level: \code{normalise_febr_wrb()} strips qualifier parens and
pluralises the bare RSG (\code{"Xanthic Ferralsol"} ->
\code{"Ferralsols"}); \code{normalise_febr_usda()} maps the suffix of
the last subgroup token to the USDA Order (\code{"Typic
Haplorthox"} -> \code{"Oxisols"}).
}

\section{Errors and missing-label handling}{


Pedons without a reference label for a given system are silently
excluded from THAT system's comparison (but still classified for the
other two systems). If a system has zero pedons with a reference
label, the corresponding \code{$per_system} entry has
\code{accuracy = NA_real_} and \code{message = "no_reference_labels"}.
Classifier errors are caught per-pedon and recorded in
\code{n_errors}; they do not abort the run.
}

\examples{
\donttest{
# Requires a user-provided BDsolos CSV; guarded so the example
# no-ops on CRAN when the file is absent.
csv_path <- "RJ.csv"
if (file.exists(csv_path)) {
  peds <- load_bdsolos_csv(csv_path)
  bench <- benchmark_bdsolos(peds, systems = c("sibcs", "wrb2022", "usda"))
  bench$coverage      # how many pedons had each reference label
  bench$per_system$sibcs$accuracy
  bench$per_system$sibcs$confusion

  # Subordem level
  bench2 <- benchmark_bdsolos(peds, systems = "sibcs",
                                 sibcs_level = "subordem")
}
}
}
\seealso{
\code{\link{load_bdsolos_csv}},
  \code{\link{benchmark_lucas_2018}}, \code{\link{classify_all}},
  \code{\link{normalise_febr_sibcs}},
  \code{\link{normalise_febr_wrb}},
  \code{\link{normalise_febr_usda}}.
}
