SoilTaxonomyDendrogram: Soil Taxonomy Dendrogram

In sharpshootR: A Soil Survey Toolkit

Soil Taxonomy Dendrogram

Description

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.

Usage

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

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.

Value

An invisibly-returned list containing:

• dist: pair-wise dissimilarity matrix

• order: final ordering of hclust leaves

Author(s)

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
)

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

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

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

sharpshootR documentation built on Oct. 23, 2024, 1:06 a.m.