% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/soil-classes-at-location.R
\name{soil_classes_at_location}
\alias{soil_classes_at_location}
\title{Likely soil classes at a geographic location (spatial classification aid)}
\usage{
soil_classes_at_location(
  lat,
  lon,
  system = c("wrb2022", "sibcs", "usda"),
  buffer_m = 1000,
  source_url = NULL,
  top_n = 5,
  verbose = TRUE
)
}
\arguments{
\item{lat, lon}{Numeric WGS-84 coordinates.}

\item{system}{Classification system. One of \code{"wrb2022"}
(default), \code{"sibcs"}, \code{"usda"}.}

\item{buffer_m}{Radius in metres around the point used to gather
raster pixels (default 1000 m, i.e. roughly 4 SoilGrids
pixels).}

\item{source_url}{Path / URL of the dominant-soil raster.}

\item{top_n}{Keep the top N classes by probability (default 5).}

\item{verbose}{Emit a \code{cli} summary.}
}
\value{
A list as described under \strong{Output}.
}
\description{
Returns a ranked list of the soil Reference Soil Groups (or
SiBCS ordens, or USDA orders) most likely to occur at the given
point, based on a global or regional dominant-soil raster
(SoilGrids 2.0 by default). This is the **before-you-have-a-pedon
helper**: a pedologist arriving in the field can call it with the
GPS coordinates of the planned profile pit and see which classes
are expected, plus what attributes typically distinguish them.
}
\details{
This function does \strong{not} classify a profile. The
deterministic key in \code{\link{classify_wrb2022}} /
\code{\link{classify_sibcs}} / \code{\link{classify_usda}} remains
the only thing that assigns a class from horizon data. The output
here is purely informational -- a "shopping list" of what to
confirm.
}
\section{Data source}{

For real use, point \code{source_url} at a regional SoilGrids
"MostProbable WRB" GeoTIFF / COG (one of the cuts at
\url{https://files.isric.org/soilgrids/latest/data/wrb/}). For
tests, \code{options(soilKey.test_raster = "/tmp/syn.tif")} is
honoured. When no source is given, the function emits a
\code{cli_alert_warning()} and returns an empty result -- it does
\strong{not} pretend to know.
}

\section{Output}{

A list with three elements:
\describe{
  \item{\code{distribution}}{A \code{data.table} with columns
        \code{rsg_code}, \code{rsg_name}, \code{probability},
        sorted by descending probability.}
  \item{\code{typical_attributes}}{A \code{data.table} keyed by
        \code{rsg_code} with the canonical attribute ranges that
        distinguish each class (clay range, CEC range, BS range,
        etc.). The values come from the WRB 2022 / SiBCS 5 /
        KST 13ed canonical thresholds, NOT from the raster.}
  \item{\code{site}}{The site list passed in, plus the buffer
        radius and the source URL.}
}
}

\examples{
\donttest{
if (requireNamespace("terra", quietly = TRUE)) {
  # Mata Atlantica, Rio de Janeiro state (needs internet -- try() guards it).
  res <- try(soil_classes_at_location(
    lat        = -22.7,
    lon        = -43.7,
    system     = "wrb2022",
    source_url = paste0("https://files.isric.org/soilgrids/latest/",
                          "data/wrb/MostProbable.vrt")
  ), silent = TRUE)
  if (!inherits(res, "try-error")) {
    res$distribution         # ranked list of likely RSGs
    res$typical_attributes   # canonical thresholds per RSG to confirm
  }
}
}
}
\seealso{
\code{\link{spatial_prior_soilgrids}} for the
         post-classification consistency check.
}
