% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hzOffset.R
\name{hzAbove}
\alias{hzAbove}
\alias{hzBelow}
\alias{hzOffset}
\title{Select Horizons Above or Below a Reference Horizon}
\usage{
hzAbove(x, ..., offset = NULL, SPC = TRUE, simplify = SPC, single = FALSE)

hzBelow(x, ..., offset = NULL, SPC = TRUE, simplify = SPC, single = FALSE)

hzOffset(x, hzidx, offset, SPC = FALSE, simplify = TRUE)
}
\arguments{
\item{x}{\code{SoilProfileCollection}}

\item{...}{comma-separated set of logical expressions, in context of horizon data, length for each expression must match number of horizons in \code{x}}

\item{offset}{integer vector or NULL, when specified this is the \verb{[, j]} (horizon/slice) index definining the horizons above or below a reference horizon that should be returned. see details}

\item{SPC}{logical, return a \code{SoilProfileCollection} subset to selected horizons}

\item{simplify}{logical, flatten list of horizon row indices into a numeric vector}

\item{single}{logical, interpret multiple matching reference horizons as a single horizon, defined by max(top) - min(bottom)}

\item{hzidx}{integer vector of target horizon row indices, typically calculated by \code{hzAbove()} and \code{hzBelow()}}
}
\value{
One of:
\itemize{
\item \code{SoilProfileCollection}: when \code{SPC = TRUE}
\item list of horizon row indices when \code{SPC = FALSE} and \code{simplify = FALSE}
\item vector of horizon row indices: when \code{SPC = FALSE} and \code{simplify = TRUE}
}

The return value will not include data from profiles which have no matching reference horizons.
}
\description{
These functions return "selected" horizons offset from "reference" horizon defined by logical expressions which include horizon data elements. Typically, \code{hzAbove()} and \code{hzBelow()} are used as a simpler interface to \code{hzOffset()}. Selected horizons can be returned as a complete \code{SoilProfileCollection} (\code{SPC = TRUE}), a list of horizon data row indices (\verb{SPC = FALSE, simplify = FALSE}), or as a numeric vector of horizon data row indices (\verb{SPC = FALSE, simplify = TRUE}).
}
\details{
Expressions that match multiple reference horizons will result in the inclusion of these reference horizons in the selected horizons. Interpreting multiple reference horizons as a single horizon (\code{single = TRUE}), defined by min(top) - max(bottom), will ensure that only selected horizons are returned.

The \code{offset} argument controls which "horizons above" or "horizons below" reference horizon(s) are selected, using the \code{SoilProfileCollection} \verb{[, j]} (horizon/slice) notation. Possible values and their interpretation are as follows:
\itemize{
\item \code{offset = NULL}: select all horizons above or below reference horizon(s)
\item \code{offset = 1}: select the first horizon above or below reference horizon(s)
\item \code{offset = 1:2}: select the first and second horizons above or below reference horizon(s)
\item \code{offset = 1:10}: safely select the 1st -> 10th horizons, even if there are fewer, above or below reference horizon(s)
}
}
\examples{

# example data
x <- c(
  'P1:AAA|BwBwBwBw|CCCCCCC|CdCdCdCd',
  'P2:Ap|AA|E|BhsBhs|Bw1Bw1|CCCCC',
  'P3:A|Bt1Bt1Bt1|Bt2Bt2Bt2|Bt3|Cr|RRRRR',
  'P4:AA|EEE|BhsBhsBhsBhs|BwBw|CCCCC',
  'P5:AAAA|ACACACACAC|CCCCCCCCCCC|CdCdCd'
)

s <- quickSPC(x)

# single match for most profiles
.ex <- grepl('Bt3|Bw', s$name)
s$e <- .ex

# default: select all horizons above or below
a <- hzAbove(s, .ex, SPC = FALSE, simplify = TRUE)
b <- hzBelow(s, .ex, SPC = FALSE, simplify = TRUE)

op <- par(no.readonly = TRUE)
par(mar = c(0, 0, 3, 0))
plotSPC(
  s, color = 'e', col.label = 'reference', col.palette = c('grey', 'royalblue'), 
  name = 'name', hz.depths = TRUE, depth.axis = FALSE, 
  name.style = 'center-center', cex.names = 0.75
)

# highlight selected horizons above and below with brackets
addBracket(
  depths(s, hzID = FALSE)[a, ], agg = TRUE,
  offset = -0.3, col = 'darkgreen', tick.length = 0, lwd = 3
)

addBracket(
  depths(s, hzID = FALSE)[b, ], agg = TRUE,
  offset = -0.35, col = 'firebrick', tick.length = 0, lwd = 3
)


# select only 1st horizon above / below
a <- hzAbove(s, .ex, SPC = FALSE, simplify = TRUE, offset = 1)
b <- hzBelow(s, .ex, SPC = FALSE, simplify = TRUE, offset = 1)

plotSPC(
  s, color = 'e', col.label = 'reference', col.palette = c('grey', 'royalblue'), 
  name = 'name', hz.depths = TRUE, depth.axis = FALSE, 
  name.style = 'center-center', cex.names = 0.75
)

# highlight selected horizons above and below with brackets
addBracket(
  depths(s, hzID = FALSE)[a, ], agg = TRUE,
  offset = -0.3, col = 'darkgreen', tick.length = 0, lwd = 3
)

addBracket(
  depths(s, hzID = FALSE)[b, ], agg = TRUE,
  offset = -0.35, col = 'firebrick', tick.length = 0, lwd = 3
)


# multiple matches
.ex <- grepl('B', s$name)
s$e <- .ex

# default
a <- hzAbove(s, .ex, SPC = FALSE, simplify = TRUE)
b <- hzBelow(s, .ex, SPC = FALSE, simplify = TRUE)

par(mfcol = c(1, 2))
plotSPC(
  s,  col.label = 'reference', color = 'e', 
  col.palette = c('grey', 'royalblue'), 
  name = 'name', hz.depths = TRUE, depth.axis = FALSE, 
  name.style = 'center-center', cex.names = 0.75
)

addBracket(
  depths(s, hzID = FALSE)[a, ], agg = TRUE,
  offset = -0.3, col = 'darkgreen', tick.length = 0, lwd = 3
)

addBracket(
  depths(s, hzID = FALSE)[b, ], agg = TRUE,
  offset = -0.35, col = 'firebrick', tick.length = 0, lwd = 3
)

mtext('single = FALSE',  side = 1, line = -1.5, at = 0, adj = -0.5)


# interpret multiple reference hz as a single reference hz
a <- hzAbove(s, .ex, SPC = FALSE, simplify = TRUE, single = TRUE)
b <- hzBelow(s, .ex, SPC = FALSE, simplify = TRUE, single = TRUE)


plotSPC(
  s, col.label = 'reference', color = 'e', 
  col.palette = c('grey', 'royalblue'), name = 'name', 
  hz.depths = TRUE, depth.axis = FALSE, 
  name.style = 'center-center', cex.names = 0.75
)

addBracket(
  depths(s, hzID = FALSE)[a, ], agg = TRUE,
  offset = -0.3, col = 'darkgreen', tick.length = 0, lwd = 3
)

addBracket(
  depths(s, hzID = FALSE)[b, ], agg = TRUE,
  offset = -0.35, col = 'firebrick', tick.length = 0, lwd = 3
)

mtext('single = TRUE',  side = 1, line = -1.5, at = 0, adj = -0.5)


# demonstrate SPC = TRUE, single = TRUE
plotSPC(
  s, col.label = 'reference', color = 'e', 
  col.palette = c('grey', 'royalblue'), name = 'name', 
  hz.depths = TRUE, depth.axis = FALSE, 
  name.style = 'center-center', cex.names = 0.75, max.depth = 250
)

a <- hzAbove(s, .ex, SPC = TRUE, single = TRUE)

plotSPC(
  a, name = 'name', hz.depths = TRUE, depth.axis = FALSE, 
  name.style = 'center-center', cex.names = 0.75, max.depth = 250
)
title('selected profiles/horizons')

par(op)

}
