kde: Create (a) kernel density estimate(s)

Description

Creates one or more kernel density estimates using a combination of the Botev (2010) bandwidth selector and the Abramson (1982) adaptive kernel bandwidth modifier.

Usage

kde(x, ...)
# S3 method for default
kde(x, from = NA, to = NA, bw = NA, adaptive = TRUE,
  log = FALSE, n = 512, plot = TRUE, pch = NA, xlab = "age [Ma]",
  ylab = "", kde.col = rgb(1, 0, 1, 0.6), hist.col = rgb(0, 1, 0, 0.2),
  show.hist = TRUE, bty = "n", binwidth = NA, ncol = NA, ...)
# S3 method for UPb
kde(x, from = NA, to = NA, bw = NA, adaptive = TRUE,
  log = FALSE, n = 512, plot = TRUE, pch = NA, xlab = "age [Ma]",
  ylab = "", kde.col = rgb(1, 0, 1, 0.6), hist.col = rgb(0, 1, 0, 0.2),
  show.hist = TRUE, bty = "n", binwidth = NA, ncol = NA, type = 4,
  cutoff.76 = 1100, cutoff.disc = c(-15, 5), ...)
# S3 method for detritals
kde(x, from = NA, to = NA, bw = NA, adaptive = TRUE,
  log = FALSE, n = 512, plot = TRUE, pch = NA, xlab = "age [Ma]",
  ylab = "", kde.col = rgb(1, 0, 1, 0.6), hist.col = rgb(0, 1, 0, 0.2),
  show.hist = TRUE, bty = "n", binwidth = NA, ncol = NA,
  samebandwidth = TRUE, normalise = TRUE, ...)
# S3 method for PbPb
kde(x, from = NA, to = NA, bw = NA, adaptive = TRUE,
  log = FALSE, n = 512, plot = TRUE, pch = NA, xlab = "age [Ma]",
  ylab = "", kde.col = rgb(1, 0, 1, 0.6), hist.col = rgb(0, 1, 0, 0.2),
  show.hist = TRUE, bty = "n", binwidth = NA, ncol = NA, i2i = FALSE,
  ...)
# S3 method for ArAr
kde(x, from = NA, to = NA, bw = NA, adaptive = TRUE,
  log = FALSE, n = 512, plot = TRUE, pch = NA, xlab = "age [Ma]",
  ylab = "", kde.col = rgb(1, 0, 1, 0.6), hist.col = rgb(0, 1, 0, 0.2),
  show.hist = TRUE, bty = "n", binwidth = NA, ncol = NA, i2i = FALSE,
  ...)
# S3 method for ReOs
kde(x, from = NA, to = NA, bw = NA, adaptive = TRUE,
  log = FALSE, n = 512, plot = TRUE, pch = NA, xlab = "age [Ma]",
  ylab = "", kde.col = rgb(1, 0, 1, 0.6), hist.col = rgb(0, 1, 0, 0.2),
  show.hist = TRUE, bty = "n", binwidth = NA, ncol = NA, i2i = TRUE,
  ...)
# S3 method for SmNd
kde(x, from = NA, to = NA, bw = NA, adaptive = TRUE,
  log = FALSE, n = 512, plot = TRUE, pch = NA, xlab = "age [Ma]",
  ylab = "", kde.col = rgb(1, 0, 1, 0.6), hist.col = rgb(0, 1, 0, 0.2),
  show.hist = TRUE, bty = "n", binwidth = NA, ncol = NA, i2i = TRUE,
  ...)
# S3 method for RbSr
kde(x, from = NA, to = NA, bw = NA, adaptive = TRUE,
  log = FALSE, n = 512, plot = TRUE, pch = NA, xlab = "age [Ma]",
  ylab = "", kde.col = rgb(1, 0, 1, 0.6), hist.col = rgb(0, 1, 0, 0.2),
  show.hist = TRUE, bty = "n", binwidth = NA, ncol = NA, i2i = TRUE,
  ...)
# S3 method for LuHf
kde(x, from = NA, to = NA, bw = NA, adaptive = TRUE,
  log = FALSE, n = 512, plot = TRUE, pch = NA, xlab = "age [Ma]",
  ylab = "", kde.col = rgb(1, 0, 1, 0.6), hist.col = rgb(0, 1, 0, 0.2),
  show.hist = TRUE, bty = "n", binwidth = NA, ncol = NA, i2i = TRUE,
  ...)
# S3 method for UThHe
kde(x, from = NA, to = NA, bw = NA, adaptive = TRUE,
  log = FALSE, n = 512, plot = TRUE, pch = NA, xlab = "age [Ma]",
  ylab = "", kde.col = rgb(1, 0, 1, 0.6), hist.col = rgb(0, 1, 0, 0.2),
  show.hist = TRUE, bty = "n", binwidth = NA, ncol = NA, ...)
