% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/calc_AverageDose.R
\name{calc_AverageDose}
\alias{calc_AverageDose}
\title{Calculate the Average Dose and the dose rate dispersion}
\usage{
calc_AverageDose(
  data,
  sigma_m,
  Nb_BE = 500,
  na.rm = TRUE,
  plot = TRUE,
  verbose = TRUE,
  ...
)
}
\arguments{
\item{data}{\linkS4class{RLum.Results} or \link{data.frame} (\strong{required}):
for \link{data.frame}: two columns with \code{De} \code{(data[,1])} and \verb{De error} \code{(values[,2])}}

\item{sigma_m}{\link{numeric} (\strong{required}):
the overdispersion resulting from a dose recovery
experiment, i.e. when all grains have  received the same dose. Indeed in such a case, any
overdispersion (i.e. dispersion on top of analytical uncertainties) is, by definition, an
unrecognised measurement uncertainty.}

\item{Nb_BE}{\link{integer} (\emph{with default}):
sample size used for the bootstrapping}

\item{na.rm}{\link{logical} (\emph{with default}):
exclude \code{NA} values from the data set prior to any further operation.}

\item{plot}{\link{logical} (\emph{with default}):
enable/disable the plot output.}

\item{verbose}{\link{logical} (\emph{with default}):
enable/disable output to the terminal.}

\item{...}{further arguments that can be passed to \link[graphics:hist]{graphics::hist}. As three plots
are returned all arguments need to be provided as \link{list},
e.g., \code{main = list("Plot 1", "Plot 2", "Plot 3")}.
Note: not all arguments of \code{hist} are
supported, but the output of \code{hist} is returned and can be used of own plots. \cr

Further supported arguments: \code{mtext} (\link{character}), \code{rug} (\code{TRUE/FALSE}).}
}
\value{
The function produces numerical output and an optional plot. In addition,
an \linkS4class{RLum.Results} object containing the following
elements is returned:

\item{$summary}{\link{data.frame} summary of all relevant model results.}
\item{$data}{\link{data.frame} with original input data.}
\item{$dstar}{\link{matrix} with bootstrap values.}
\item{$hist}{\link{list} object as produced by the \link{hist} function.}

The \verb{$summary} data.frame contains the following columns:
\tabular{lll}{
\strong{Column} \tab \strong{Type} \tab \strong{Description}\cr
AVERAGE_DOSE \tab \link{numeric} \tab the obtained average dose\cr
AVERAGE_DOSE.SE \tab \link{numeric} \tab the average dose error \cr
SIGMA_D \tab \link{numeric}\tab sigma \cr
SIGMA_D.SE \tab \link{numeric}\tab standard error of the sigma  \cr
IC_AVERAGE_DOSE.LEVEL  \tab \link{character}\tab confidence level average dose\cr
IC_AVERAGE_DOSE.LOWER  \tab \link{character}\tab lower quantile of average dose \cr
IC_AVERAGE_DOSE.UPPER \tab \link{character}\tab upper quantile of average dose\cr
IC_SIGMA_D.LEVEL \tab \link{integer}\tab confidence level sigma\cr
IC_SIGMA_D.LOWER \tab \link{character}\tab lower sigma quantile\cr
IC_SIGMA_D.UPPER \tab \link{character}\tab upper sigma quantile\cr
L_MAX \tab \link{character}\tab maximum likelihood value \cr
de \tab \link{numeric} \tab same as \code{AVERAGE_DOSE} (internal use)\cr
de_err \tab \link{numeric} \tab same as \code{AVERAGE_DOSE.SE} (internal use)\cr
}

The function returns two different plot panels.

(1) An abanico plot with the dose values

(2) A histogram panel comprising 3 histograms with the equivalent dose and the bootstrapped average
dose and the sigma values.
}
\description{
This functions calculates the Average Dose and its extrinsic dispersion,
estimating the standard errors by bootstrapping based on the Average
Dose Model by Guérin et al., 2017.

\strong{\code{sigma_m}}\cr

The program requires the input of a known value of \code{sigma_m},
which corresponds to the intrinsic overdispersion, as determined
by a dose recovery experiment. Then the dispersion in doses (\code{sigma_d})
will be that over and above \code{sigma_m} (and individual uncertainties \code{sigma_wi}).
}
\note{
This function has beta status!
}
\section{Function version}{
 0.1.7
}

\examples{

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

## calculate Average dose (using only the first 56 values here)
AD <- calc_AverageDose(ExampleData.DeValues$CA1[1:56, ], sigma_m = 0.1)

## plot De and set Average dose as central value
plot_AbanicoPlot(AD, z.0 = AD$summary$de)

} 

\section{How to cite}{
Christophe, C., Philippe, A., Guérin, G., Kreutzer, S., 2026. calc_AverageDose(): Calculate the Average Dose and the dose rate dispersion. Function version 0.1.7. 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., Steinbuch, L., Boer, A.d., Bluszcz, A., 2026. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 1.2.1. https://r-lum.github.io/Luminescence/
}

\references{
Guérin, G., Christophe, C., Philippe, A., Murray, A.S., Thomsen, K.J., Tribolo, C., Urbanova, P.,
Jain, M., Guibert, P., Mercier, N., Kreutzer, S., Lahaye, C., 2017. Absorbed dose, equivalent dose,
measured dose rates, and implications for OSL age estimates: Introducing the Average Dose Model.
Quaternary Geochronology 1-32. doi:10.1016/j.quageo.2017.04.002

\strong{Further reading}\cr

Efron, B., Tibshirani, R., 1986. Bootstrap Methods for Standard Errors, Confidence Intervals,
and Other Measures of Statistical Accuracy. Statistical Science 1, 54-75.
}
\seealso{
\link{read.table}, \link[graphics:hist]{graphics::hist}
}
\author{
Claire Christophe, IRAMAT-CRP2A, Université de Nantes (France)\cr
Anne Philippe, Université de Nantes, (France)\cr
Guillaume Guérin, IRAMAT-CRP2A, Université Bordeaux Montaigne, (France)\cr
Sebastian Kreutzer, F2.1 Geophysical Parametrisation/Regionalisation, LIAG - Institute for Applied Geophysics (Germany)
, RLum Developer Team}
\keyword{datagen}
