Soil Taxonomy Dendrogram

Plot a dendrogram based on the first 4 levels of Soil Taxonomy, with soil profiles hanging below. A dissimilarity matrix is computed using Gower's distance metric for nominal (KST.order = FALSE) or ordinal (KST.order = TRUE) scale variables, based on soil order, suborder, greatgroup, and subgroup taxa.

SoilTaxonomyDendrogram(
  spc,
  KST.order = TRUE,
  rotationOrder = NULL,
  level = c(soilorder = "soilorder", suborder = "suborder", greatgroup = "greatgroup",
    subgroup = "subgroup"),
  cluster.method = c("divisive", "agglomerative"),
  cluster.args = list(),
  name = "hzname",
  name.style = "center-center",
  id.style = "side",
  n.depth.ticks = 6,
  scaling.factor = 0.015,
  cex.names = 0.75,
  cex.id = 0.75,
  width = 0.25,
  y.offset = 0.5,
  shrink = FALSE,
  font.id = 2,
  cex.taxon.labels = 0.66,
  font.taxon.labels = 3,
  dend.color = par("fg"),
  dend.width = 1,
  dend.type = c("phylogram", "cladogram"),
  max.depth = ifelse(is.infinite(max(spc)), 200, max(spc)),
  ...
)

Arguments

spc

a SoilProfileCollection object, typically returned by soilDB::fetchOSD

KST.order

logical, encode / cluster taxa via ordinal factors, based on ordering within Keys to Soil Taxonomy

rotationOrder

character vector of profile IDs with desired ordering of leaves in the dendrogram from left to right; exact ordering is not always possible

level

character. One or more site-level columns in spc. Default: "soilorder", "suborder", "greatgroup" and "subgroup"

cluster.method

Either "divisive" (cluster::diana(); default) or "agglomerative" (cluster::agnes())

cluster.args

Optional: additional arguments for cluster::diana() or cluster::agnes() cluster methods

name

column name containing horizon names

name.style

passed to aqp::plotSPC

id.style

passed to aqp::plotSPC

n.depth.ticks

suggested number of ticks on the depth axis

scaling.factor

scaling factor used to convert depth units into plotting units

cex.names

character scaling for horizon names

cex.id

character scaling for profile IDs

width

width of profiles

y.offset

vertical offset between dendrogram and profiles

shrink

logical, should long horizon names be shrunk by 80% ?

font.id

integer, font style applied to profile id, default is 2 (bold)

cex.taxon.labels

numeric, character scaling for taxonomic information

font.taxon.labels

integer, font style applied to taxa labels, default is 3 (italic)

dend.color

dendrogram line color

dend.width

dendrogram line width

dend.type

dendrogram type, passed to plot.phylo(), either "phylogram" or "cladogram"

max.depth

depth at which profiles are truncated for plotting

...

additional arguments to aqp::plotSPC

Value

An invisibly-returned list containing:

• dist: pair-wise dissimilarity matrix

• order: final ordering of hclust leaves

Details

This function looks for specific site-level attributes named: "soilorder", "suborder", "greatgroup", and "subgroup", or their NASIS physical column name analogues "taxorder", "taxsuborder", "taxgrtgroup", and "taxsubgrp". See https://github.com/ncss-tech/sharpshootR/blob/master/misc/soilTaxonomyDendrogram-examples.R for some examples.

The rotationOrder argument uses ape::rotateConstr() to reorder leaves within the hclust representation of the ST hierarchy. Perfect sorting is not always possible.

Author

D.E. Beaudette

Examples

# built-in data, same as results from soilDB::fetchOSD()
data("OSDexamples")

# examples using first 8 profiles

# KST-style ordering
SoilTaxonomyDendrogram(
  OSDexamples$SPC[1:8, ], width = 0.3, name.style = 'center-center',
  KST.order = TRUE, axis.line.offset = -4, scaling.factor = 0.014
)
#> `axis.line.offset` is now deprecated, please use `depth.axis` argument


# classic ordering, based on nominal scale variables (un-ordered factors)
SoilTaxonomyDendrogram(
  OSDexamples$SPC[1:8, ], width = 0.3, name.style = 'center-center',
  KST.order = FALSE, axis.line.offset = -4, scaling.factor = 0.014
)
#> `axis.line.offset` is now deprecated, please use `depth.axis` argument


# adjust taxon label font and font size
SoilTaxonomyDendrogram(
  OSDexamples$SPC[1:15, ], width = 0.3, name.style = 'center-center',
  KST.order = FALSE, axis.line.offset = -4, scaling.factor = 0.014,
  font.taxon.labels = 2, cex.taxon.labels = 0.55
)
#> `axis.line.offset` is now deprecated, please use `depth.axis` argument


# cladogram vs. dendrogram
# truncate profiles at 150cm
SoilTaxonomyDendrogram(
  OSDexamples$SPC[1:16, ], width = 0.3, name.style = 'center-center',
  KST.order = TRUE, axis.line.offset = -4, scaling.factor = 0.02,
  font.taxon.labels = 1, cex.taxon.labels = 0.55,
  dend.type = 'cladogram', max.depth = 150
)
#> `axis.line.offset` is now deprecated, please use `depth.axis` argument