% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/key-usda.R
\name{classify_usda}
\alias{classify_usda}
\title{Classify a pedon under USDA Soil Taxonomy (13th edition)}
\usage{
classify_usda(
  pedon,
  rules = NULL,
  on_missing = c("warn", "silent", "error"),
  include_family = FALSE,
  infer_temperature = TRUE,
  gapfill = FALSE
)
}
\arguments{
\item{pedon}{A \code{\link{PedonRecord}}.}

\item{rules}{Optional pre-loaded rule set.}

\item{on_missing}{One of \code{"warn"} (default), \code{"silent"},
\code{"error"}.}

\item{include_family}{If \code{TRUE}, derive and prepend the 5th-level
family modifiers. Default \code{FALSE} (output byte-identical to
earlier versions).}

\item{infer_temperature}{When deriving the family, infer the soil
temperature regime from latitude/elevation if
\code{site$soil_temperature_regime} is absent (default
\code{TRUE}). See \code{family_temperature_regime_usda}.}

\item{gapfill}{Opt-in within-pedon depth gap-fill, default \code{FALSE}
(no-op, classification stays byte-identical). \code{TRUE} fills
interior \code{NA} cells of the continuous depth-trending attributes
by linear interpolation from the profile's own measured horizons; a
character vector restricts it to those attributes; a named list is
passed to \code{\link{gapfill_within_pedon}}. Filled cells carry
\code{inferred_prior} provenance, so the evidence grade drops to
\code{"C"}. Runs on a deep copy -- the caller's pedon is never mutated.}
}
\value{
A \code{\link{ClassificationResult}} with deepest-level
        taxon name. Each level's trace is in \code{$trace}; the family
        attributes are in \code{$trace$family}.
}
\description{
Walks the canonical USDA key (Order -> Suborder -> Great Group ->
Subgroup) using YAML rule files at:
\itemize{
  \item \code{inst/rules/usda/key.yaml}: Order key (12 entries)
  \item \code{inst/rules/usda/suborders/<order>.yaml}
  \item \code{inst/rules/usda/great-groups/<order>.yaml}
  \item \code{inst/rules/usda/subgroups/<order>.yaml}
}
}
\details{
With \code{include_family = TRUE} it additionally derives the 5th
category, the \strong{family} -- a set of class modifiers
(particle-size, mineralogy, CEC-activity, reaction, temperature
regime, depth) PREPENDED to the subgroup name, e.g. \emph{"fine,
kaolinitic, isohyperthermic Rhodic Hapludox"}. See
\code{\link{classify_usda_family}}.
}
\examples{
pedon <- make_ferralsol_canonical()
res <- classify_usda(pedon)
res$name
# include the 5th (family) level:
classify_usda(pedon, include_family = TRUE)$name
}
\references{
Soil Survey Staff (2022). Keys to Soil Taxonomy, 13th
  edition. USDA Natural Resources Conservation Service.
}
