aqp: SoilProfileCollection-plotting-methods – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

SoilProfileCollection-plotting-methods

Create Soil Profile Sketches

Description

Generate a diagram of soil profile sketches from a SoilProfileCollection object. The Introduction to SoilProfileCollection Objects tutorial contains many examples and discussion of the large number of arguments to this function.

Usage

plotSPC(
  x,
  color = "soil_color",
  width = 0.2,
  name = NULL,
  name.style = "right-center",
  label = idname(x),
  hz.depths = FALSE,
  alt.label = NULL,
  alt.label.col = "black",
  cex.names = 0.5,
  cex.depth.axis = cex.names,
  cex.id = cex.names + (0.2 * cex.names),
  font.id = 2,
  print.id = TRUE,
  id.style = "auto",
  plot.order = 1:length(x),
  relative.pos = 1:length(x),
  add = FALSE,
  scaling.factor = 1,
  y.offset = rep(0, times = length(x)),
  x.idx.offset = 0,
  n = length(x),
  max.depth = ifelse(is.infinite(max(x)), 200, max(x)),
  n.depth.ticks = 5,
  shrink = FALSE,
  shrink.cutoff = 3,
  shrink.thin = NULL,
  abbr = FALSE,
  abbr.cutoff = 5,
  divide.hz = TRUE,
  hz.distinctness.offset = NULL,
  hz.topography.offset = NULL,
  hz.boundary.lty = NULL,
  axis.line.offset = -2.5,
  plot.depth.axis = TRUE,
  density = NULL,
  show.legend = TRUE,
  col.label = color,
  col.palette = c("#5E4FA2", "#3288BD", "#66C2A5", "#ABDDA4", "#E6F598", "#FEE08B",
    "#FDAE61", "#F46D43", "#D53E4F", "#9E0142"),
  col.palette.bias = 1,
  col.legend.cex = 1,
  n.legend = 8,
  lwd = 1,
  lty = 1,
  default.color = grey(0.95),
  ...
)

## S4 method for signature 'SoilProfileCollection,ANY'
## note: y argument in generic definition is not currently used
plot(x, y, ...)

Arguments

`x`	a `SoilProfileCollection` object
`color`	quoted column name containing R-compatible color descriptions, or numeric / categorical data to be displayed thematically; see details
`width`	scaling of profile widths (typically 0.1 - 0.4)
`name`	quoted column name of the (horizon-level) attribute containing horizon designations, can be left as `NULL` and horizon designation column will be selected via `hzdesgnname(x)`. Suppress horizon name printing by setting `name=NA`.
`name.style`	one of several possible horizon designations labeling styles: 'right-center' (aqp default), 'left-top', 'left-center'
`label`	quoted column name of the (site-level) attribute used to identify profile sketches
`hz.depths`	logical, annotate horizon top depths to the right of each sketch (FALSE)
`alt.label`	quoted column name of the (site-level) attribute used for secondary annotation
`alt.label.col`	color used for secondary annotation text
`cex.names`	baseline character scaling applied to all text labels
`cex.depth.axis`	character scaling applied to depth scale
`cex.id`	character scaling applied to `label`
`font.id`	font style applied to `label`, default is 2 (bold)
`print.id`	logical, print `label` above/beside each profile? (TRUE)
`id.style`	`label` printing style: 'auto' (default) = simple heuristic used to select from: 'top' = centered above each profile, 'side' = 'along the top-left edge of profiles'
`plot.order`	integer vector describing the order in which individual soil profiles should be plotted
`relative.pos`	vector of relative positions along the x-axis, within {1, n}, ignores `plot.order` see details
`add`	logical, add to an existing figure
`scaling.factor`	vertical scaling of profile depths, useful for adding profiles to an existing figure
`y.offset`	numeric vector of vertical offset for top of profiles in depth units of `x`, can either be a single numeric value or vector of length = `length(x)`
`x.idx.offset`	integer specifying horizontal offset from 0 (left-hand edge)
`n`	integer describing amount of space along x-axis to allocate, defaults to `length(x)`
`max.depth`	suggested lower depth boundary of plot
`n.depth.ticks`	suggested number of ticks in depth scale
`shrink`	logical, reduce character scaling for 'long' horizon by 80%
`shrink.cutoff`	character length defining 'long' horizon names
`shrink.thin`	integer, horizon thickness threshold for shrinking horizon names by 80%, only activated when `shrink = TRUE` (`NULL` = no shrinkage)
`abbr`	logical, abbreviate `label`
`abbr.cutoff`	suggested minimum length for abbreviated `label`
`divide.hz`	logical, divide horizons with line segment? (TRUE), see details
`hz.distinctness.offset`	NULL, or quoted column name (horizon-level attribute) containing vertical offsets used to depict horizon boundary distinctness (same units as profiles), see details and codehzDistinctnessCodeToOffset
`hz.topography.offset`	NULL, or quoted column name (horizon-level attribute) containing offsets used to depict horizon boundary topography (same units as profiles), see details and codehzTopographyCodeToOffset
`hz.boundary.lty`	quoted column name (horizon-level attribute) containing line style (integers) used to encode horizon topography
`axis.line.offset`	horizontal offset applied to depth axis (default is -2.5, larger numbers move the axis to the right)
`plot.depth.axis`	logical, plot depth axis? (default is TRUE)
`density`	fill density used for horizon color shading, either a single integer or a quoted column name (horizon-level attribute) containing integer values (default is NULL, no shading)
`show.legend`	logical, show legend? (default is TRUE)
`col.label`	thematic legend title
`col.palette`	color palette used for thematic sketches (default is `rev(brewer.pal(10, 'Spectral'))`)
`col.palette.bias`	color ramp bias (skew), see `colorRamp`
`col.legend.cex`	scaling of thematic legend
`n.legend`	approximate number of classes used in numeric legend, max number of items per row in categorical legend
`lwd`	line width multiplier used for sketches
`lty`	line style used for sketches
`default.color`	default horizon fill color used when `color` attribute is `NA`
`...`	other arguments passed into lower level plotting functions
`y`	(not used)

