combine_De_Dr: Combine Dose Rate and Equivalent Dose Distribution

View source: R/combine_De_Dr.R

combine_De_DrR Documentation

Combine Dose Rate and Equivalent Dose Distribution

Description

A Bayesian statistical analysis of OSL age requiring dose rate sample. Estimation contains a preliminary step for detecting outliers in the equivalent dose sample.

Usage

combine_De_Dr(
  De,
  s,
  Dr,
  int_OD,
  Age_range = c(1, 300),
  outlier_threshold = 0.05,
  outlier_method = "default",
  outlier_analysis_plot = FALSE,
  method_control = list(),
  par_local = TRUE,
  verbose = TRUE,
  plot = TRUE,
  ...
)

Arguments

De

numeric (required): a equivalent dose sample

s

numeric (required): a vector of measurement errors on the equivalent dose

Dr

numeric (required): a dose rate sample

int_OD

numeric (required): the intrinsic overdispersion, typically the standard deviation characterizing a dose-recovery test distribution

Age_range

numeric (with default): the age range to be investigated by the algorithm, the larger the value the more iterations are needed and the longer it takes. Should not be set too narrow, cut the algorithm some slack.

outlier_threshold

numeric (with default): the required significance level used for the outlier detection. If set to 1, no outliers are removed. If outlier_method = "RousseeuwCroux1993", the median distance is used as outlier threshold. Please see details for further information.

outlier_method

character (with default): select the outlier detection method, either "default" or "RousseeuwCroux1993". See details for further information.

outlier_analysis_plot

logical (with default): enables/disables the outlier analysis plot. Note: the outlier analysis will happen with or without plot output

method_control

list (with default): named list of further parameters passed down to the rjags::rjags modelling

par_local

logical (with default): if set to TRUE the function uses its own graphics::par settings (which will end in two plots next to each other)

verbose

logical (with default): enable/disable terminal feedback

plot

logical (with default): enable/disable plot output

...

a few further arguments to fine-tune the plot output such as cdf_ADr_quantiles (TRUE/FALSE), legend.pos, legend (TRUE/FALSE)

Details

Outlier detection

Two different outlier detection methods are implemented (full details are given in the cited literature).

  1. The default and recommend method, uses quantiles to compare prior and posterior distributions of the individual variances of the equivalent doses. If the corresponding quantile in the corresponding posterior distribution is larger than the quantile in the prior distribution, the value is marked as outlier (cf. Galharret et al., preprint)

  2. The alternative method employs the method suggested by Rousseeuw and Croux (1993) using the absolute median distance.

Parameters available for method_control

The parameters listed below are used to granular control Bayesian modelling using rjags::rjags. Internally the functions .calc_IndividualAgeModel() and .calc_BayesianCentraAgelModel(). The parameter settings affect both models. Note: method_control expects a named list of parameters

PARAMETER TYPE DEFAULT REMARKS
variable.names_IAM character c('A', 'a', 'sig_a') variables names to be monitored in the modelling process using the internal function .calc_IndividualAgeModel()
variable.names_BCAM character c('A', 'D_e') variables names to be monitored in the modelling process using the internal function .calc_BayesianCentraAgelModel()
n.chains integer 4 number of MCMC chains
n.adapt integer 1000 number of iterations for the adaptation
n.iter integer 5000 number of iterations to monitor cf. rjags::coda.samples
thin numeric 1 thinning interval for the monitoring cf. rjags::coda.samples
diag logical FALSE additional terminal convergence diagnostic. FALSE if verbose = FALSE
progress.bar logical FALSE enable/disable progress bar. FALSE if verbose = FALSE
quiet logical TRUE silence terminal output. Set to TRUE if verbose = FALSE
return_mcmc logical FALSE return additional MCMC diagnostic information

Value

The function returns a plot if plot = TRUE and an RLum.Results object with the following slots:

⁠@data⁠
.. $Ages: a numeric vector with the modelled ages to be further analysed or visualised
.. $Ages_stats: a data.frame with sum HPD, CI 68% and CI 95% for the ages
.. $outliers_index: the index with the detected outliers
.. $cdf_ADr_mean : empirical cumulative density distribution A * Dr (mean)
.. $cdf_ADr_quantiles : empirical cumulative density distribution A * Dr (quantiles .025,.975)
.. $cdf_De_no_outlier : empirical cumulative density distribution of the De with no outliers
.. $cdf_De_initial : empirical cumulative density distribution of the initial De
.. $mcmc_IAM : the MCMC list of the Individual Age Model, only of method_control = list(return_mcmc = TRUE) otherwise NULL
.. $mcmc_BCAM : the MCMC list of the Bayesian Central Age Model, only of method_control = list(return_mcmc = TRUE) otherwise NULL

⁠@info⁠
.. $call: the original function call
.. $model_IAM: the BUGS model used to derive the individual age
.. $model_BCAM: the BUGS model used to calculate the Bayesian Central Age

Function version

0.1.0

How to cite

Philippe, A., Galharret, J., Mercier, N., Kreutzer, S., 2024. combine_De_Dr(): Combine Dose Rate and Equivalent Dose Distribution. Function version 0.1.0. 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., 2024. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.24. https://CRAN.R-project.org/package=Luminescence

Author(s)

Anne Philippe, Université de Nantes (France), Jean-Michel Galharret, Université de Nantes (France), Norbert Mercier, IRAMAT-CRP2A, Université Bordeaux Montaigne (France), Sebastian Kreutzer, Institute of Geography, Heidelberg University (Germany) , RLum Developer Team

References

Mercier, N., Galharret, J.-M., Tribolo, C., Kreutzer, S., Philippe, A., preprint. Luminescence age calculation through Bayesian convolution of equivalent dose and dose-rate distributions: the De_Dr model. Geochronology, 1-22.

Galharret, J-M., Philippe, A., Mercier, N., preprint. Detection of outliers with a Bayesian hierarchical model: application to the single-grain luminescence dating method. Electronic Journal of Applied Statistics

Further reading

Rousseeuw, P.J., Croux, C., 1993. Alternatives to the median absolute deviation. Journal of the American Statistical Association 88, 1273–1283. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.2307/2291267")}

Rousseeuw, P.J., Debruyne, M., Engelen, S., Hubert, M., 2006. Robustness and outlier detection in chemometrics. Critical Reviews in Analytical Chemistry 36, 221–242. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1080/10408340600969403")}

See Also

plot_OSLAgeSummary, rjags::rjags, mclust-package

Examples

## set parameters
Dr <- stats::rlnorm (1000, 0, 0.3)
De <- 50*sample(Dr, 50, replace = TRUE)
s <- stats::rnorm(50, 10, 2)

## run modelling
## note: modify parameters for more realistic results
## Not run: 
results <- combine_De_Dr(
 Dr = Dr,
 int_OD = 0.1,
 De,
 s,
 Age_range = c(0,100),
 method_control = list(
  n.iter = 100,
  n.chains = 1))

## show models used
writeLines(results@info$model_IAM)
writeLines(results@info$model_BCAM)

## End(Not run)


Luminescence documentation built on June 22, 2024, 9:54 a.m.