The function performs a SAR CW-OSL analysis on an RLum.Analysis object, including growth curve fitting.
analyse_SAR.CWOSL(
object,
signal_integral = NULL,
background_integral = NULL,
signal_integral_Tx = NULL,
background_integral_Tx = NULL,
integral_input = c("channel", "measurement"),
OSL.component = NULL,
rejection.criteria = list(),
dose.points = NULL,
dose.points.test = NULL,
dose_rate_source = NULL,
trim_channels = FALSE,
mtext.outer = "",
plot = TRUE,
plot_onePage = FALSE,
plot_singlePanels = FALSE,
onlyLxTxTable = FALSE,
method_control = list(),
...
)A plot (optional) and an RLum.Results object is returned containing the following elements:
data.frame containing De-values, De-error and further parameters
data.frame of all calculated Lx/Tx values including signal, background counts and the dose points
data.frame with values that might by used as rejection criteria.
NA is produced if no R0 dose point exists.
formula formula that have been used for the growth curve fitting
List used internally for plotting.
The output should be accessed using the function get_RLum.
The function currently supports only 'OSL', 'IRSL' and 'POSL' data!
RLum.Analysis (required):
input object containing data for analysis, alternatively a list of
RLum.Analysis objects can be provided. The object
should only contain curves considered part of the SAR protocol (see
Details). When OSL.component is set, the input object must have been
processed by OSLdecomposition::RLum.OSL_decomposition().
integer (required):
vector of channels for the signal integral. It can be a list of integers,
if object is a list. If set to NULL (default) or NA, no integrals are
taken into account and their settings are ignored.
integer (required):
vector of channels for the background integral. It can be a list of
integers, if object is a list. If set to NULL (default), no integrals
are taken into account and their settings are ignored. If set to NA, no
background integral is subtracted.
integer (optional):
vector of channels for the signal integral for the Tx curve. It can be a
list of integers, if object is a list. If NULL, the signal_integral
vector is used also for the Tx curve.
integer (optional):
vector of channels for the background integral for the Tx curve. It can
be a list of integers, if object is a list. If NULL, the
background_integral vector is used. If set to NA, no background integral
for the Tx curve is subtracted.
character (with default):
input type for signal_integral, one of "channel" (default) or
"measurement". If set to "measurement", the best matching channels
corresponding to the given time range (in seconds) are selected.
character or integer (optional):
single index or a character defining the signal component to be evaluated.
It requires that the object was processed by OSLdecomposition::RLum.OSL_decomposition.
This argument can either be the name of the OSL component assigned by
OSLdecomposition::RLum.OSL_global_fitting or the index in descending
order of decay rates. Then "1" selects the fastest decaying component, "2"
the second fastest and so on. Can be a list of integers or strings (or mixed)
If object is a list and this parameter is provided as list it alternates over
the elements (aliquots) of the object list, e.g., list(1,2) processes the first
aliquot with component 1 and the second aliquot with component 2.
NULL does not process any component.
list (with default):
provide a named list and set rejection criteria in percentage. It can
be a nested list, if object is of type list.
Note: unnamed list elements are ignored.
Allowed options:
recycling.ratio numeric (default: 10)
recuperation.rate numeric (default: 10)
palaeodose.error numeric (default: 10)
testdose.error numeric (default: 10)
sn.ratio numeric (default: NA)
exceed.max.regpoint logical (default: FALSE)
consider.uncertainties logical (default: FALSE)
recuperation_reference character (default: "Natural"; set to, e.g.,
"R1" for another point)
sn_reference character (default: "Natural").
Example: rejection.criteria = list(recycling.ratio = 10).
All numerical criteria can be set to NA, in which case values are
calculated, but they are not considered, and their corresponding RC.Status
is always "OK". In the "Checks" plot, they are shown with a grey circle
and only their value is reported (without showing <= NA or >= NA).
If onlyLxTxTable = TRUE, the palaeodose.error and exceed.max.regpoint
criteria are not computed.
numeric (optional):
a numeric vector containing the dose point values. Using this argument
overwrites dose point values extracted from other data. Can be a list of
numeric vectors, if object is of type list.
numeric (optional):
a numeric vector containing the test dose in the same units as dose.points.
If length = 1, the values will be recycled. It has only an effect for
fit.method = 'OTORX'.
numeric (optional):
numerical value for the source dose rate, typically in Gy/s. If set, the
x-axis default for the dose-response curve changes to Dose [Gy].
logical (with default):
trim channels per record category to the lowest number of channels in the
category by using trim_RLum.Data. Applies only to OSL and IRSL curves.
For a more granular control use trim_RLum.Data before calling this
function.
character (optional):
option to provide an outer margin mtext. Can be a list of characters,
if object is of type list
logical (with default): enable/disable the plot output.
logical (with default): enable/disable plotting all subplots on one page.
logical (with default) or numeric (optional):
control the plotting of subplots in single windows (one subplot per page).
Using a numeric vector allows to select the subplots individually;
setting it to TRUE corresponds to plot_singlePanels = 1:8. For example,
plot_singlePanels = c(1,2,3,4) will plot the TL and Lx, Tx curves;
plot_singlePanels = c(5,6,7,8) will plot the legend (5), the dose-response
curve (6), the rejection criteria (7), and either the IRSL curve or the
single grain (8). It is ignored if plot = FALSE or plot_onePage = TRUE.
logical (with default):
If TRUE the dose response curve fitting and plotting is skipped, and the
palaeodose.error and exceed.max.regpoint criteria are not computed.
This allows to get hands on the Lx/Tx table for large datasets
without the need for a curve fitting.
list (optional):
options to control the function behaviour. Currently only the
'auto_curve_removal' (logical) option is supported, which controls whether
curves with recordType starting with _ should be automatically removed
(TRUE by default).
further arguments that will be passed to
fit_DoseResponseCurve, plot_DoseResponseCurve
or calc_OSLLxTxRatio (the latter only supports
background.count.distribution, sigmab, sig0, od_rates).
Additionally, supported are legend.cex and legend.pch to modify the
legend symbols.
Note: If you consider using the early light subtraction method,
sigmab should be provided.
Note: od_rates can be used to treat uncertainties in Lx/Tx according
to Bluszcz et al. (2015) instead of the standard approach of Galbraith
(2002, 2014). See calc_OSLLxTxRatio for details.
1.0.0
Kreutzer, S., Colombo, M., 2026. analyse_SAR.CWOSL(): Analyse SAR CW-OSL Measurements. Function version 1.0.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., Steinbuch, L., Boer, A.d., Bluszcz, A., 2026. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 1.3.0. https://r-lum.github.io/Luminescence/
Sebastian Kreutzer, F2.1 Geophysical Parametrisation/Regionalisation, LIAG - Institute for Applied Geophysics (Germany)
Marco Colombo, Institute of Geography, Heidelberg University (Germany)
, RLum Developer Team
The function performs an analysis for standard SAR protocol measurements
introduced by Murray and Wintle (2000) with CW-OSL curves. For the
calculation of the Lx/Tx value the function calc_OSLLxTxRatio is
used. To change the way the Lx/Tx error is calculated use arguments
background.count.distribution and sigmab, which will be passed to
calc_OSLLxTxRatio.
What is part of a SAR sequence?
The function is rather picky when it comes to accepted curve input (OSL, IRSL,...) and structure. A SAR sequence is basically a set of \(L_{x}/T_{x}\) curves. Hence, every second curve is considered a shine-down curve related to the test dose. It also means that the number of curves for \(L_{x}\) has to be equal to the number of \(T_{x}\) curves, and that hot-bleach curves do not belong in a SAR sequence; at least not for the analysis. Other curves allowed and processed are preheat curves, or preheat curves measured as TL, and irradiation curves. The latter indicates the duration of the irradiation, the dose and test dose points, e.g., as part of XSYG files.
Argument object is of type list
If the argument object is of type list containing only
RLum.Analysis objects, the function re-calls itself on each element
in the list. This is useful for analysing an entire measurement without
writing separate for-loops. To gain full control of the parameters (e.g., dose.points) for
every aliquot (corresponding to one RLum.Analysis object in the list), in
this case the arguments can be provided as list. This list should
be of similar length as the list provided with the argument object,
otherwise the function will create an own list of the requested length.
Function output will be just one single RLum.Results object.
Please be careful when using this option. While it may allow for a fast and efficient data analysis, the function may break with an unclear error message if the input data is misspecified.
Working with IRSL data
The function was originally designed to work just for 'OSL' curves, following the principles of the SAR protocol. An IRSL measurement protocol may follow this procedure, e.g., post-IR IRSL protocol (Thomsen et al., 2008). Therefore this function has been enhanced to work with IRSL data, however, the function is only capable of analysing curves that follow the SAR protocol structure, i.e., to analyse a post-IR IRSL protocol, curve data have to be pre-selected by the user to fit the standards of the SAR protocol, i.e., Lx,Tx,Lx,Tx and so on.
Example: Imagine the measurement contains pIRIR50 and pIRIR225 IRSL
curves. Only one curve type can be analysed at the same time: either the
pIRIR50 curves or the pIRIR225 curves.
Supported rejection criteria
[recycling.ratio]: calculated for every repeated regeneration dose point.
[recuperation.rate]: recuperation rate calculated by comparing the
Lx/Tx values of the zero regeneration point with the Ln/Tn value (the
Lx/Tx ratio of the natural signal). For methodological background see
Aitken and Smith (1988). As a variant, recuperation_reference can be
specified to select another dose point as reference instead of Ln/Tn.
[testdose.error]: set the allowed error for the test dose, which by
default should not exceed 10%. The test dose error is calculated as
Tx_net.error/Tx_net. The calculation of the \(T_{n}\) error is detailed
in calc_OSLLxTxRatio.
[palaeodose.error]: set the allowed error for the De value, which by
default should not exceed 10%.
[sn.ratio]: set the allowed signal/noise ratio, which by default should
be at least 50. By default it uses the value from the natural curve, but
this can be changed by specifying the sn_reference option.
By default, the computed values are compared directly to the corresponding
thresholds to establish their result status ("OK" or "FAILED"). By setting
the option consider.uncertainties = TRUE in the rejection.criteria
list, quantified uncertainties are considered in the computation of the
test value before comparing it to the threshold(currently supported
only for recycling.ratio, recuperation.rate and exceed.max.regpoint).
This reduces tests being marked as "FAILED" when the deviation from the
threshold is smaller than the uncertainty margin.
Irradiation times
The function makes two attempts to extract irradiation data (dose points)
automatically from the input object, if the argument dose.points is not
set (aka set to NULL).
It searches in every curve for an info object called IRR_TIME. If this
is found, any value set there is taken as dose point.
If the object contains curves of type irradiation, the function tries
to use this information to assign these values to the curves. However, the
function does not overwrite values preset in IRR_TIME.
Aitken, M.J. and Smith, B.W., 1988. Optical dating: recuperation after bleaching. Quaternary Science Reviews 7, 387-393.
Duller, G., 2003. Distinguishing quartz and feldspar in single grain luminescence measurements. Radiation Measurements 37 (2), 161-165.
Murray, A.S. and Wintle, A.G., 2000. Luminescence dating of quartz using an improved single-aliquot regenerative-dose protocol. Radiation Measurements 32, 57-73.
Thomsen, K.J., Murray, A.S., Jain, M., Boetter-Jensen, L., 2008. Laboratory fading rates of various luminescence signals from feldspar-rich sediment extracts. Radiation Measurements 43, 1474-1486. doi:10.1016/j.radmeas.2008.06.002
Bluszcz, A., Adamiec, G., Herr, A., 2015. Estimation of equivalent dose and its uncertainty in the OSL SAR protocol when count numbers do not follow a Poisson distribution. Radiation Measurements 81, 46-54. doi:10.1016/j.radmeas.2015.01.004
calc_OSLLxTxRatio, fit_DoseResponseCurve, plot_DoseResponseCurve, RLum.Analysis, RLum.Results
##load data
##ExampleData.BINfileData contains two BINfileData objects
##CWOSL.SAR.Data and TL.SAR.Data
data(ExampleData.BINfileData, envir = environment())
##transform the values from the first position in a RLum.Analysis object
object <- Risoe.BINfileData2RLum.Analysis(CWOSL.SAR.Data, pos=1)
##perform SAR analysis and set rejection criteria
results <- analyse_SAR.CWOSL(
object = object,
signal_integral = 1:2,
background_integral = 900:1000,
log = "x",
fit.method = "SSE",
plot_onePage = TRUE,
rejection.criteria = list(
recycling.ratio = 10,
recuperation.rate = 10,
testdose.error = 10,
palaeodose.error = 10,
recuperation_reference = "Natural",
sn.ratio = 50,
sn_reference = "Natural",
exceed.max.regpoint = TRUE)
)
##show De results
get_RLum(results)
##show LnTnLxTx table
get_RLum(results, data.object = "LnLxTnTx.table")
## Run example with special case for
## the OTORX fit
if (FALSE) {
results <- analyse_SAR.CWOSL(
object = object,
signal_integral = 1:2,
background_integral = 900:1000,
dose.points.test = 15,
n.MC = 10,
fit.method = "OTORX")
}
Run the code above in your browser using DataLab