% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/calc_SourceDoseRate.R
\name{calc_SourceDoseRate}
\alias{calc_SourceDoseRate}
\title{Calculation of the source dose rate via the date of measurement}
\usage{
calc_SourceDoseRate(
  measurement.date,
  calib.date,
  calib.dose.rate,
  calib.error,
  source.type = c("Sr-90", "Am-214", "Co-60", "Cs-137"),
  dose.rate.unit = c("Gy/s", "Gy/min"),
  predict = NULL
)
}
\arguments{
\item{measurement.date}{\link{character} or \link{Date} (\emph{with default}):
Date of measurement in \code{"YYYY-MM-DD"} format. If no value is provided, the
date will be set to today. The argument can be provided as vector.}

\item{calib.date}{\link{character} or \link{Date} (\strong{required}):
date of source calibration in \code{"YYYY-MM-DD"} format.}

\item{calib.dose.rate}{\link{numeric} (\strong{required}):
dose rate at date of calibration in Gy/s or Gy/min.}

\item{calib.error}{\link{numeric} (\strong{required}):
error of dose rate at date of calibration Gy/s or Gy/min.}

\item{source.type}{\link{character} (\emph{with default}):
specify irradiation source (\code{Sr-90}, \code{Co-60}, \code{Cs-137}, \code{Am-214}),
see details for further information.}

\item{dose.rate.unit}{\link{character} (\emph{with default}):
dose rate unit for input (one of \code{Gy/min} or \code{Gy/s}). The output is given in
Gy/s as valid for the function \link{convert_Second2Gray}.}

\item{predict}{\link{integer} (\emph{with default}):
option allowing to predict the dose rate of the source over time in days
set by the provided value. Starting date is the value set with
\code{measurement.date}, e.g., \code{calc_SourceDoseRate(..., predict = 100)} calculates
the source dose rate for the next 100 days.}
}
\value{
Returns an S4 object of type \linkS4class{RLum.Results}.
Slot \code{data} contains a \link{list} with the following structure:

\if{html}{\out{<div class="sourceCode">}}\preformatted{$ dose.rate (data.frame)
.. $ dose.rate
.. $ dose.rate.error
.. $ date (corresponding measurement date)
$ parameters (list)
.. $ source.type
.. $ halflife
.. $ dose.rate.unit
$ call (the original function call)
}\if{html}{\out{</div>}}

The output should be accessed using the function \link{get_RLum}.
A plot method of the output is provided via \link{plot_RLum}.
}
\description{
Calculating the dose rate of the irradiation source via the date of
measurement based on: source calibration date, source dose rate, dose rate
error. The function returns a data.frame that provides the input argument
dose_rate for the function \link{convert_Second2Gray}.

Calculation of the source dose rate based on the time elapsed since the last
calibration of the irradiation source. Decay parameters assume a Sr-90 beta
source.
\deqn{dose.rate = D0 \exp(-\frac{\log(2)}{T.1/2} t)}

where \code{D0} is the calibration dose rate, \eqn{T.1/2} is the half-life of the
source nuclide (in days), \code{t} is the time since source calibration (in days),
and \eqn{\log(2) / T.1/2} equals the decay constant lambda.

Information on the date of measurements may be taken from the data's
original .BIN file (using e.g., \code{BINfile <- Luminescence::read_BIN2R()} and the slot
\code{BINfile@METADATA$DATE}).

\strong{Allowed source types and related values}

\tabular{rlll}{
\strong{#} \tab \strong{Source type} \tab \strong{T.1/2} \tab \strong{Reference} \cr
\verb{[1]} \tab Sr-90 \tab 28.90 y \tab NNDC, Brookhaven National Laboratory \cr
\verb{[2]} \tab Am-214 \tab 432.6 y \tab NNDC, Brookhaven National Laboratory \cr
\verb{[3]} \tab Co-60 \tab 5.274 y \tab NNDC, Brookhaven National Laboratory \cr
\verb{[4]} \tab Cs-137 \tab 30.08 y \tab NNDC, Brookhaven National Laboratory}
}
\note{
Please be careful when using the option \code{predict}, especially when a
multiple set for \code{measurement.date} and \code{calib.date} is provided. For the
source dose rate prediction, the function takes the last \code{measurement.date}
value and predicts from that the source dose rate for the number of days
requested, that is: the (multiple) original input will be replaced.
However, the function does not change entries for the calibration dates,
but mixes them up. Therefore, it is not recommended to use this option
when multiple calibration dates (\code{calib.date}) are provided.
}
\section{Function version}{
 0.3.4
}

\examples{

##(1) Simple function usage
##Basic calculation of the dose rate for a specific date
dose.rate <-  calc_SourceDoseRate(measurement.date = "2012-01-27",
                                  calib.date = "2014-12-19",
                                  calib.dose.rate = 0.0438,
                                  calib.error = 0.0019)

##show results
get_RLum(dose.rate)

##(2) Usage in combination with another function (e.g., convert_Second2Gray() )
## load example data
data(ExampleData.DeValues, envir = environment())

## use the calculated variable dose.rate as input argument
## to convert De(s) to De(Gy)
convert_Second2Gray(ExampleData.DeValues$BT998, dose.rate)

##(3) source rate prediction and plotting
dose.rate <-  calc_SourceDoseRate(measurement.date = "2012-01-27",
                                  calib.date = "2014-12-19",
                                  calib.dose.rate = 0.0438,
                                  calib.error = 0.0019,
                                  predict = 1000)
plot_RLum(dose.rate)

##(4) export output to a LaTeX table (example using the package 'xtable')
\dontrun{
xtable::xtable(get_RLum(dose.rate))
}

} 

\section{How to cite}{
Fuchs, M.C., Kreutzer, S., 2026. calc_SourceDoseRate(): Calculation of the source dose rate via the date of measurement. Function version 0.3.4. 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{
NNDC, Brookhaven National Laboratory \verb{http://www.nndc.bnl.gov/}
}
\seealso{
\link{convert_Second2Gray}, \link{get_RLum}, \link{plot_RLum}
}
\author{
Margret C. Fuchs, HZDR, Helmholtz-Institute Freiberg for Resource Technology (Germany) \cr
Sebastian Kreutzer, F2.1 Geophysical Parametrisation/Regionalisation, LIAG - Institute for Applied Geophysics (Germany)
, RLum Developer Team}
\keyword{manip}
