% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/spectra-fetch-labels.R
\name{download_ossl_subset_with_labels}
\alias{download_ossl_subset_with_labels}
\title{Download an OSSL subset and attach WRB / SiBCS / USDA labels}
\usage{
download_ossl_subset_with_labels(
  region = c("global", "south_america", "north_america", "europe", "africa", "asia",
    "oceania"),
  max_distance_km = 5,
  wosis_endpoint = NULL,
  translate_systems = TRUE,
  max_to_label = Inf,
  verbose = TRUE,
  query_fn = NULL,
  ...
)
}
\arguments{
\item{region}{OSSL region filter; one of \code{"global"},
\code{"south_america"}, \code{"north_america"},
\code{"europe"}, \code{"africa"}, \code{"asia"},
\code{"oceania"}.}

\item{max_distance_km}{WoSIS spatial-join tolerance in kilometres
(default 5). Profiles whose nearest WRB-labeled WoSIS
neighbour is farther than this are left unlabeled.}

\item{wosis_endpoint}{Override for the WoSIS GraphQL endpoint
(default \code{getOption("soilKey.wosis_graphql")}). The
canonical value is
\code{"https://graphql.isric.org/wosis/graphql"}.}

\item{translate_systems}{If \code{TRUE} (default), also adds
\code{sibcs_ordem} and \code{usda_order} columns derived
from the WRB label via the Schad (2023) Annex Table 1 /
SiBCS 5ª ed. Annex A correspondence. Those translations
are 1:N for some classes; we pick the most-common partner
and tag rows where the translation is genuinely ambiguous.}

\item{max_to_label}{Maximum number of profiles to query against
WoSIS (default \code{Inf}). WoSIS throttles aggressive
queries; cap this when running interactive demos.}

\item{verbose}{Emit \code{cli} progress messages.}

\item{query_fn}{Optional injection of the per-coordinate WoSIS
query function. Default uses
\code{\link{.query_nearest_wosis_wrb}}. Tests pass a stub
here to exercise the join logic without network.}

\item{...}{Forwarded to \code{\link{download_ossl_subset}}.}
}
\value{
A list with \code{Xr} (numeric matrix), \code{Yr} (data
        frame with the labels attached), and \code{metadata}
        (list with the OSSL fetch metadata + the join statistics:
        number of profiles labeled, average / max distance,
        WoSIS endpoint, snapshot date).
}
\description{
Fetches a region-filtered slice of the Open Soil Spectral Library
via \code{\link{download_ossl_subset}} and post-joins WRB
Reference Soil Group labels from WoSIS GraphQL by spatial
nearest-neighbour. The resulting artefact has the canonical
\code{list(Xr, Yr, metadata)} shape -- with extra columns in
\code{Yr}: \code{wrb_rsg}, \code{wrb_label_source},
\code{wrb_label_distance_km}, plus optionally \code{sibcs_ordem}
and \code{usda_order} when \code{translate_systems = TRUE}.
}
\section{Why this function exists}{

OSSL stores Vis-NIR / MIR spectra and lab data but typically lacks
WRB Reference Soil Group labels on most profiles (KSSL data is
USDA-flavoured; non-US contributions are inconsistent). WoSIS, by
contrast, archives ~228 000 profiles with WRB labels but no
spectra. This function bridges the two so the user can run
\code{\link{classify_by_spectral_neighbours}} on a real-data
OSSL library without having to do the spatial join themselves.
}

\section{Caveats and provenance}{

WRB labels obtained via spatial join are \strong{weak labels}.
The same physical location may have been classified differently
across surveys (different WRB editions, different
interpretations). Each row carries:

\itemize{
  \item \code{wrb_label_source = "wosis_spatial_join"}: label
        inherited from a WoSIS neighbour within
        \code{max_distance_km}.
  \item \code{wrb_label_distance_km}: the distance to that
        neighbour (NA when no neighbour was found within
        tolerance).
  \item \code{wrb_label_source = "ossl_native"}: label was
        already present in OSSL Yr (rare; preserved verbatim).
  \item \code{wrb_label_source = "missing"}: no neighbour within
        tolerance; the row stays unlabeled and will be skipped
        downstream.
}

Treat the labels as priors, not ground truth.
}

\examples{
\donttest{
# Pulls OSSL + WoSIS over the network; the example no-ops on CRAN.
if (interactive()) {
  lib <- try(download_ossl_subset_with_labels(
    region          = "south_america",
    max_distance_km = 10
  ), silent = TRUE)
  if (!inherits(lib, "try-error")) {
    table(lib$Yr$wrb_rsg, useNA = "always")
    table(lib$Yr$wrb_label_source)
  }
}
}
}
\seealso{
\code{\link{download_ossl_subset}}, \code{\link{classify_by_spectral_neighbours}}.
}
