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

Description Usage Arguments Details Value References See Also Examples

View source: R/kde.R

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
kde(x, ...)

## Default S3 method:
kde(x, from = NA, to = NA, bw = NA,
  adaptive = TRUE, log = FALSE, n = 512, plot = TRUE, pch = "|",
  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, hide = NULL, ...)

## S3 method for class 'UPb'
kde(x, from = NA, to = NA, bw = NA, adaptive = TRUE,
  log = FALSE, n = 512, plot = TRUE, pch = "|",
  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, type = 4, cutoff.76 = 1100, cutoff.disc = c(-15,
  5), common.Pb = 0, hide = NULL, ...)

## S3 method for class '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,
  hide = NULL, ...)

## S3 method for class 'PbPb'
kde(x, from = NA, to = NA, bw = NA, adaptive = TRUE,
  log = FALSE, n = 512, plot = TRUE, pch = "|",
  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, common.Pb = 1, hide = NULL, ...)

## S3 method for class 'ArAr'
kde(x, from = NA, to = NA, bw = NA, adaptive = TRUE,
  log = FALSE, n = 512, plot = TRUE, pch = "|",
  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, i2i = FALSE, hide = NULL, ...)

## S3 method for class 'KCa'
kde(x, from = NA, to = NA, bw = NA, adaptive = TRUE,
  log = FALSE, n = 512, plot = TRUE, pch = "|",
  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, i2i = FALSE, hide = NULL, ...)

## S3 method for class 'ThU'
kde(x, from = NA, to = NA, bw = NA, adaptive = TRUE,
  log = FALSE, n = 512, plot = TRUE, pch = "|",
  xlab = "age [ka]", ylab = "", kde.col = rgb(1, 0, 1, 0.6),
  hist.col = rgb(0, 1, 0, 0.2), show.hist = TRUE, bty = "n",
  binwidth = NA, i2i = FALSE, detritus = 0, Th02 = c(0, 0),
  Th02U48 = c(0, 0, 1e+06, 0, 0, 0, 0, 0, 0), hide = NULL, ...)

## S3 method for class 'ReOs'
kde(x, from = NA, to = NA, bw = NA, adaptive = TRUE,
  log = FALSE, n = 512, plot = TRUE, pch = "|",
  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, i2i = TRUE, hide = NULL, ...)

## S3 method for class 'SmNd'
kde(x, from = NA, to = NA, bw = NA, adaptive = TRUE,
  log = FALSE, n = 512, plot = TRUE, pch = "|",
  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, i2i = TRUE, hide = NULL, ...)

## S3 method for class 'RbSr'
kde(x, from = NA, to = NA, bw = NA, adaptive = TRUE,
  log = FALSE, n = 512, plot = TRUE, pch = "|",
  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, i2i = TRUE, hide = NULL, ...)

## S3 method for class 'LuHf'
kde(x, from = NA, to = NA, bw = NA, adaptive = TRUE,
  log = FALSE, n = 512, plot = TRUE, pch = "|",
  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, i2i = TRUE, hide = NULL, ...)

## S3 method for class 'UThHe'
kde(x, from = NA, to = NA, bw = NA,
  adaptive = TRUE, log = FALSE, n = 512, plot = TRUE, pch = "|",
  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, hide = NULL, ...)

## S3 method for class 'fissiontracks'
kde(x, from = NA, to = NA, bw = NA,
  adaptive = TRUE, log = FALSE, n = 512, plot = TRUE, pch = "|",
  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, hide = NULL, ...)

Arguments

x

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

...

optional arguments to be passed on to R's density function.

from

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

to

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

bw

the bandwidth of the KDE. If NULL, bw will be calculated automatically using the algorithm by Botev et al. (2010).

adaptive

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

log

transform the ages to a log scale if TRUE

n

horizontal resolution (i.e., the number of segments) 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 log = FALSE, or as a fractional value if log = TRUE. Sturges' Rule (\log_2[n]+1, where n is the number of data points) is used if binwidth = NA

hide

vector with indices of aliquots that should be removed from the plot.

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 minimum (negative) and maximum (positive) 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.

common.Pb

apply a common lead correction using one of three methods:

1: use the isochron intercept as the initial Pb-composition

2: use the Stacey-Kramer two-stage model to infer the initial Pb-composition

3: use the Pb-composition stored in settings('iratio','Pb206Pb204') and settings('iratio','Pb207Pb204')

ncol

scalar value indicating the number of columns over which the KDEs should be divided.

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, ^{40}Ca/^{44}Ca, ^{87}Sr/^{86}Sr, ^{143}Nd/^{144}Nd, ^{187}Os/^{188}Os, ^{230}Th/^{232}Th or ^{176}Hf/^{177}Hf ratio from an isochron fit. Setting i2i to FALSE uses the default values stored in settings('iratio',...).

detritus

detrital ^{230}Th correction (only applicable when x$format == 1 or 2.

0: no correction

1: project the data along an isochron fit

2: correct the data using an assumed initial ^{230}Th/^{232}Th-ratio for the detritus.

3: correct the data using the measured present day ^{230}Th/^{238}U, ^{232}Th/^{238}U and ^{234}U/^{238}U-ratios in the detritus.

Th02

2-element vector with the assumed initial ^{230}Th/^{232}Th-ratio of the detritus and its standard error. Only used if detritus==2

Th02U48

9-element vector with the measured composition of the detritus, containing X=0/8, sX, Y=2/8, sY, Z=4/8, sZ, rXY, rXZ, rYZ. Only used if isochron==FALSE and detritus==3

Details

Given a set of n age estimates \{t_1, t_2, ..., t_n\}, histograms and KDEs are probability density estimators that display age distributions by smoothing. Histograms do this by grouping the data into a number of regularly spaced bins. Alternatively, kernel density estimates (KDEs; Vermeesch, 2012) smooth data by applying a (Gaussian) kernel:

KDE(t) = ∑_{i=1}^{n}N(t|μ=t_i,σ=h[t])/n

where N(t|μ,σ) is the probability of observing a value t under a Normal distribution with mean μ and standard deviation σ. h[t] is the smoothing parameter or ‘bandwidth’ of the kernel density estimate, which may or may not depend on the age t. If h[t] depends on t, then KDE(t) is known as an ‘adaptive’ KDE. The default bandwidth used by IsoplotR is calculated using the algorithm of Botev et al. (2010) and modulated by the adaptive smoothing approach of Abramson (1982). The rationale behind adaptive kernel density estimation is to use a narrower bandwidth near the peaks of the sampling distribution (where the ordered dates are closely spaced in time), and a wider bandwidth in the distribution's sparsely sampled troughs. Thus, the resolution of the density estimate is optimised according to data availability.

Value

If x has class UPb, PbPb, ArAr, KCa, ReOs, SmNd, RbSr, UThHe, fissiontracks or ThU, 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

log

copied from the input

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.

See Also

radialplot, cad

Examples

1
2
3
4
5
6
7
kde(examples$UPb)

dev.new()
kde(examples$FT1,log=TRUE)

dev.new()
kde(examples$DZ,from=1,to=3000,kernel="epanechnikov")

IsoplotR documentation built on Dec. 9, 2018, 1:04 a.m.