% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/getArgillicBounds.R
\name{getArgillicBounds}
\alias{getArgillicBounds}
\title{Estimate upper and lower boundary of argillic diagnostic subsurface horizon}
\usage{
getArgillicBounds(
  p,
  hzdesgn = hzdesgnname(p, required = TRUE),
  clay.attr = hzmetaname(p, "clay", required = TRUE),
  texcl.attr = hztexclname(p, required = TRUE),
  require_t = TRUE,
  bottom.pattern = "Cr|R|Cd",
  lower.grad.pattern = "^[2-9]*B*CB*[^rtd]*[1-9]*$",
  sandy.texture.pattern = "-S$|^S$|COS$|L[^V]FS$|[^L]VFS$|LS$|LFS$",
  vertical.distance = 30,
  simplify = TRUE,
  verbose = FALSE
)
}
\arguments{
\item{p}{A SoilProfileCollection}

\item{hzdesgn}{the name of the column/attribute containing the horizon designation; default="hzname"}

\item{clay.attr}{the name of the column/attribute containing the clay content; default="clay"}

\item{texcl.attr}{the name of the column/attribute containing the textural class (used for finding sandy horizons); default="texcl"}

\item{require_t}{require a "t" subscript for positive identification of upper and lower bound of argillic? default: TRUE}

\item{bottom.pattern}{regular expression passed to \code{estimateSoilDepth} to match the lower boundary of the soil. default is "Cr|R|Cd" which approximately matches paralithic, lithic and densic contacts.}

\item{lower.grad.pattern}{this is a pattern for adjusting the bottom depth of the argillic horizon upwards from the bottom depth of the soil. The absence of illuviation is used as a final control on horizon pattern matching.}

\item{sandy.texture.pattern}{this is a pattern for matching sandy textural classes: \verb{-S$|^S$|COS$|L[^V]FS$|[^L]VFS$|LS$|LFS$}}

\item{vertical.distance}{Vertical distance in which clay increase must be met. Default \code{30} cm}

\item{simplify}{Return a length 2 vector with upper and lower boundary when \code{p} has length 1? Default \code{TRUE}.}

\item{verbose}{Print out information about 't' subscripts, sandy textures, plow layers and lower gradational horizons?}
}
\value{
Returns a numeric vector; first value is top depth, second value is bottom depth. If as.list is TRUE, returns a list with top depth named "ubound" and bottom depth named "lbound". If \code{p} has more than one profile or if \code{simplify = FALSE} the result is a data.frame containing profile ID, upper and lower boundary columns.
}
\description{
\code{getArgillicBounds} estimates the upper and lower boundary of argillic diagnostic subsurface horizon for a profile in a single-profile SoilProfileCollection object (\code{p}).

The upper boundary is where the clay increase threshold is met. The function uses \code{crit.clay.argillic} as the threshold function for determining whether a clay increase occurs and \code{get.increase.matrix} to determine whether the increase is met, whether vertical distance of increase is sufficiently small, and in which horizon.
}
\details{
The lower boundary is first approximated as the depth to a lithic/paralithic/densic contact, or some other horizon matchable by a custom regular expression pattern. Subsequently, that boundary is extended upwards to the end of "evidence of illuviation."

The depth to contact is estimated using 'bottom.pattern' "Cr|R|Cd" by default. It matches anything containing Cr, R or Cd.

The lower gradational horizon regular expression ‘lower.grad.pattern' default is \verb{^[2-9]*B*CB*[^rtd]*[1-9]*$\}}. It matches anything that starts with a lithologic discontinuity (or none) and a C master horizon designation. May contain B as second horizon designation in transitional horizon. May not contain 'r' or 't' subscript.

The minimum thickness of the argillic horizon is dependent on whether all subhorizons are "sandy" or not. The \code{sandy.texture.pattern} default \verb{-S$|^S$|COS$|L[^V]FS$|[^L]VFS$|LS$|LFS$} captures USDA textural class fine earth fractions that meet "sandy" particle size class criteria.

There also is an option ‘require_t' to omit the requirement for evidence of eluviation in form of 't' subscript in 'hzdesgn'. Even if "t" subscript is not required for positive identification, the presence of lower gradational C horizons lacking 't' will still be used to modify the lower boundary upward from a detected contact, if needed. If this behavior is not desired, just set 'lower.grad.pattern' to something that will not match any horizons in your data.
}
\examples{
data(sp1, package = 'aqp')
depths(sp1) <- id ~ top + bottom
site(sp1) <- ~ group

# set required metadata
hzdesgnname(sp1) <- 'name'
hztexclname(sp1) <- 'texture'
hzmetaname(sp1, 'clay') <- 'prop'

x <- getArgillicBounds(sp1)
x

}
\author{
Andrew G. Brown
}
