Luminescence (version 0.9.25)

plot_DRTResults: Visualise dose recovery test results

Description

The function provides a standardised plot output for dose recovery test measurements.

Usage

plot_DRTResults(
  values,
  given.dose = NULL,
  error.range = 10,
  preheat,
  boxplot = FALSE,
  mtext,
  summary,
  summary.pos,
  legend,
  legend.pos,
  par.local = TRUE,
  na.rm = FALSE,
  ...
)

Value

A plot is returned.

Arguments

values

RLum.Results or data.frame (required): input values containing at least De and De error. To plot more than one data set in one figure, a list of the individual data sets must be provided (e.g. list(dataset.1, dataset.2)).

given.dose

numeric (optional): given dose used for the dose recovery test to normalise data. If only one given dose is provided this given dose is valid for all input data sets (i.e., values is a list). Otherwise a given dose for each input data set has to be provided (e.g., given.dose = c(100,200)). If given.dose in NULL the values are plotted without normalisation (might be useful for preheat plateau tests). Note: Unit has to be the same as from the input values (e.g., Seconds or Gray).

error.range

numeric: symmetric error range in percent will be shown as dashed lines in the plot. Set error.range to 0 to void plotting of error ranges.

preheat

numeric: optional vector of preheat temperatures to be used for grouping the De values. If specified, the temperatures are assigned to the x-axis.

boxplot

logical: optionally plot values, that are grouped by preheat temperature as boxplots. Only possible when preheat vector is specified.

mtext

character: additional text below the plot title.

summary

character (optional): adds numerical output to the plot. Can be one or more out of:

• "n" (number of samples),

• "mean" (mean De value),

• "weighted$mean" (error-weighted mean),

• "median" (median of the De values),

• "sd.rel" (relative standard deviation in percent),

• "sd.abs" (absolute standard deviation),

• "se.rel" (relative standard error) and

• "se.abs" (absolute standard error)

and all other measures returned by the function calc_Statistics.

summary.pos

numeric or character (with default): optional position coordinates or keyword (e.g. "topright") for the statistical summary. Alternatively, the keyword "sub" may be specified to place the summary below the plot header. However, this latter option in only possible if mtext is not used.

legend

character vector (optional): legend content to be added to the plot.

legend.pos

numeric or character (with default): optional position coordinates or keyword (e.g. "topright") for the legend to be plotted.

par.local

logical (with default): use local graphical parameters for plotting, e.g. the plot is shown in one column and one row. If par.local = FALSE, global parameters are inherited, i.e. parameters provided via par() work

na.rm

logical: indicating whether NA values are removed before plotting from the input data set

...

further arguments and graphical parameters passed to plot, supported are: xlab, ylab, xlim, ylim, main, cex, las and `pch``

Function version

0.1.14

How to cite

Kreutzer, S., Dietze, M., 2024. plot_DRTResults(): Visualise dose recovery test results. Function version 0.1.14. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J., Mercier, N., Philippe, A., Riedesel, S., Autzen, M., Mittelstrass, D., Gray, H.J., Galharret, J., Colombo, M., 2024. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.25. https://r-lum.github.io/Luminescence/

Author

Sebastian Kreutzer, Institute of Geography, Heidelberg University (Germany)
Michael Dietze, GFZ Potsdam (Germany) , RLum Developer Team

Details

Procedure to test the accuracy of a measurement protocol to reliably determine the dose of a specific sample. Here, the natural signal is erased and a known laboratory dose administered which is treated as unknown. Then the De measurement is carried out and the degree of congruence between administered and recovered dose is a measure of the protocol's accuracy for this sample.
In the plot the normalised De is shown on the y-axis, i.e. obtained De/Given Dose.

References

Wintle, A.G., Murray, A.S., 2006. A review of quartz optically stimulated luminescence characteristics and their relevance in single-aliquot regeneration dating protocols. Radiation Measurements, 41, 369-391.

See Also

plot

Examples

## read example data set and misapply them for this plot type
data(ExampleData.DeValues, envir = environment())

## plot values
plot_DRTResults(
  values = ExampleData.DeValues$BT998[7:11,],
  given.dose = 2800,
  mtext = "Example data")

## plot values with legend
plot_DRTResults(
  values = ExampleData.DeValues$BT998[7:11,],
  given.dose = 2800,
  legend = "Test data set")

## create and plot two subsets with randomised values
x.1 <- ExampleData.DeValues$BT998[7:11,]
x.2 <- ExampleData.DeValues$BT998[7:11,] * c(runif(5, 0.9, 1.1), 1)

plot_DRTResults(
  values = list(x.1, x.2),
  given.dose = 2800)

## some more user-defined plot parameters
plot_DRTResults(
  values = list(x.1, x.2),
  given.dose = 2800,
  pch = c(2, 5),
  col = c("orange", "blue"),
  xlim = c(0, 8),
  ylim = c(0.85, 1.15),
  xlab = "Sample aliquot")

## plot the data with user-defined statistical measures as legend
plot_DRTResults(
  values = list(x.1, x.2),
  given.dose = 2800,
  summary = c("n", "weighted$mean", "sd.abs"))

## plot the data with user-defined statistical measures as sub-header
plot_DRTResults(
  values = list(x.1, x.2),
  given.dose = 2800,
  summary = c("n", "weighted$mean", "sd.abs"),
  summary.pos = "sub")

## plot the data grouped by preheat temperatures
plot_DRTResults(
  values = ExampleData.DeValues$BT998[7:11,],
  given.dose = 2800,
  preheat = c(200, 200, 200, 240, 240))

## read example data set and misapply them for this plot type
data(ExampleData.DeValues, envir = environment())

## plot values
plot_DRTResults(
  values = ExampleData.DeValues$BT998[7:11,],
  given.dose = 2800,
  mtext = "Example data")

## plot two data sets grouped by preheat temperatures
plot_DRTResults(
  values = list(x.1, x.2),
  given.dose = 2800,
  preheat = c(200, 200, 200, 240, 240))

## plot the data grouped by preheat temperatures as boxplots
plot_DRTResults(
  values = ExampleData.DeValues$BT998[7:11,],
  given.dose = 2800,
  preheat = c(200, 200, 200, 240, 240),
  boxplot = TRUE)