% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gapfill.R
\name{gapfill_within_pedon}
\alias{gapfill_within_pedon}
\title{Fill interior missing horizon attributes by within-pedon depth interpolation}
\usage{
gapfill_within_pedon(pedon, attrs = NULL, confidence = 0.6, overwrite = FALSE)
}
\arguments{
\item{pedon}{A \code{\link{PedonRecord}} with at least two horizons.}

\item{attrs}{Character vector of horizon columns to fill. Defaults to the
continuous depth-trending attributes a linear interpolation can
reasonably estimate (clay/silt/sand, pH, organic carbon, CEC/ECEC,
base/aluminium saturation, bulk density).}

\item{confidence}{Numeric in \[0, 1\] recorded as the provenance confidence
of each interpolated cell. Defaults to \code{0.6} -- below a measured
value but anchored on the profile's own data, hence above the
\code{0.5} used for an external SoilGrids prior.}

\item{overwrite}{If \code{FALSE} (default) only \code{NA} cells are filled.
If \code{TRUE}, non-measured cells are re-interpolated (measured cells
are still never overwritten, and the provenance authority order is
always respected).}
}
\value{
Invisibly, the mutated \code{pedon}. An attribute
        \code{"gapfill_within_pedon"} on the return value records how many
        cells were filled and for which attributes.
}
\description{
For each requested attribute, builds a depth profile from the horizons in
which that attribute is \emph{measured} (non-\code{NA}) and linearly
interpolates the value at the mid-depth of every horizon where it is missing
-- but only for horizons whose mid-depth falls strictly between the
shallowest and deepest measured layer. Cells above the top or below the
bottom measured layer are left \code{NA}: the function interpolates, it never
extrapolates. Each fill is written with \code{source = "inferred_prior"}, so
the \code{\link{PedonRecord}} authority order keeps it from displacing a
measured, spectra-predicted or VLM-extracted value, and any downstream
\code{compute_evidence_grade} call reports grade \code{"C"}.
}
\details{
This is the within-pedon companion to
\code{\link{apply_soilgrids_depth_prior}} (which fills from an external
SoilGrids profile rather than from the profile's own measured layers). It is
the mechanism behind the opt-in \code{gapfill} argument of
\code{\link{classify_wrb2022}}, \code{\link{classify_sibcs}},
\code{\link{classify_usda}} and \code{\link{classify_all}}.

Note that this mutates \code{pedon} in place (as
\code{apply_soilgrids_depth_prior} does). The \code{gapfill} argument of the
classifiers operates on a deep copy instead, so a classification call never
alters the caller's pedon.
}
\examples{
h <- data.frame(
  top_cm    = c(0, 20, 40, 60),
  bottom_cm = c(20, 40, 60, 90),
  clay_pct  = c(15, NA, 35, 40)
)
p <- PedonRecord$new(horizons = h)
gapfill_within_pedon(p, attrs = "clay_pct")
p$horizons$clay_pct   # second horizon filled to ~25 by interpolation
}
\seealso{
\code{\link{apply_soilgrids_depth_prior}}, \code{\link{classify_all}}
}
