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
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
kde(x, ...)

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

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

## S3 method for class 'ReOs'
kde(
  x,
  from = NA,
  to = NA,
  bw = NA,
  adaptive = TRUE,
  log = FALSE,
  n = 512,
  plot = TRUE,
  rug = TRUE,
  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,
  rug = TRUE,
  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,
  rug = TRUE,
  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,
  rug = TRUE,
  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,
  rug = TRUE,
  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,
  rug = TRUE,
  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, ThPb, 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

rug

add a rug plot?

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), the concordia age (type=5), or the ^{208}Pb/^{232}Th age (type=6).

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

discordance cutoff filter. This is an object of class discfilter.

common.Pb

common lead correction:

0: none

1: use the Pb-composition stored in

settings('iratio','Pb207Pb206') (if x has class UPb and x$format<4);

settings('iratio','Pb206Pb204') and settings('iratio','Pb207Pb204') (if x has class PbPb or x has class UPb and 3<x$format<7); or

settings('iratio','Pb208Pb206') and settings('iratio','Pb208Pb207') (if x has class UPb and x$format=7,8).

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

3: use the Stacey-Kramers two-stage model to infer the initial Pb-composition (only valid if x has class UPb).

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, ^{207}Pb/^{204}Pb, ^{87}Sr/^{86}Sr, ^{143}Nd/^{144}Nd, ^{187}Os/^{188}Os, ^{230}Th/^{232}Th, ^{176}Hf/^{177}Hf or ^{204}Pb/^{208}Pb 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.

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

Example output

dev.new(): using pdf(file="Rplots1.pdf")

IsoplotR documentation built on July 10, 2021, 1:06 a.m.