generalize.hz {aqp}

Generalize Horizon Names

Description

Generalize a vector of horizon names, based on new classes, and REGEX patterns. Or create a new column ghl in a SoilProfileCollection (requires a horizon designation name to be defined for the collection, see details)

Usage

generalize.hz(
  x,
  new,
  pattern,
  non.matching.code = "not-used",
  hzdepm = NULL,
  ordered = !missing(hzdepm),
  ...
)

## S4 method for signature 'character'
generalizeHz(
  x,
  new,
  pattern,
  non.matching.code = "not-used",
  hzdepm = NULL,
  ordered = !missing(hzdepm),
  ...
)

## S4 method for signature 'SoilProfileCollection'
generalizeHz(
  x,
  new,
  pattern,
  non.matching.code = "not-used",
  hzdepm = NULL,
  ordered = !missing(hzdepm),
  ghl = "genhz",
  ...
)

Arguments

x

character vector of horizon names or a SoilProfileCollection object

new

character vector of generalized horizon labels (GHL)

pattern

character vector of REGEX patterns, same length as new

non.matching.code

character, label used for any horizon not matched by pattern

hzdepm

numeric vector of horizon mid-points; NA values in hzdepm will result in non.matching.code (or NA if not defined) in result

ordered

logical, TRUE when hzdepm argument is specified

...

additional arguments passed to grep() such as perl = TRUE for advanced REGEX

ghl

Generalized Horizon Designation column name (to be created/updated when x is a SoilProfileCollection)

Details

When x is a SoilProfileCollection the ghl column will be updated with the factor results. This requires that the "horizon designation name" metadata be defined for the collection to set the column for input designations.

Value

factor (possibly an ordered factor) of the same length as x (if character) or as number of horizons in x (if SoilProfileCollection)

Author(s)

D.E. Beaudette

References

Beaudette, D.E., Roudier, P., Skovlin, J. (2016). Probabilistic Representation of Genetic Soil Horizons. In: Hartemink, A., Minasny, B. (eds) Digital Soil Morphometrics. Progress in Soil Science. Springer, Cham. https://doi.org/10.1007/978-3-319-28295-4_18

See Also

hzdesgnname()

Examples

data(sp1)

# check original distribution of hz designations
table(sp1$name)

# generalized horizon labels
# character vector input
sp1$genhz <- generalizeHz(
  sp1$name,
  new = c('O','A','B','C','R'),
  pattern = c('O', '^A','^B','C','R'),
  ordered = TRUE
)

# see how we did / what we missed
table(sp1$genhz, sp1$name)


## a more advanced example, requries `perl = TRUE`
# example data
x <- c('A', 'AC', 'Bt1', '^AC', 'C', 'BC', 'CB')

# new labels
n <- c('A', '^AC', 'C')

# patterns:
# "A anywhere in the name"
# "literal '^A' anywhere in the name"
# "C anywhere in name, but without preceding A"
p <- c('A', '^A', '(?<!A)C')

# note additional argument
res <- generalizeHz(
  x, 
  new = n, 
  pattern = p, 
  perl = TRUE
)

# double-check: OK
table(res, x)

## apply to a SoilProfileCollection
data(sp1)
depths(sp1) <- id ~ top + bottom

# must set horizon designation metadata
hzdesgnname(sp1) <- 'name'

# result is a SoilProfileCollection
x <- generalizeHz(
  sp1,
  new = c('O','A','B','C','R'),
  pattern = c('O', '^A','^B','C','R'),
  ordered = TRUE
)

# GHL stored in 'genhz' column
x$genhz

# GHL metadata is set
GHL(x)