hzAbove: Select Horizons Above or Below a Reference Horizon

Description

These functions return "selected" horizons offset from "reference" horizon defined by logical expressions which include horizon data elements. Typically, hzAbove() and hzBelow() are used as a simpler interface to hzOffset(). Selected horizons can be returned as a complete SoilProfileCollection (SPC = TRUE), a list of horizon data row indices (SPC = FALSE, simplify = FALSE), or as a numeric vector of horizon data row indices (SPC = FALSE, simplify = TRUE).

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)

Value

One of:

SoilProfileCollection: when SPC = TRUE
list of horizon row indices when SPC = FALSE and simplify = FALSE
vector of horizon row indices: when SPC = FALSE and simplify = TRUE

The return value will not include data from profiles which have no matching reference horizons.

Arguments

x: SoilProfileCollection
...: comma-separated set of logical expressions, in context of horizon data, length for each expression must match number of horizons in x
offset: integer vector or NULL, when specified this is the [, j] (horizon/slice) index definining the horizons above or below a reference horizon that should be returned. see details
SPC: logical, return a SoilProfileCollection subset to selected horizons
simplify: logical, flatten list of horizon row indices into a numeric vector
single: logical, interpret multiple matching reference horizons as a single horizon, defined by max(top) - min(bottom)
hzidx: integer vector of target horizon row indices, typically calculated by hzAbove() and hzBelow()

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 (single = TRUE), defined by min(top) - max(bottom), will ensure that only selected horizons are returned.

The offset argument controls which "horizons above" or "horizons below" reference horizon(s) are selected, using the SoilProfileCollection [, j] (horizon/slice) notation. Possible values and their interpretation are as follows:

offset = NULL: select all horizons above or below reference horizon(s)
offset = 1: select the first horizon above or below reference horizon(s)
offset = 1:2: select the first and second horizons above or below reference horizon(s)
offset = 1:10: safely select the 1st -> 10th horizons, even if there are fewer, above or below reference horizon(s)

Examples

Run this code


# 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)

Run the code above in your browser using DataLab