analyse_SAR.CWOSL: Analyse SAR CW-OSL measurements
In Luminescence: Comprehensive Luminescence Dating Data Analysis
View source: R/analyse_SAR.CWOSL.R
analyse_SAR.CWOSL R Documentation
Analyse SAR CW-OSL measurements
Description
The function performs a SAR CW-OSL analysis on an
RLum.Analysis object including growth curve fitting.
Usage
analyse_SAR.CWOSL(
object,
signal.integral.min = NA,
signal.integral.max = NA,
background.integral.min = NA,
background.integral.max = NA,
OSL.component = NULL,
rejection.criteria = list(),
dose.points = NULL,
trim_channels = FALSE,
mtext.outer = "",
plot = TRUE,
plot_onePage = FALSE,
plot.single = FALSE,
onlyLxTxTable = FALSE,
...
)
Arguments
object
RLum.Analysis (required):
input object containing data for analysis, alternatively a list of
RLum.Analysis objects can be provided. The object should contain only curves
considered part of the SAR protocol (see Details.)
signal.integral.min
integer (required):
lower bound of the signal integral. Can be a list of integers, if object is
of type list. If the input is vector (e.g., c(1,2)) the 2nd value will be interpreted
as the minimum signal integral for the Tx curve. Can be set to NA, in this
case no integrals are taken into account.
signal.integral.max
integer (required):
upper bound of the signal integral. Can be a list of integers, if object is
of type list. If the input is vector (e.g., c(1,2)) the 2nd value will be interpreted
as the maximum signal integral for the Tx curve. Can be set to NA, in this
case no integrals are taken into account.
background.integral.min
integer (required):
lower bound of the background integral. Can be a list of integers, if object is
of type list. If the input is vector (e.g., c(1,2)) the 2nd value will be interpreted
as the minimum background integral for the Tx curve. Can be set to NA, in this
case no integrals are taken into account.
background.integral.max
integer (required):
upper bound of the background integral. Can be a list of integers, if object is
of type list. If the input is vector (e.g., c(1,2)) the 2nd value will be interpreted
as the maximum background integral for the Tx curve. Can be set to NA, in this
case no integrals are taken into account.
OSL.component
character or integer (optional): s 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 the 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.
rejection.criteria
list (with default):
provide a named list and set rejection criteria in percentage
for further calculation. Can be a list in a list, if object is of type list.
Note: If an unnamed list is provided the new settings are ignored!
Allowed arguments are recycling.ratio, recuperation.rate,
palaeodose.error, testdose.error, exceed.max.regpoint = TRUE/FALSE,
recuperation_reference = "Natural" (or any other dose point, e.g., "R1").
Example: rejection.criteria = list(recycling.ratio = 10).
Per default all numerical values are set to 10, exceed.max.regpoint = TRUE.
Every criterion can be set to NA. In this value are calculated, but not considered, i.e.
the RC.Status becomes always 'OK'
dose.points
numeric (optional):
a numeric vector containing the dose points 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
trim_channels
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 passing the input object.
mtext.outer
character (optional):
option to provide an outer margin mtext. Can be a list of characters,
if object is of type list
plot
logical (with default): enables or disables plot output.
plot_onePage
logical (with default): enables or disables on page plot output
plot.single
logical (with default) or numeric (optional):
single plot output (TRUE/FALSE) to allow for plotting the results in single plot windows.
If a numeric vector is provided the plots can be selected individually, i.e.
plot.single = c(1,2,3,4) will plot the TL and Lx, Tx curves but not the legend (5) or the
growth curve (6), (7) and (8) belong to rejection criteria plots. Requires
plot = TRUE.
onlyLxTxTable
logical (with default): If TRUE the dose response
curve fitting and plotting is skipped.
This allows to get hands on the Lx/Tx table for large datasets
without the need for a curve fitting.
...
further arguments that will be passed to the function
plot_GrowthCurve or calc_OSLLxTxRatio
(supported: background.count.distribution, sigmab, sig0).
Please note that if you consider to use the early light subtraction
method you should provide your own sigmab value!
Details
The function performs an analysis for a 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. For changing the way the Lx/Tx error is calculated use the argument
background.count.distribution and sigmab, which will be passed to the function
calc_OSLLxTxRatio.
What is part of a SAR sequence?
The function is rather picky when it comes down to accepted curve input (OSL,IRSL,...) and structure.
A SAR sequence is basically a set of L_{x}/T_{x} curves. Hence, every 2nd 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 into 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 later one 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 as often as elements
are in the list. This is useful if an entire measurement wanted to be analysed without
writing separate for-loops. To gain in 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. It may allow a fast an efficient data analysis, but
the function may also break with an unclear error message, due to wrong input data.
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 functions 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: 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 with the argument recuperation_reference another dose point can be
selected as reference instead of Ln/Tn.
[testdose.error]: set the allowed error for the test dose, which per
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 per
default should not exceed 10%.
Irradiation times
The function makes two attempts to extra irradiation data (dose points)
automatically from the input object, if the argument dose.points was not
set (aka set to NULL).
It searches in every curve for an info object called IRR_TIME. If this was set, any value
set here 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.
Value
A plot (optional) and an RLum.Results object is
returned containing the following elements:
data
data.frame containing De-values, De-error and further parameters
LnLxTnTx.values
data.frame of all calculated Lx/Tx values including signal,
background counts and the dose points
rejection.criteria
data.frame with values that might by used as rejection criteria.
NA is produced if no R0 dose point exists.
Formula
formula formula that have been used for the growth curve fitting
The output should be accessed using the function get_RLum.
Function version
0.10.3
How to cite
Kreutzer, S., 2024. analyse_SAR.CWOSL(): Analyse SAR CW-OSL measurements. Function version 0.10.3. 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., 2024. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.24. https://CRAN.R-project.org/package=Luminescence
Note
This function must not be mixed up with the function
Analyse_SAR.OSLdata, which works with
Risoe.BINfileData objects.
The function currently does support only 'OSL', 'IRSL' and 'POSL' data!
Author(s)
Sebastian Kreutzer, Institute of Geography, Heidelberg University (Germany)
, RLum Developer Team
References
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
See Also
calc_OSLLxTxRatio, plot_GrowthCurve, RLum.Analysis,
RLum.Results, get_RLum
Examples
##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.min = 1,
signal.integral.max = 2,
background.integral.min = 900,
background.integral.max = 1000,
log = "x",
fit.method = "EXP",
rejection.criteria = list(
recycling.ratio = 10,
recuperation.rate = 10,
testdose.error = 10,
palaeodose.error = 10,
recuperation_reference = "Natural",
exceed.max.regpoint = TRUE)
)
##show De results
get_RLum(results)
##show LnTnLxTx table
get_RLum(results, data.object = "LnLxTnTx.table")
Luminescence documentation built on June 22, 2024, 9:54 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
View source: R/analyse_SAR.CWOSL.R
| analyse_SAR.CWOSL | R Documentation |
Analyse SAR CW-OSL measurements
Description
The function performs a SAR CW-OSL analysis on an RLum.Analysis object including growth curve fitting.
Usage
analyse_SAR.CWOSL(
object,
signal.integral.min = NA,
signal.integral.max = NA,
background.integral.min = NA,
background.integral.max = NA,
OSL.component = NULL,
rejection.criteria = list(),
dose.points = NULL,
trim_channels = FALSE,
mtext.outer = "",
plot = TRUE,
plot_onePage = FALSE,
plot.single = FALSE,
onlyLxTxTable = FALSE,
...
)
Arguments
object |
RLum.Analysis (required): input object containing data for analysis, alternatively a list of RLum.Analysis objects can be provided. The object should contain only curves considered part of the SAR protocol (see Details.) |
signal.integral.min |
integer (required):
lower bound of the signal integral. Can be a list of integers, if |
signal.integral.max |
integer (required):
upper bound of the signal integral. Can be a list of integers, if |
background.integral.min |
integer (required):
lower bound of the background integral. Can be a list of integers, if |
background.integral.max |
integer (required):
upper bound of the background integral. Can be a list of integers, if |
OSL.component |
character or integer (optional): s single index
or a character defining the signal component to be evaluated.
It requires that the object was processed by |
rejection.criteria |
list (with default):
provide a named list and set rejection criteria in percentage
for further calculation. Can be a list in a list, if Allowed arguments are |
dose.points |
numeric (optional):
a numeric vector containing the dose points values. Using this argument
overwrites dose point values extracted from other data. Can be a list of
numeric vectors, if |
trim_channels |
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 |
mtext.outer |
character (optional):
option to provide an outer margin |
plot |
logical (with default): enables or disables plot output. |
plot_onePage |
logical (with default): enables or disables on page plot output |
plot.single |
logical (with default) or numeric (optional):
single plot output ( |
onlyLxTxTable |
logical (with default): If |
... |
further arguments that will be passed to the function
plot_GrowthCurve or calc_OSLLxTxRatio
(supported: |
Details
The function performs an analysis for a 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. For changing the way the Lx/Tx error is calculated use the argument
background.count.distribution and sigmab, which will be passed to the function
calc_OSLLxTxRatio.
What is part of a SAR sequence?
The function is rather picky when it comes down to accepted curve input (OSL,IRSL,...) and structure.
A SAR sequence is basically a set of L_{x}/T_{x} curves. Hence, every 2nd 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 into 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 later one 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 as often as elements
are in the list. This is useful if an entire measurement wanted to be analysed without
writing separate for-loops. To gain in 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. It may allow a fast an efficient data analysis, but the function may also break with an unclear error message, due to wrong input data.
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 functions 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: 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 with the argument recuperation_reference another dose point can be
selected as reference instead of Ln/Tn.
[testdose.error]: set the allowed error for the test dose, which per
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 per
default should not exceed 10%.
Irradiation times
The function makes two attempts to extra irradiation data (dose points)
automatically from the input object, if the argument dose.points was not
set (aka set to NULL).
It searches in every curve for an info object called
IRR_TIME. If this was set, any value set here 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 inIRR_TIME.
Value
A plot (optional) and an RLum.Results object is returned containing the following elements:
data |
data.frame containing De-values, De-error and further parameters |
LnLxTnTx.values |
data.frame of all calculated Lx/Tx values including signal, background counts and the dose points |
rejection.criteria |
data.frame with values that might by used as rejection criteria.
|
Formula |
formula formula that have been used for the growth curve fitting |
The output should be accessed using the function get_RLum.
Function version
0.10.3
How to cite
Kreutzer, S., 2024. analyse_SAR.CWOSL(): Analyse SAR CW-OSL measurements. Function version 0.10.3. 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., 2024. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.24. https://CRAN.R-project.org/package=Luminescence
Note
This function must not be mixed up with the function Analyse_SAR.OSLdata, which works with Risoe.BINfileData objects.
The function currently does support only 'OSL', 'IRSL' and 'POSL' data!
Author(s)
Sebastian Kreutzer, Institute of Geography, Heidelberg University (Germany) , RLum Developer Team
References
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
See Also
calc_OSLLxTxRatio, plot_GrowthCurve, RLum.Analysis, RLum.Results, get_RLum
Examples
##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.min = 1,
signal.integral.max = 2,
background.integral.min = 900,
background.integral.max = 1000,
log = "x",
fit.method = "EXP",
rejection.criteria = list(
recycling.ratio = 10,
recuperation.rate = 10,
testdose.error = 10,
palaeodose.error = 10,
recuperation_reference = "Natural",
exceed.max.regpoint = TRUE)
)
##show De results
get_RLum(results)
##show LnTnLxTx table
get_RLum(results, data.object = "LnLxTnTx.table")
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.