% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/class-PedonRecord.R
\name{PedonRecord}
\alias{PedonRecord}
\title{PedonRecord: structured representation of a single pedon}
\description{
PedonRecord: structured representation of a single pedon

PedonRecord: structured representation of a single pedon
}
\details{
The central data carrier in soilKey. A PedonRecord bundles everything we
know about one soil profile: site metadata, the horizons table (with a
fixed canonical schema — see \code{\link{horizon_column_spec}}),
optional Vis-NIR/MIR spectra, profile photographs, source documents, and
a provenance log that records, per (horizon, attribute) pair, where each
value came from (\code{measured}, \code{extracted_vlm},
\code{predicted_spectra}, \code{inferred_prior}, \code{user_assumed}).

All diagnostic functions (\code{\link{argic}}, \code{\link{ferralic}},
\code{\link{mollic}}, ...) consume a PedonRecord directly. The
provenance log is what allows the final
\code{\link{ClassificationResult}} to assign a meaningful evidence
grade.
}
\section{Public fields}{
\if{html}{\out{<div class="r6-fields">}}
\describe{
\item{\code{site}}{List. Site-level metadata: \code{lat}, \code{lon},
\code{crs} (default 4326), \code{date},
\code{country}, \code{elevation_m}, \code{slope_pct},
\code{aspect_deg}, \code{landform},
\code{parent_material}, \code{land_use},
\code{vegetation}, \code{drainage_class},
plus an arbitrary \code{id}.}

\item{\code{horizons}}{data.table with the canonical horizon schema.}

\item{\code{spectra}}{List with optional \code{vnir} matrix (rows =
horizons, cols = wavelengths in nm), \code{mir}
matrix, and \code{metadata} list.}

\item{\code{images}}{List of named lists describing profile photographs.}

\item{\code{documents}}{List of named lists describing source documents.}

\item{\code{provenance}}{data.table with columns \code{horizon_idx},
\code{attribute}, \code{source}, \code{confidence},
\code{notes}.}
}
\if{html}{\out{</div>}}
}
\section{Methods}{
\subsection{Public methods}{
\itemize{
\item \href{#method-PedonRecord-new}{\code{PedonRecord$new()}}
\item \href{#method-PedonRecord-validate}{\code{PedonRecord$validate()}}
\item \href{#method-PedonRecord-to_aqp}{\code{PedonRecord$to_aqp()}}
\item \href{#method-PedonRecord-from_aqp}{\code{PedonRecord$from_aqp()}}
\item \href{#method-PedonRecord-add_measurement}{\code{PedonRecord$add_measurement()}}
\item \href{#method-PedonRecord-summary}{\code{PedonRecord$summary()}}
\item \href{#method-PedonRecord-print}{\code{PedonRecord$print()}}
\item \href{#method-PedonRecord-clone}{\code{PedonRecord$clone()}}
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-PedonRecord-new"></a>}}
\if{latex}{\out{\hypertarget{method-PedonRecord-new}{}}}
\subsection{Method \code{new()}}{
Construct a PedonRecord.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{PedonRecord$new(
  site = NULL,
  horizons = NULL,
  spectra = NULL,
  images = NULL,
  documents = NULL,
  provenance = NULL
)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{site}}{List of site-level metadata.}

\item{\code{horizons}}{data.frame/data.table of horizons.}

\item{\code{spectra}}{Optional list with \code{vnir}, \code{mir},
\code{metadata}.}

\item{\code{images}}{Optional list of image descriptors.}

\item{\code{documents}}{Optional list of document descriptors.}

\item{\code{provenance}}{Optional provenance data.table; if NULL, an empty
one is created.}
}
\if{html}{\out{</div>}}
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-PedonRecord-validate"></a>}}
\if{latex}{\out{\hypertarget{method-PedonRecord-validate}{}}}
\subsection{Method \code{validate()}}{
Validate the record against soil-physical sanity rules.

Checks: top < bottom for every horizon; no overlapping depths;
clay+silt+sand sum to 100 ± 2 where all three are reported; pH
values plausible (1..12); CEC >= sum of exchangeable bases (Ca, Mg,
K, Na); Munsell value/chroma in plausible ranges; coarse fragments
percent in [0, 100]; OC% reasonable (<60); site lat/lon within
geographic ranges. Returns a list with \code{valid}, \code{errors},
\code{warnings}, \code{n_horizons}.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{PedonRecord$validate(strict = FALSE, verbose = TRUE)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{strict}}{If \code{TRUE}, throws on errors instead of returning.}

\item{\code{verbose}}{If \code{TRUE}, prints messages via cli.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
Invisibly, a list summarising the validation outcome.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-PedonRecord-to_aqp"></a>}}
\if{latex}{\out{\hypertarget{method-PedonRecord-to_aqp}{}}}
\subsection{Method \code{to_aqp()}}{
Coerce to an aqp \code{SoilProfileCollection}.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{PedonRecord$to_aqp()}\if{html}{\out{</div>}}
}

\subsection{Returns}{
A \code{SoilProfileCollection}. Requires the \code{aqp}
        package.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-PedonRecord-from_aqp"></a>}}
\if{latex}{\out{\hypertarget{method-PedonRecord-from_aqp}{}}}
\subsection{Method \code{from_aqp()}}{
Populate this record from an aqp
             \code{SoilProfileCollection}.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{PedonRecord$from_aqp(spc, top_col = "top_cm", bottom_col = "bottom_cm")}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{spc}}{A \code{SoilProfileCollection}.}

\item{\code{top_col}}{Name of the top-depth column in \code{spc} (mapped to
\code{top_cm}).}

\item{\code{bottom_col}}{Name of the bottom-depth column (mapped to
\code{bottom_cm}).}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
Invisibly self (mutated in place).
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-PedonRecord-add_measurement"></a>}}
\if{latex}{\out{\hypertarget{method-PedonRecord-add_measurement}{}}}
\subsection{Method \code{add_measurement()}}{
Add a measurement (or extracted/predicted value) and
             record its provenance.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{PedonRecord$add_measurement(
  horizon_idx,
  attribute,
  value,
  source = "measured",
  confidence = 1,
  notes = NA_character_,
  overwrite = FALSE
)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{horizon_idx}}{Integer horizon index (1-based).}

\item{\code{attribute}}{Name of the horizon column to set.}

\item{\code{value}}{New value for that cell.}

\item{\code{source}}{One of "measured", "extracted_vlm",
"predicted_spectra", "inferred_prior", "user_assumed".}

\item{\code{confidence}}{Numeric in [0, 1].}

\item{\code{notes}}{Optional free-text note.}

\item{\code{overwrite}}{If \code{FALSE} (default) and the cell already has
a value from a more authoritative source, leave it
alone. If \code{TRUE}, overwrite.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
Invisibly self.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-PedonRecord-summary"></a>}}
\if{latex}{\out{\hypertarget{method-PedonRecord-summary}{}}}
\subsection{Method \code{summary()}}{
Compact summary list (for serialization or testing).
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{PedonRecord$summary(...)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{...}}{Ignored (S3 summary signature compatibility).}
}
\if{html}{\out{</div>}}
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-PedonRecord-print"></a>}}
\if{latex}{\out{\hypertarget{method-PedonRecord-print}{}}}
\subsection{Method \code{print()}}{
Pretty-print the record.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{PedonRecord$print(...)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{...}}{Ignored (S3 print signature compatibility).}
}
\if{html}{\out{</div>}}
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-PedonRecord-clone"></a>}}
\if{latex}{\out{\hypertarget{method-PedonRecord-clone}{}}}
\subsection{Method \code{clone()}}{
The objects of this class are cloneable with this method.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{PedonRecord$clone(deep = FALSE)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{deep}}{Whether to make a deep clone.}
}
\if{html}{\out{</div>}}
}
}
}
