Analyse IRSAR RF measurements

Description

Function to analyse IRSAR RF measurements on K-feldspar samples, performed using the protocol according to Erfurt et al. (2003) and beyond.

Usage

analyse_IRSAR.RF(object, sequence_structure = c("NATURAL", "REGENERATED"),
  RF_nat.lim = NULL, RF_reg.lim = NULL, method = "FIT",
  method.control = NULL, test_parameters = NULL, n.MC = 10,
  txtProgressBar = TRUE, plot = TRUE, plot_reduced = FALSE, ...)

Arguments

Details

The function performs an IRSAR analysis described for K-feldspar samples by Erfurt et al. (2003) assuming a negligible sensitivity change of the RF signal.

General Sequence Structure (according to Erfurt et al. (2003))

1. Measuring IR-RF intensity of the natural dose for a few seconds (RF_{nat})

2. Bleach the samples under solar conditions for at least 30 min without changing the geometry

3. Waiting for at least one hour

4. Regeneration of the IR-RF signal to at least the natural level (measuring (RF_{reg})

5. Fitting data with a stretched exponential function

6. Calculate the the palaeodose D_{e} using the parameters from the fitting

Actually two methods are supported to obtain the D_{e}: method = "FIT" and method = "SLIDE":

method = "FIT"

The principle is described above and follows the original suggestions by Erfurt et al., 2003. For the fitting the mean count value of the RF_nat curve is used.

Function used for the fitting (according to Erfurt et al. (2003)):

φ(D) = φ_{0}-Δφ(1-exp(-λ*D))^β

with φ(D) the dose dependent IR-RF flux, φ_{0} the inital IR-RF flux, Δφ the dose dependent change of the IR-RF flux, λ the exponential parameter, D the dose and β the dispersive factor.

To obtain the palaeodose D_{e} the function is changed to:

D_{e} = ln(-(φ(D) - φ_{0})/(-λ*φ)^{1/β}+1)/-λ

The fitting is done using the port algorithm of the nls function.

method = "SLIDE"

For this method the natural curve is slided along the x-axis until congruence with the regenerated curve is reached. Instead of fitting this allows to work with the original data without the need of any physical model. This approach was introduced for RF curves by Buylaert et al., 2012 and Lapp et al., 2012.

Here the sliding is done by searching for the minimum of the squared residuals.

method.control

To keep the generic argument list as clear as possible, arguments to control the methods for De estimation are all preset with meaningful default parameters and can be handled using the argument method.control only, e.g., method.control = list(trace = TRUE). Supported arguments are:

Error estimation

For method = "FIT" the asymmetric error range is obtained by using the 2.5 % (lower) and the 97.5 % (upper) quantiles of the RF_{nat} curve for calculating the D_{e} error range.

For method = "SLIDE" the error is obtained by bootstrapping the residuals of the slided curve to construct new natural curves for a Monte Carlo simulation. The error is returned in two ways: (a) the standard deviation of the herewith obtained D_{e} from the MC runs and (b) the confidence interval using the 2.5 % (lower) and the 97.5 % (upper) quantiles. The results of the MC runs are returned with the function output.

Test parameters

The argument test_parameters allows to pass some thresholds for several test parameters, which will be evaluated during the function run. If a threshold is set and it will be exceeded the test parameter status will be set to "FAILED". Intentionally this parameter is not termed 'rejection criteria' as not all test parameters are evaluated for both methods and some parameters are calculated by not evaluated by default. Common for all parameters are the allowed argument options NA and NULL. If the parameter is set to NA the value is calculated but the result will not be evaluated, means it has no effect on the status ("OK" or "FAILED") of the parameter. Setting the parameter to NULL disables the parameter entirely and the parameter will be also removed from the function output. This might be useful in cases where a particular parameter asks for long computation times. Currently supported parameters are:

curves_ratio numeric (default: 1.001):

The ratio of RF_{nat} over RF_{reg} in the range ofRF_{nat} of is calculated and should not exceed the threshold value.

intersection_ratio numeric (default: NA):

Calculated as absolute difference from 1 of the ratio of the integral of the normalised RF-curves, This value indicates intersection of the RF-curves and should be close to 0 if the curves have a similar shape. For this calculation first the corresponding time-count pair value on the RF_reg curve is obtained using the maximum count value of the RF_nat curve and only this segment (fitting to the RF_nat curve) on the RF_reg curve is taken for further calculating this ratio. If nothing is found at all, Inf is returned.

residuals_slope numeric (default: NA; only for method = "SLIDE"):

A linear function is fitted on the residuals after sliding. The corresponding slope can be used to discard values as a high (positive, negative) slope may indicate that both curves are fundamentally different and the method cannot be applied at all. Per default the value of this parameter is calculated but not evaluated.

curves_bounds numeric (default: max(RF_{reg_counts}):

This measure uses the maximum time (x) value of the regenerated curve. The maximum time (x) value of the natural curve cannot be larger than this value. However, although this is not recommended the value can be changed or disabled.

dynamic_ratio numeric (default: NA):

The dynamic ratio of the regenerated curve is calculated as ratio of the minimum and maximum count values.

lambda, beta and delta.phi numeric (default: NA; method = "SLIDE"):

The stretched exponential function suggested by Erfurt et al. (2003) describing the decay of the RF signal, comprises several parameters that might be useful to evaluate the shape of the curves. For method = "FIT" this parameter is obtained during the fitting, for method = "SLIDE" a rather rough estimation is made using the function nlsLM and the equation given above. Note: As this procedure requests more computation time, setting of one of these three parameters to NULL also prevents a calculation of the remaining two.

Value

A plot (optional) and an RLum.Results object is returned:

@data
$ De.values: data.frame table with De and corresponding values
..$ DE : numeric: the obtained equivalent dose
..$ DE.ERROR : numeric: (only method = "SLIDE") standard deviation obtained from MC runs
..$ DE.LOWER : numeric: 2.5% quantile for De values obtained by MC runs
..$ DE.UPPER : numeric: 97.5% quantile for De values obtained by MC runs
..$ DE.STATUS : character: test parameter status
..$ RF_NAT.LIM : charcter: used RF_nat curve limits
..$ RF_REG.LIM : character: used RF_reg curve limits
..$ POSITION : integer: (optional) position of the curves
..$ DATE : character: (optional) measurement date
..$ SEQUENCE_NAME : character: (optional) sequence name
..$ UID : character: unique data set ID
$ test_parameters : data.frame table test parameters
$ fit : nls nlsModel object
$ slide : list data from the sliding process, including the sliding matrix

@info
$ call : language-class: the orignal function call

The output (De.values) should be accessed using the function get_RLum

Function version

0.6.9 (2016-05-27 10:40:45)

Note

[THIS FUNCTION HAS BETA-STATUS]

This function assumes that there is no sensitivity change during the measurements (natural vs. regenerated signal), which is in contrast to the findings from Buylaert et al. (2012). Furthermore: In course of ongoing research this function has been almost fully re-written, but further thoughtful tests are still pending! However, as a lot new package functionality was introduced with the changes made for this function and to allow a part of such tests the re-newed code was made part of the current package.

Author(s)

Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montaigne (France)
R Luminescence Package Team

References

Buylaert, J.P., Jain, M., Murray, A.S., Thomsen, K.J., Lapp, T., 2012. IR-RF dating of sand-sized K-feldspar extracts: A test of accuracy. Radiation Measurements 44 (5-6), 560-565. doi: 10.1016/j.radmeas.2012.06.021

Erfurt, G., Krbetschek, M.R., 2003. IRSAR - A single-aliquot regenerative-dose dating protocol applied to the infrared radiofluorescence (IR-RF) of coarse- grain K-feldspar. Ancient TL 21, 35-42.

Erfurt, G., 2003. Infrared luminescence of Pb+ centres in potassium-rich feldspars. physica status solidi (a) 200, 429-438.

Erfurt, G., Krbetschek, M.R., 2003. Studies on the physics of the infrared radioluminescence of potassium feldspar and on the methodology of its application to sediment dating. Radiation Measurements 37, 505-510.

Erfurt, G., Krbetschek, M.R., Bortolot, V.J., Preusser, F., 2003. A fully automated multi-spectral radioluminescence reading system for geochronometry and dosimetry. Nuclear Instruments and Methods in Physics Research Section B: Beam Interactions with Materials and Atoms 207, 487-499.

Lapp, T., Jain, M., Thomsen, K.J., Murray, A.S., Buylaert, J.P., 2012. New luminescence measurement facilities in retrospective dosimetry. Radiation Measurements 47, 803-808. doi:10.1016/j.radmeas.2012.02.006

Trautmann, T., 2000. A study of radioluminescence kinetics of natural feldspar dosimeters: experiments and simulations. Journal of Physics D: Applied Physics 33, 2304-2310.

Trautmann, T., Krbetschek, M.R., Dietrich, A., Stolz, W., 1998. Investigations of feldspar radioluminescence: potential for a new dating technique. Radiation Measurements 29, 421-425.

Trautmann, T., Krbetschek, M.R., Dietrich, A., Stolz, W., 1999. Feldspar radioluminescence: a new dating method and its physical background. Journal of Luminescence 85, 45-58.

Trautmann, T., Krbetschek, M.R., Stolz, W., 2000. A systematic study of the radioluminescence properties of single feldspar grains. Radiation Measurements 32, 685-690.

See Also

RLum.Analysis, RLum.Results, get_RLum, nls, nlsLM

Examples

##load data
data(ExampleData.RLum.Analysis, envir = environment())

##(1) perform analysis using the method 'FIT'
results <- analyse_IRSAR.RF(object = IRSAR.RF.Data)

##show De results and test paramter results
get_RLum(results, data.object = "De.values")
get_RLum(results, data.object = "test_parameters")

##(2) perform analysis using the method 'SLIDE'
results <- analyse_IRSAR.RF(object = IRSAR.RF.Data, method = "SLIDE", n.MC = 1)

## Not run: 
##(3) perform analysis using the method 'SLIDE' and method control option
## 'trace
results <- analyse_IRSAR.RF(
 object = IRSAR.RF.Data,
 method = "SLIDE",
 method.control = list(trace = TRUE))


## End(Not run)

Results

R version 3.3.1 (2016-06-21) -- "Bug in Your Hair"
Copyright (C) 2016 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.

R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.

Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.

> library(Luminescence)
Welcome to the R package Luminescence version 0.6.0 [Built: 2016-05-30 16:47:30 UTC]
A blue LED to a trapped electron: 'Resistance is futile.'
> png(filename="/home/ddbj/snapshot/RGM3/R_CC/result/Luminescence/analyse_IRSAR.RF.Rd_%03d_medium.png", width=480, height=480)
> ### Name: analyse_IRSAR.RF
> ### Title: Analyse IRSAR RF measurements
> ### Aliases: analyse_IRSAR.RF
> ### Keywords: datagen
> 
> ### ** Examples
> 
> 
> ##load data
> data(ExampleData.RLum.Analysis, envir = environment())
> 
> ##(1) perform analysis using the method 'FIT'
> results <- analyse_IRSAR.RF(object = IRSAR.RF.Data)
> 
> ##show De results and test paramter results
> get_RLum(results, data.object = "De.values")
      DE DE.ERROR DE.LOWER DE.UPPER DE.STATUS RF_NAT.LIM RF_REG.LIM POSITION
1 623.25       NA   600.63    635.8        OK        1:5      1:524       NA
  DATE SEQUENCE_NAME                                UID
1   NA            NA 2016-07-04-07:32.0.810128468088806
> get_RLum(results, data.object = "test_parameters")
  POSITION          PARAMETER THRESHOLD        VALUE STATUS SEQUENCE_NAME
1       NA       curves_ratio     1.001 6.845685e-01     OK            NA
2       NA intersection_ratio        NA 5.541736e-03     OK            NA
3       NA    residuals_slope        NA           NA     OK            NA
4       NA      curves_bounds   716.000 6.358000e+02     OK            NA
5       NA      dynamic_ratio        NA 1.524261e+00     OK            NA
6       NA             lambda        NA 2.182234e-04     OK            NA
7       NA               beta        NA 5.418719e-01     OK            NA
8       NA          delta.phi        NA 2.103400e+03     OK            NA
                                 UID
1 2016-07-04-07:32.0.810128468088806
2 2016-07-04-07:32.0.810128468088806
3 2016-07-04-07:32.0.810128468088806
4 2016-07-04-07:32.0.810128468088806
5 2016-07-04-07:32.0.810128468088806
6 2016-07-04-07:32.0.810128468088806
7 2016-07-04-07:32.0.810128468088806
8 2016-07-04-07:32.0.810128468088806
> 
> ##(2) perform analysis using the method 'SLIDE'
> results <- analyse_IRSAR.RF(object = IRSAR.RF.Data, method = "SLIDE", n.MC = 1)

	 Run Monte Carlo loops for error estimation
   |                                                                               |                                                                      |   0%   |                                                                               |======================================================================| 100%
Warning message:
In analyse_IRSAR.RF(object = IRSAR.RF.Data, method = "SLIDE", n.MC = 1) :
  Narrow density distribution, no density distribution plotted!
> 
> ## Not run: 
> ##D ##(3) perform analysis using the method 'SLIDE' and method control option
> ##D ## 'trace
> ##D results <- analyse_IRSAR.RF(
> ##D  object = IRSAR.RF.Data,
> ##D  method = "SLIDE",
> ##D  method.control = list(trace = TRUE))
> ##D 
> ## End(Not run)
> 
> 
> 
> 
> 
> 
> dev.off()
null device 
          1 
>