Details

Depth limits (max.depth) and number of depth ticks (n.depth.ticks) are suggestions to the pretty function. You may have to tinker with both parameters to get what you want.

The 'side' id.style is useful when plotting a large collection of profiles, and/or, when profile IDs are long.

If the column containing horizon designations is not specified (the name argument), a column (presumed to contain horizon designation labels) is guessed based on regular expression matching of the pattern 'name'– this usually works, but it is best to manual specify the name of the column containing horizon designations.

The color argument can either name a column containing R-compatible colors, possibly created via munsell2rgb, or column containing either numeric or categorical (either factor or character) values. In the second case, values are converted into colors and displayed along with a simple legend above the plot. Note that this functionality makes several assumptions about plot geometry and is most useful in an interactive setting.

Adjustments to the legend can be specified via col.label (legend title), col.palette (palette of colors, automatically expanded), col.legend.cex (legend scaling), and n.legend (approximate number of classes for numeric variables, or, maximum number of legend items per row for categorical variables). Currently, plotSPC will only generate two rows of legend items. Consider reducing the number of classes if two rows isn't enough room.

Profile sketches can be added according to relative positions along the x-axis (vs. integer sequence) via relative.pos argument. This should be a vector of positions within {1,n} that are used for horizontal placement. Default values are 1:length(x). Care must be taken when both plot.order and relative.pos are used simultaneously: relative.pos specifies horizontal placement after sorting. addDiagnosticBracket and addVolumeFraction use the relative.pos values for subsequent annotation.

Relative positions that are too close will result in overplotting of sketches. Adjustments to relative positions such that overlap is minimized can be performed with fixOverlap(pos), where pos is the original vector of relative positions.

The x.idx.offset argument can be used to shift a collection of pedons from left to right in the figure. This can be useful when plotting several different SoilProfileCollection objects within the same figure. Space must be pre-allocated in the first plotting call, with an offset specified in the second call. See examples below.

Note

A new plot of soil profiles is generated, or optionally added to an existing plot.

Author(s)

D.E. Beaudette

References

Beaudette, D.E., Roudier P., and A.T. O'Geen. 2013. Algorithms for Quantitative Pedology: A Toolkit for Soil Scientists. Computers & Geosciences. 52:258 - 268.

Examples

# example data
data(sp1)
# usually best to adjust margins
par(mar=c(0,0,3,0))

# add color vector
sp1$soil_color <- with(sp1, munsell2rgb(hue, value, chroma))

