% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/spectra-fetch.R
\name{download_ossl_subset}
\alias{download_ossl_subset}
\title{Download an OSSL subset and return an `ossl_library` artefact}
\usage{
download_ossl_subset(
  region = c("global", "south_america", "north_america", "europe", "africa", "asia",
    "oceania"),
  properties = c("clay_pct", "sand_pct", "silt_pct", "cec_cmol", "bs_pct", "ph_h2o",
    "oc_pct", "fe_dcb_pct", "caco3_pct"),
  wavelengths = 350:2500,
  endpoint = NULL,
  cache_dir = NULL,
  force = FALSE,
  verbose = TRUE
)
}
\arguments{
\item{region}{One of \code{"global"}, \code{"south_america"},
\code{"north_america"}, \code{"europe"}, \code{"africa"},
\code{"asia"}, \code{"oceania"}. Filters the OSSL training
rows by their site coordinates' continent.}

\item{properties}{Character vector of OSSL property names to keep
in `Yr` (drops other reference columns to keep the artefact
small). Defaults to the WRB-relevant set used by
\code{\link{fill_from_spectra}}.}

\item{wavelengths}{Integer vector of wavelengths (nm) the returned
\code{Xr} matrix will be interpolated to. Defaults to
Vis-NIR/SWIR (350-2500 nm at 1-nm resolution, 2151
columns).}

\item{endpoint}{OSSL HTTP endpoint serving the JSON manifest;
overrideable via \code{options(soilKey.ossl_endpoint = ...)}
for testing or for using a private mirror. The default is
the public Soil Spectroscopy GG bucket.}

\item{cache_dir}{Cache directory; defaults to
\code{tools::R_user_dir("soilKey", "cache")}.}

\item{force}{If \code{TRUE}, re-fetches even when a cached subset
exists.}

\item{verbose}{If \code{TRUE}, emits a `cli` summary of the fetch.}
}
\value{
A list with elements \code{Xr} (numeric matrix, rows =
        training profiles, columns = wavelengths in nm),
        \code{Yr} (data.frame with the requested property columns,
        rows aligned to \code{Xr}), and \code{metadata} (snapshot
        date, region, n profiles, source URL, and the SHA-256 of
        the cache file). Pass it as the \code{ossl_library}
        argument to \code{\link{fill_from_spectra}} or
        \code{\link{predict_ossl_mbl}}.
}
\description{
Fetches a region-filtered subset of the Open Soil Spectral Library
(Sanderman et al. 2024) and assembles it into the
`list(Xr, Yr, metadata)` shape consumed by
\code{\link{predict_ossl_mbl}} and
\code{\link{predict_ossl_plsr_local}}. The result is cached under
`tools::R_user_dir("soilKey", "cache")` so subsequent calls in the
same session (or future R sessions) skip the network.
}
\details{
This function intentionally does \strong{not} fall back to the
synthetic predictor on network failure -- a missing OSSL artefact
is a real condition that the caller must handle, and silent
fallback would make benchmarks meaningless.
}
\references{
Sanderman, J., Savage, K., Dangal, S.R.S., Duran, G., Rivard, C.,
Cardona, M.T., Sandzhieva, A., Aramian, A. & Safanelli, J.L. (2024).
Soil Spectroscopy for Global Good -- the Open Soil Spectral Library
(OSSL). \code{https://soilspectroscopy.org/}.
}
