plotKDE: Plot one or several KDEs using ggplot2.

In thegeologician/ggprovenance: Plotting of sediment provenance data, ggplot-style

Description

plotKDE takes a simple named list containing the ages measured on each sample, and produces rich graphics of kernel density estimates (KDEs). A multitude of parameters makes the function complex, but gives fine control over the final graphic, in many cases producing output that needs no further editing in other software, see examples and vignette. Although syntax differs from ggplot functions, the concept of mapping data values (from parameter categories) onto aesthetics remains.

Usage

plotKDE(ages, title, limits = c(0, max(unlist(ages), na.rm = TRUE)),
  plotonly = names(ages), categories, mapping, breaks = NULL,
  bandwidth = NA, splitat = NA, markers = c("none", "dash", "circle"),
  logx = FALSE, histogram = FALSE, binwidth = bandwidth,
  adaptive = TRUE, stack = c("equal", "close", "dense"),
  normalise = c("area", "height", "none"), lowcount = 80, ...)

Arguments

ages	A named list of ages for each sample/data set.
title	Overal plot title.
limits	Numerical vector giving the range of ages to plot.
plotonly	Vector of names of samples to plot.
categories	A data frame giving categorising information on samples.
mapping	Aesthetic mapping, see aes.
breaks	Numerical vector of break values along x-axis.
bandwidth	Bandwidth for KDE and histogram calculation.
splitat	Numerical, split plots into left and right plot.
markers	Character, type of tick marks indicating input data.
logx	Boolean, plot x-axis in log-scale.
histogram	Boolean, add histogram.
binwidth	Bin width for histograms.
adaptive	Boolean, use Abramson's adaptive bandwith modifier.
stack	Character, stack plots more closely (see details).
normalise	Character, normalise KDEs to height or area (default).
lowcount	Minimum number for robust data set.
...	Additional parameters passed on to KDEs.

Details

If limits is of length 2 it specifies the range of ages to plot. This will be split at age splitat, if given. If limits is of length 4, it specifies the ranges for the left and right half plots, respectively, and overrides splitat. KDEs and histograms are calculated on the whole data, and normalised before truncation at limits.

If bandwith = NA (default), the median of calculated 'optimal bandwidths' (function botev of package provenance) is used on all KDEs. If a numerical value is given, this will be used for all KDEs. If bandwidth = -1, the individual optimal bandwidths are used for each KDE.

splitat specifies an age to split the plots into half at. The two halfes will both oppupy half the available space, at differing x scales to accomodate the range especified by limits overall.

categories contains any meta-information on samples, one line per sample. Any categories given can be mapped onto aesthetics with the mapping parameter.

markers indicates the type of data markers along the x-axis to indicate sampled ages. Possible values are "dash", "circle", or "none" (default).

If histograms are plotted (histogram = TRUE), the bin width can optionally be set by specifying binwidth. Values of NA or -1 both cause the binwidth to be set automatically to the median of 'optimal bandwidths'.

stack specifies vertical spacing of stacked plots. One of "equal" (default), giving each plot the same height, "close", letting each plot only take up as much space as its maximum y value requires, and "dense", stacking non-filled KDEs as closely as possible. "close" has no effect if normalise="height", and "dense" only works when mapping=aes(fill=NULL) is specified.

normalise may be one of "area" (default), making KDEs the same area, "height", making KDEs the same height, or "none". If histogram = TRUE, KDEs are always normalised to area.

lowcount gives the minimum number to consider a data set robust. Smaller sets will be drawn in a dashed line, unless the linetype aestetic is specified in mapping. Set to -1 to disable.

Value

A ggplot object containing the specified plot.

Note

normalise = "height" can be misleading, visually overemphasising distributions with broad peaks.

Tip: The returned ggplot object can be further modified with ggplot2's functions (e.g. theme) and saved in many file formats using ggsave.

See Also

theme, ggsave, plot.KDE

thegeologician/ggprovenance documentation built on Sept. 26, 2021, 8:59 a.m.