% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/classify-with-uncertainty.R
\name{classify_with_uncertainty}
\alias{classify_with_uncertainty}
\title{Posterior distribution over classification outcomes}
\usage{
classify_with_uncertainty(
  pedon,
  n = 200L,
  system = c("wrb2022", "sibcs", "usda"),
  level = c("rsg", "name"),
  scales = NULL,
  sensitivity = TRUE,
  seed = 42L
)
}
\arguments{
\item{pedon}{A \code{\link{PedonRecord}}.}

\item{n}{Number of Monte-Carlo draws (default 200).}

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

\item{level}{\code{"rsg"} (default; compare the RSG / order) or
\code{"name"} (compare the full classification name, qualifiers
included -- strictly more uncertain).}

\item{scales}{Optional named list overriding the default per-grade
magnitudes; each element has the shape returned by
\code{\link{get_perturbation_scale}}, keyed by grade letter.}

\item{sensitivity}{If \code{TRUE} (default) also computes a
leave-one-attribute-out sensitivity ranking. Set \code{FALSE}
to skip that extra pass when only the posterior is needed.}

\item{seed}{Random seed for reproducibility.}
}
\value{
A list of class \code{"soilkey_uncertainty"} with elements:
        \code{posterior} (named numeric vector summing to 1, sorted
        descending), \code{top1} (the modal class), \code{entropy}
        (Shannon entropy of the posterior, natural log), \code{sensitivity}
        (a \code{data.table} of \code{attribute} / \code{importance},
        or \code{NULL}), \code{n_runs}, \code{n_success},
        \code{baseline}, \code{system} and \code{level}.
}
\description{
Runs \code{n} Monte-Carlo perturbations of a pedon and tallies the
resulting classes into an empirical posterior. Unlike
\code{\link{classification_robustness}}, the perturbation magnitude of
every \code{(horizon, attribute)} cell is scaled by its provenance
evidence grade (see \code{\link{get_perturbation_scale}}): an A-grade
measurement is nudged by a few percent, an E-grade assumption by a
third of its value. The posterior therefore reflects not just how
close the profile sits to a key boundary, but how trustworthy the
inputs that placed it there actually are.
}
\examples{
\donttest{
p <- make_ferralsol_canonical()
u <- classify_with_uncertainty(p, n = 50, system = "wrb2022")
u$posterior   # P(RSG = x)
u$entropy     # near 0 for a robust profile
}
}
\seealso{
\code{\link{classification_robustness}},
         \code{\link{get_perturbation_scale}},
         \code{\link{compute_per_attribute_evidence_grade}}.
}
