% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/calc_OSLLxTxRatio.R
\name{calc_OSLLxTxRatio}
\alias{calc_OSLLxTxRatio}
\title{Calculate \code{Lx/Tx} ratio for CW-OSL curves}
\usage{
calc_OSLLxTxRatio(
  Lx.data,
  Tx.data = NULL,
  signal_integral = NULL,
  background_integral = NULL,
  signal_integral_Tx = NULL,
  background_integral_Tx = NULL,
  integral_input = c("channel", "measurement"),
  background.count.distribution = "non-poisson",
  use_previousBG = FALSE,
  sigmab = NULL,
  sig0 = 0,
  digits = NULL,
  ...
)
}
\arguments{
\item{Lx.data}{\linkS4class{RLum.Data.Curve}, \link{data.frame}, \link{list} (\strong{required}):
requires a CW-OSL shine down curve (x = time, y = counts). Data can also be
provided as a list.}

\item{Tx.data}{\linkS4class{RLum.Data.Curve} or \link{data.frame} (\emph{optional}):
requires a CW-OSL shine down curve (x = time, y = counts). If no
input is given the \code{Tx.data} will be treated as \code{NA} and no \code{Lx/Tx} ratio
is calculated. When \code{Lx.data} is a list, it must be provided as a list of
the same length.}

\item{signal_integral}{\link{integer} (\strong{required}):
vector of channels for the signal integral. If set to \code{NA} (alternate mode),
no integrals are taken into account and their settings are ignored.}

\item{background_integral}{\link{integer} (\strong{required}):
vector of channels for the background integral. If set to \code{NA}, no
background integral is subtracted; in this case, \code{sigmab.LnLx} (unless
manually set) and the signal-to-noise ratio for Ln/Lx\verb{will be}NA`.}

\item{signal_integral_Tx}{\link{integer} (\emph{optional}):
vector of channels for the signal integral for the \code{Tx} curve.
If \code{NULL}, the \code{signal_integral} vector is used.}

\item{background_integral_Tx}{\link{integer} (\emph{optional}):
vector of channels for the background integral for the \code{Tx} curve.
If \code{NULL}, the \code{background_integral} vector is used. If set to \code{NA}, no
background integral for the \code{Tx} curve is subtracted; in this case,
\code{sigmab.TxTx} (unless manually set) and the signal-to-noise ratio for
\code{Tn/Tx} will be \code{NA}.}

\item{integral_input}{\link{character} (\emph{with default}):
input type for \code{signal_integral}, one of \code{"channel"} (default) or
\code{"measurement"}. If set to \code{"measurement"}, the best matching channels
corresponding to the given time/temperature range are selected.}

\item{background.count.distribution}{\link{character} (\emph{with default}):
sets the count distribution assumed for the error calculation.
Possible arguments are \code{"poisson"} or \code{"non-poisson"} (default). See
details for further information.}

\item{use_previousBG}{\link{logical} (\emph{with default}):
If set to \code{TRUE} the background of the \code{Lx}-signal is subtracted also
from the \code{Tx}-signal. Please note that in this case separate
signal integral limits for the \code{Tx}-signal are not allowed and will be reset.}

\item{sigmab}{\link{numeric} (\emph{optional}):
option to set a manual value for the overdispersion (for \code{LnTx} and \code{TnTx}),
used for the \code{Lx/Tx} error calculation. The value should be provided as
absolute squared count values, e.g. \code{sigmab = c(300,300)}.
\strong{Note:} If only one value is provided this value is taken for both (\code{LnTx} and \code{TnTx}) signals.}

\item{sig0}{\link{numeric} (\emph{with default}):
allow adding an extra component of error to the final \code{Lx/Tx} error value
(e.g., instrumental error, see details).}

\item{digits}{\link{integer} (\emph{with default}):
round numbers to the specified digits. If set to \code{NULL} no rounding occurs.}

\item{...}{currently not used.}
}
\value{
Returns an S4 object of type \linkS4class{RLum.Results}.

Slot \code{data} contains a \link{list} with the following structure:

\strong{@data}

\if{html}{\out{<div class="sourceCode">}}\preformatted{$LxTx.table (data.frame)
.. $ LnLx
.. $ LnLx.BG
.. $ TnTx
.. $ TnTx.BG
.. $ Net_LnLx
.. $ Net_LnLx.Error
.. $ Net_TnTx
.. $ Net_TnTx.Error
.. $ SN_RATIO_LnLx,
.. $ SN_RATIO_TnTx,
.. $ LxTx
.. $ LxTx.Error
$calc.parameters (list)
.. $ sigmab.LnTx
.. $ sigmab.TnTx
.. $ k
}\if{html}{\out{</div>}}

\strong{@info}

\if{html}{\out{<div class="sourceCode">}}\preformatted{$ call (original function call)
}\if{html}{\out{</div>}}
}
\description{
Calculate \code{Lx/Tx} ratios from a given set of CW-OSL curves assuming late light
background subtraction.
}
\details{
The function checks the integrity of the values chosen for the signal and
background integrals; the signal integral limits have to be lower than
the background integral limits. If a \link{vector} is given as input instead
of a \link{data.frame}, an artificial \link{data.frame} is produced. The
error calculation is done according to Galbraith (2002).

\strong{Please note:} In cases where the calculation results in \code{NaN} values (for
example due to zero-signal, and therefore a division of 0 by 0), these \code{NaN}
values are replaced by 0.

\strong{\code{sigmab}}

The default value of \code{sigmab} is calculated assuming the background is
constant and \strong{would not} applicable when the background varies as,
e.g., as observed for the early light subtraction method.

\strong{\code{sig0}}

This argument allows to add an extra component of error to the final \code{Lx/Tx}
error value. The input will be treated as factor that is multiplied with
the already calculated \code{LxTx} and the result is add up by:

\deqn{se(LxTx) = \sqrt{se(LxTx)^2 + (LxTx * sig0)^2}}

\strong{\code{SN_RATIO_LnLx} and \code{SN_RATIO_TnTx}}

For convenience, the function returns the signal-to-noise ratio (\code{SN_RATIO})
for the \code{LnLx} and the \code{TnTx} curves. This is simply the signal divided
by the background signal counts normalised to the \code{k} value (see below).

\strong{\code{background.count.distribution}}

This argument allows selecting the distribution assumption that is used for
the error calculation. According to Galbraith (2002, 2014) the background
counts may be overdispersed (i.e. do not follow a Poisson distribution,
which is assumed for the photomultiplier counts). In that case (might be the
normal case) it has to be accounted for the overdispersion by estimating
\eqn{\sigma^2} (i.e. the overdispersion value). Therefore the relative
standard error is calculated as:
\itemize{
\item \code{poisson}
\deqn{rse(\mu_{S}) \approx \sqrt{Y_{0} + Y_{1}/k^2) / (Y_{0} - Y_{1}/k)} }
\item \code{non-poisson}
\deqn{rse(\mu_{S}) \approx \sqrt{Y_{0} + Y_{1}/k^2 + \sigma^2(1+1/k)) / (Y_{0} - Y_{1}/k)} }
}

If \code{background_integral = NA}, then in both cases the relative standard
error simplifies to:

\deqn{rse(\mu_{S}) \approx \sqrt{Y_{0}} / Y_{0}}

\strong{Please note} that when using the early background subtraction method in
combination with the 'non-poisson' distribution argument, the corresponding \code{Lx/Tx} error
may considerably increase due to a high \code{sigmab} value.
Please check whether this is valid for your data set and if necessary
consider to provide an own \code{sigmab} value using the corresponding argument \code{sigmab}.
}
\note{
The results of this function have been cross-checked with the Analyst
(version 3.24b). Access to the results object via \link{get_RLum}.

\strong{Caution:} If you are using early light subtraction (EBG), please either provide your
own \code{sigmab} value or use \code{background.count.distribution = "poisson"}.
}
\section{Function version}{
 0.9.8
}

\examples{

##load data
data(ExampleData.LxTxOSLData, envir = environment())

##calculate Lx/Tx ratio
results <- calc_OSLLxTxRatio(
 Lx.data = Lx.data,
 Tx.data = Tx.data,
 signal_integral = 1:2,
 background_integral = 85:100)

##get results object
get_RLum(results)

} 

\section{How to cite}{
Kreutzer, S., Colombo, M., 2026. calc_OSLLxTxRatio(): Calculate Lx/Tx ratio for CW-OSL curves. Function version 0.9.8. 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{
Duller, G., 2018. Analyst v4.57 - User Manual.
\verb{https://users.aber.ac.uk/ggd}\cr

Galbraith, R.F., 2002. A note on the variance of a background-corrected OSL
count. Ancient TL, 20 (2), 49-51. \doi{10.26034/la.atl.2002.348}

Galbraith, R.F., 2014. A further note on the variance of a
background-corrected OSL count. Ancient TL, 31 (2), 1-3. \doi{10.26034/la.atl.2014.477}
}
\seealso{
\linkS4class{RLum.Data.Curve}, \link{fit_DoseResponseCurve},
\link{analyse_SAR.CWOSL}
}
\author{
Sebastian Kreutzer, F2.1 Geophysical Parametrisation/Regionalisation, LIAG - Institute for Applied Geophysics (Germany) \cr
Marco Colombo, Institute of Geography, Heidelberg University (Germany)
, RLum Developer Team}
\keyword{datagen}