# S3 method for fissiontracks
kde(x, from = NA, to = NA, bw = NA,
  adaptive = TRUE, log = FALSE, n = 512, plot = TRUE, pch = NA,
  xlab = "age [Ma]", ylab = "", kde.col = rgb(1, 0, 1, 0.6),
  hist.col = rgb(0, 1, 0, 0.2), show.hist = TRUE, bty = "n",
  binwidth = NA, ncol = NA, ...)

Arguments

a vector of numbers OR an object of class UPb, PbPb, ArAr, ReOs, SmNd, RbSr, UThHe, fissiontracks or detrital

...

optional arguments to be passed on to density

from

minimum age of the time axis. If NULL, this is set automatically

maximum age of the time axis. If NULL, this is set automatically

the bandwidth of the KDE. If NULL, bw will be calculated automatically using botev()

adaptive

logical flag controlling if the adaptive KDE modifier of Abramson (1982) is used

log

transform the ages to a log scale if TRUE

horizontal resolution of the density estimate

plot

show the KDE as a plot

pch

the symbol used to show the samples. May be a vector. Set pch=NA to turn them off.

xlab

the x-axis label

ylab

the y-axis label

kde.col

the fill colour of the KDE specified as a four element vector of r, g, b, alpha values

hist.col

the fill colour of the histogram specified as a four element vector of r, g, b, alpha values

show.hist

logical flag indicating whether a histogram should be added to the KDE

bty

change to "o", "l", "7", "c", "u", or "]" if you want to draw a box around the plot

binwidth

scalar width of the histogram bins, in Myr if x$log = FALSE, or as a fractional value if x$log = TRUE. Sturges' Rule is used if binwidth = NA

ncol

scalar value indicating the number of columns over which the KDEs should be divided. This option is only used if x has class detritals.

type

scalar indicating whether to plot the $^{207}$ Pb/ $^{235}$ U age (type=1), the $^{206}$ Pb/ $^{238}$ U age (type=2), the $^{207}$ Pb/ $^{206}$ Pb age (type=3), the $^{207}$ Pb/ $^{206}$ Pb- $^{206}$ Pb/ $^{238}$ U age (type=4), or the (Wetherill) concordia age (type=5)

cutoff.76

the age (in Ma) below which the $^{206}$ Pb/ $^{238}$ U and above which the $^{207}$ Pb/ $^{206}$ Pb age is used. This parameter is only used if type=4.

cutoff.disc

two element vector with the maximum and minimum percentage discordance allowed between the $^{207}$ Pb/ $^{235}$ U and $^{206}$ Pb/ $^{238}$ U age (if $^{206}$ Pb/ $^{238}$ U < cutoff.76) or between the $^{206}$ Pb/ $^{238}$ U and $^{207}$ Pb/ $^{206}$ Pb age (if $^{206}$ Pb/ $^{238}$ U > cutoff.76). Set cutoff.disc=NA if you do not want to use this filter.

samebandwidth

logical flag indicating whether the same bandwidth should be used for all samples. If samebandwidth = TRUE and bw = NULL, then the function will use the median bandwidth of all the samples.

normalise

logical flag indicating whether or not the KDEs should all integrate to the same value.

i2i

`isochron to intercept': calculates the initial (aka `inherited', `excess', or `common') $^{40}$ Ar/ $^{36}$ Ar, $^{207}$ Pb/ $^{204}$ Pb, $^{87}$ Sr/ $^{86}$ Sr, $^{143}$ Nd/ $^{144}$ Nd, $^{187}$ Os/ $^{188}$ Os or $^{176}$ Hf/ $^{177}$ Hf ratio from an isochron fit. Setting i2i to FALSE uses the default values stored in settings('iratio',...) or zero (for the Pb-Pb method).

Value

if plot = TRUE, returns an object of class KDE, i.e. a list containing the following items:

x: horizontal plot coordinates
y: vertical plot coordinates
bw: the base bandwidth of the density estimate
ages: the data values from the input to the kde function

or, if x has class =detritals, an object of class KDEs, i.e. a list containing the following items:

kdes: a named list with objects of class KDE
from: the beginning of the common time scale
to: the end of the common time scale
themax: the maximum probability density of all the KDEs
xlabel: the x-axis label to be used by plot.KDEs

References

Abramson, I.S., 1982. On bandwidth variation in kernel estimates-a square root law. The annals of Statistics, pp.1217-1223.

Botev, Z. I., J. F. Grotowski, and D. P. Kroese. "Kernel density estimation via diffusion." The Annals of Statistics 38.5 (2010): 2916-2957.

Vermeesch, P., 2012. On the visualisation of detrital age distributions. Chemical Geology, 312, pp.190-194.

Examples

Run this code

# NOT RUN {
data(examples)
kde(examples$DZ[['N1']],kernel="epanechnikov")
kde(examples$DZ,from=0,to=3000)
# }