# =============================================================================
# Documentation entry for data/ossl_demo_sa.rda.
# =============================================================================


#' Synthetic OSSL South America demo subset
#'
#' A small, deterministic, OSSL-shaped artefact for use in vignettes,
#' examples and tests when the real Open Soil Spectral Library data
#' is not available (no network, sensitive deployment, CI). The
#' object has the canonical \code{list(Xr, Yr, metadata)} shape
#' consumed by \code{\link{predict_ossl_mbl}} /
#' \code{\link{fill_from_spectra}}, so the in-package demo path is
#' identical to the real-data path.
#'
#' @format A list with three elements:
#' \describe{
#'   \item{\code{Xr}}{Numeric matrix, 80 rows (synthetic profiles)
#'         x 2151 columns (wavelengths 350-2500 nm). Reflectance
#'         values in [0.05, 0.85].}
#'   \item{\code{Yr}}{Data frame, 80 rows x 9 columns
#'         (\code{clay_pct}, \code{sand_pct}, \code{silt_pct},
#'         \code{cec_cmol}, \code{bs_pct}, \code{ph_h2o},
#'         \code{oc_pct}, \code{fe_dcb_pct}, \code{caco3_pct}). Property
#'         ranges follow the OSSL global summary statistics.}
#'   \item{\code{metadata}}{Named list with provenance information
#'         (\code{region}, \code{n_profiles}, \code{snapshot},
#'         \code{seed}, \code{note}, ...).}
#' }
#'
#' @details
#' This is a \strong{synthetic} placeholder: the spectra are generated
#' from a tropical-soil baseline plus property-correlated absorption
#' bands (1400 nm OH-water, 1900 nm clay-OH, 2200 nm Al-OH, 900 nm
#' Fe-oxide) with deterministic noise. It is \emph{not} a substitute
#' for real OSSL measurements. For paper-grade work, populate a real
#' OSSL artefact via:
#'
#' \preformatted{
#'   ossl_lib <- download_ossl_subset(region = "south_america")
#' }
#'
#' Re-build the demo with \code{source("data-raw/build_ossl_demo.R")}.
#'
#' @source
#' Synthetic; built by \code{data-raw/build_ossl_demo.R} with seed
#' 20260430. The OSSL property ranges that drove the simulation
#' come from Sanderman, J. \emph{et al.} (2024), \emph{Open Soil
#' Spectral Library}, \url{https://soilspectroscopy.org/}.
#'
#' @examples
#' data(ossl_demo_sa)
#' dim(ossl_demo_sa$Xr)
#' #> [1]   80 2151
#' head(ossl_demo_sa$Yr)
#'
#' \donttest{
#' # Use it as the ossl_library argument to predict_ossl_mbl():
#' pedon <- make_synthetic_pedon_with_spectra()
#' fill_from_spectra(pedon,
#'                   library      = "ossl",
#'                   method       = "mbl",
#'                   ossl_library = ossl_demo_sa)
#' }
#'
#' @keywords datasets
"ossl_demo_sa"
