Luminescence (version 0.3.1)

plot_KDE: Plot kernel density estimate with statistics

Description

Function plots a kernel density estimate of measurement values in combination with the actual values and associated error bars in ascending order. Optionally, statistical measures such as mean, median, standard deviation, standard error and quartile range can be provided visually and numerically.

Usage

plot_KDE(values, na.exclude = TRUE, distribution.parameters, 
    summary, summary.pos, bw = "nrd0", output = FALSE, ...)

Arguments

values

data.frame or RLum.Results object (required): for data.frame: two columns: De (values[,1]) and De error (values[,2]). For

na.exclude

logical (with default): excludes NA values from the data set prior to any further operations.

distribution.parameters

character (optional): plots additional distribution parameters. Can be one or more out of "mean", "median", "kdemax" (maximum value of probability density function), "sd" (standard deviation) and "q

summary

character (optional): adds numerical output to the plot. Can be one or more out of: "n" (number of samples), "mean" (mean De value), "median" (median of the De values), "kdemax" (maximum value of pr

summary.pos

numeric or character (with default): optional position coordinates or keyword for the statistical summary. Y-coordinate refers to the right hand y-ax

bw

character (with default): bin-width, choose a numeric value for manual setting.

output

logical: Optional output of numerical plot parameters. These can be useful to reproduce similar plots. Default is FALSE.

...

further arguments and graphical parameters passed to plot.

Details

The function allows passing several plot arguments, such as main, xlab, cex. However, as the figure is an overlay of two separate plots, ylim must be specified in the order: c(ymin_axis1, ymax_axis1, ymin_axis2, ymax_axis2). Similarly, if other than the default colours are desired, the argument col must be provided with colours in the following order: probability density function, De values, De error bars, sd or qr polygon. See examples for some further explanations. For details on the calculation of the bin-width (parameter bw), see density.

See Also

density, plot

Examples

# read example data set
data(ExampleData.DeValues, envir = environment())

# native function call
plot_KDE(ExampleData.DeValues)

# function call with some user-defined modifications
plot_KDE(ExampleData.DeValues,
         main = "Plot of Dose distribution data",
         col = c("red", "black", "grey", "cyan"),
         xlab = "Equivalent dose [Gy]",
         ylabs = c("KDE estimate", "cumulative De values"),
         distribution.parameters = c("qr", "median"), 
         xlim = c(2000, 5000),
         ylims = c(0, 0.005, -5, 50),
         summary = c("n", "median", "serel", "seabs"),
         cex = 0.8)

# function call with complete numerical statistical description output
plot_KDE(ExampleData.DeValues,
         distribution.parameters = c("qr", "kdemax"), 
         summary = c("n", "mean", "median", "kdemax", "serel", 
                     "sdrel", "sdabs", "seabs"))

# function call with two data sets
dataset1 <- ExampleData.DeValues[1:8,]
dataset2 <- ExampleData.DeValues[9:25,]

plot_KDE(list(dataset1, dataset2), col = c("blue", "orange"))