# promote to SoilProfileCollection
depths(sp1) <- id ~ top + bottom

# plot profiles
plot(sp1, id.style='side')

# title, note line argument:
title('Sample Data 1', line=1, cex.main=0.75)

# plot profiles without horizon-line divisions
plot(sp1, divide.hz=FALSE)

# add dashed lines illustrating horizon boundary distinctness
sp1$hzD <- hzDistinctnessCodeToOffset(sp1$bound_distinct)
plot(sp1, hz.distinctness.offset='hzD')

# plot horizon color according to some property
data(sp4)
depths(sp4) <- id ~ top + bottom
plot(sp4, color='clay')

# another example
data(sp2)
depths(sp2) <- id ~ top + bottom
site(sp2) <- ~ surface

# label with site-level attribute: `surface`
plot(sp2, label='surface', plot.order=order(sp2$surface))

# example using a categorical attribute
plot(sp2, color = "plasticity")

# plot two SPC objects in the same figure
par(mar=c(1,1,1,1))
# plot the first SPC object and
# allocate space for the second SPC object
plot(sp1, n=length(sp1) + length(sp2))
# plot the second SPC, starting from the first empty space
plot(sp2, x.idx.offset=length(sp1), add=TRUE)


##
## demonstrate horizon designation shrinkage
##

data("jacobs2000")

# shrink "long" horizon names
plotSPC(
  jacobs2000, 
  name.style = 'center-center', 
  shrink = TRUE, 
  cex.names = 0.8
)

# shrink horizon names in "thin" horizons
plotSPC(
  jacobs2000, 
  name.style = 'center-center', 
  shrink = TRUE, 
  shrink.thin = 15,
  cex.names = 0.8,
)


##
## demonstrate adaptive legend
##

data(sp3)
depths(sp3) <- id ~ top + bottom

# make some fake categorical data
horizons(sp3)$fake.data <- sample(letters[1:15], size = nrow(sp3), replace=TRUE)

# better margins
par(mar=c(0,0,3,1))

# note that there are enough colors for 15 classes (vs. previous limit of 10)
# note that the legend is split into 2 rows when length(classes) > n.legend argument
plot(sp3, color='fake.data', name='fake.data', cex.names=0.8)

# make enough room in a single legend row
plot(sp3, color='fake.data', name='fake.data', cex.names=0.8, n.legend=15)


##
## demonstrate y.offset argument
## must be of length 1 or length(x)
##

# example data and local copy
data("jacobs2000")
x <- jacobs2000

# y-axis offsets, simulating a elevation along a hillslope sequence
# same units as horizon depths in `x`
y.offset <- c(-5, -10, 22, 65, 35, 15, 12)

par(mar = c(0, 0, 2, 2))

# y-offset at 0
plotSPC(x, color = 'matrix_color', cex.names = 0.66)

# constant adjustment to y-offset
plotSPC(x, color = 'matrix_color', cex.names = 0.66, y.offset = 50)

# attempt using invalid y.offset
# warning issued and default value of '0' used
# plotSPC(x, color = 'matrix_color', cex.names = 0.66, y.offset = 1:2)

# variable y-offset
par(mar = c(0, 0, 2, 0))
plotSPC(
  x, 
  y.offset = y.offset, 
  color = 'matrix_color', 
  cex.names = 0.66, 
  hz.depths = TRUE, 
  name.style = 'center-center'
)



# random y-axis offsets
yoff <- runif(n = length(x), min = 1, max = 100)
# random gradient of x-positions
xoff <- runif(n = length(x), min = 1, max = length(x))

# align / adjust relative x positions
set.seed(111)
pos <- alignTransect(xoff, x.min = 1, x.max = length(x))

par(mar = c(0.5, 0.5, 0.5, 0.5))
plotSPC(x, 
        plot.order = pos$order, 
        relative.pos = pos$relative.pos, 
        y.offset = y.offset, 
        color = 'matrix_color', 
        cex.names = 0.66, 
        hz.depths = TRUE, 
        name.style = 'center-center'
)

box()

aqp

Algorithms for Quantitative Pedology

v1.29

GPL (>= 3)

Authors

Dylan Beaudette [aut, cre], Pierre Roudier [aut, ctb], Andrew Brown [aut, ctb]

Initial release

2021-04-05