% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/benchmark-lucas-2018.R
\name{load_lucas_soil_2018}
\alias{load_lucas_soil_2018}
\title{Load the LUCAS Soil 2018 Topsoil release as a list of PedonRecord objects}
\usage{
load_lucas_soil_2018(
  path,
  attach_bulk_density = TRUE,
  countries = NULL,
  max_n = NULL,
  verbose = TRUE
)
}
\arguments{
\item{path}{Folder containing \code{LUCAS-SOIL-2018.csv} (typically
\code{<root>/LUCAS-SOIL-2018-data-report-readme-v2/LUCAS-SOIL-2018-v2/}).}

\item{attach_bulk_density}{If \code{TRUE} (default), joins the
\code{BulkDensity_2018_final-2.csv} sister file on
\code{POINTID} when present.}

\item{countries}{Optional character vector of NUTS_0 codes
(e.g. \code{c("ES", "FR")}) to filter pedons. Default
\code{NULL} (all countries).}

\item{max_n}{Optional integer cap on the number of pedons returned
(after country filter). Useful for development.}

\item{verbose}{If \code{TRUE} (default), prints a summary line.}
}
\value{
A list of \code{\link{PedonRecord}} objects (one per LUCAS
        point). Each pedon has a \code{site$id} matching the LUCAS
        \code{POINTID}, \code{site$lat} / \code{site$lon} in WGS84,
        and either one or two horizons (the second being 20-30 cm
        when the subsoil OC / CaCO3 columns are populated).
        Provenance entries from the loader use
        \code{source = "measured"}.
}
\description{
Reads the canonical European Soil Data Centre (ESDAC) release of
LUCAS Soil 2018 Topsoil chemistry as published in the JRC report
(ESDAC dataset
\url{https://esdac.jrc.ec.europa.eu/content/lucas-2018-topsoil-data}).
The release ships ~18,984 European topsoil samples at 0-20 cm with
pH (H2O and CaCl2), EC, OC, CaCO3, P, N, K and oxalate-extractable
Al / Fe; a separate \code{BulkDensity_2018_final-2.csv} carries
bulk density at 0-10 / 10-20 / 20-30 / 0-20 cm for ~6,272 of those
points and is joined automatically when present.
}
\details{
What's NOT in the release (and how to fill it):

\itemize{
  \item \strong{Texture (clay / sand / silt)} -- not in this CSV.
        Pass \code{benchmark_lucas_2018(..., fill_texture_from =
        "soilgrids")} to fill from ISRIC SoilGrids 250m via
        \code{\link{lookup_soilgrids}}.
  \item \strong{Munsell colors} -- not collected by LUCAS Soil 2018.
        If the user has Vis-NIR spectra (release separate ~83 GB),
        use \code{\link{predict_munsell_from_spectra}} (v0.9.47).
  \item \strong{Vis-NIR spectra} -- distributed separately by ESDAC.
        Once downloaded and attached to the pedon's \code{$spectra},
        \code{\link{predict_from_spectra}} (v0.9.46) fills clay /
        sand / silt / pH / OC / CEC.
  \item \strong{Taxonomic reference} -- not in the LUCAS release;
        \code{\link{benchmark_lucas_2018}} attaches the canonical
        WRB Reference Soil Group via \code{\link{lookup_esdb}}
        (v0.9.44) at the pedon's coordinates.
}

Unit conversions applied (LUCAS -> soilKey schema):

\itemize{
  \item OC, N, CaCO3, Ox_Al, Ox_Fe: g/kg -> %  (* 0.1)
  \item EC: mS/m -> dS/m (* 0.01)
  \item P, K: mg/kg unchanged
  \item pH: unitless
}

Special LUCAS string values \code{"< LOD"}, \code{"<LOD"}, empty
cells and \code{"n.d."} / \code{"ND"} are converted to \code{NA}
before numeric coercion.
}
\examples{
\donttest{
path <- file.path(tempdir(), "LUCAS-SOIL-2018-v2")
if (dir.exists(path)) {
  pedons <- load_lucas_soil_2018(path, countries = c("ES", "PT"),
                                   max_n = 100)
  length(pedons)
  pedons[[1]]
}
}
}
\seealso{
\code{\link{benchmark_lucas_2018}},
         \code{\link{lookup_esdb}},
         \code{\link{lookup_soilgrids}}.
}
