-
Notifications
You must be signed in to change notification settings - Fork 8
/
calc_OSLLxTxRatio.Rd
197 lines (163 loc) · 7.46 KB
/
calc_OSLLxTxRatio.Rd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
% 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,
signal.integral.Tx = NULL,
background.integral,
background.integral.Tx = NULL,
background.count.distribution = "non-poisson",
use_previousBG = FALSE,
sigmab = NULL,
sig0 = 0,
digits = NULL
)
}
\arguments{
\item{Lx.data}{\linkS4class{RLum.Data.Curve} or \link{data.frame} (\strong{required}):
requires a CW-OSL shine down curve (x = time, y = counts)}
\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.}
\item{signal.integral}{\link{numeric} (\strong{required}): vector with the limits for the signal integral.
Can be set to \code{NA} than now integrals are considered and all other integrals are set to \code{NA} as well.}
\item{signal.integral.Tx}{\link{numeric} (\emph{optional}):
vector with the limits for the signal integral for the \code{Tx}-curve. If nothing is provided the
value from \code{signal.integral} is used.}
\item{background.integral}{\link{numeric} (\strong{required}):
vector with the bounds for the background integral.
Can be set to \code{NA} than now integrals are considered and all other integrals are set to \code{NA} as well.}
\item{background.integral.Tx}{\link{numeric} (\emph{optional}):
vector with the limits for the background integral for the \code{Tx} curve.
If nothing is provided the value from \code{background.integral} is used.}
\item{background.count.distribution}{\link{character} (\emph{with default}):
sets the count distribution assumed for the error calculation.
Possible arguments \code{poisson} or \code{non-poisson}. 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 digits is set to \code{NULL} nothing is rounded.}
}
\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
.. $ 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 integrity of the chosen values for the signal and background integral is
checked by the function; 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{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{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}
}
\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.8.0
}
\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 = c(1:2),
background.integral = c(85:100))
##get results object
get_RLum(results)
}
\section{How to cite}{
Kreutzer, S., 2024. calc_OSLLxTxRatio(): Calculate Lx/Tx ratio for CW-OSL curves. Function version 0.8.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., Colombo, M., 2024. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.25. 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.
Galbraith, R.F., 2014. A further note on the variance of a
background-corrected OSL count. Ancient TL, 31 (2), 1-3.
}
\seealso{
\linkS4class{RLum.Data.Curve}, \link{Analyse_SAR.OSLdata}, \link{fit_DoseResponseCurve},
\link{analyse_SAR.CWOSL}
}
\author{
Sebastian Kreutzer, Institute of Geography, Heidelberg University (Germany)
, RLum Developer Team}
\keyword{datagen}