Release R Luminescence version 0.7.0

Analyse fading measurements

Calculating fading corrected ages (calc_FadingCorr()) following the approach by Huntley and Lamothe (2001) was already possible in the package 'Luminescence' since 2012. Until today, however, a function to analyse the fading measurements was still missing. The new function analyse_FadingMeasurement() closes this gap by enabling the analysis of common ‘SAR fading’ measurement data. The function can be fed with an RLum.Analysis object (raw measurement data) or with an \(L_x/T_x\) table and returns various numerical and graphical output. On top of that: the output can be directly forwarded to other functions, e.g., calc_FadingCorr() or calc_Kars2008() for further calculations.

g_value <- analyse_FadingMeasurement(
 object = fading_data,
 structure = c("Lx", "Tx"),
 plot = TRUE,
 verbose = TRUE,
 n.MC = 100)

## 
## [analyse_FadingMeasurement()]
## 
##  n.MC:   100
##  tc: 3.78e+02 s
## ---------------------------------------------------
## T_0.5 interpolated:  NA
## T_0.5 predicted: 4e+11
## g-value:     5.18 ± 0.88 (%/decade)
## g-value (norm. 2 days):  6.01 ± 0.9 (%/decade)
## ---------------------------------------------------
## rho':            3.98e-06 ± 7.15e-07
## log10(rho'):     -5.4 ± 0.08
## ---------------------------------------------------

Analyse data determined by the portable OSL reader

With this version, we now also support files produced by an SUERC portable OSL reader. Importing a PSL file is as easy as running

psl_file <- read_PSL2R(file = "myPSLfile.psl", 
                       drop_bg = TRUE, 
                       as_decay_curve = TRUE, 
                       smooth = TRUE, 
                       merge = TRUE)

Note that there are several additional arguments available to modify the data when importing the raw data to R (see ?read_PSL2R). Once the data are available in R the next logical step would be to analyse them, which can be done via analyse_portableOSL().

plot_RLum(object = psl_file, 
          combine = TRUE, 
          subset = list(recordType = c("IRSL", "OSL")))

psl_results <- analyse_portableOSL(object = psl_file, 
                                   signal.integral = 1:3, 
                                   invert = FALSE, 
                                   normalise = TRUE, 
                                   plot = TRUE)

head(round(get_RLum(psl_results), 2))

##    BSL BSL_error IRSL IRSL_error BSL_depletion IRSL_depletion IRSL_BSL_RATIO
## 1 0.67         0 0.70       0.00          0.87           0.91           1.05
## 2 1.33         0 1.43       0.01          0.88           0.90           1.07
## 3 0.36         0 0.45       0.00          1.21           1.03           1.27
## 4 0.40         0 0.42       0.00          1.05           1.02           1.06
## 5 1.92         0 1.93       0.01          0.90           0.93           1.01
## 6 1.87         0 1.84       0.01          0.96           0.95           0.98

As can be seen analyse_portableOSL() produces a recognizable plot of commonly reported parameters, i.e. the signal intensities, depletion ratios and signal ratios. The function returns the numeric values, which can be used for further processing if desired.

Anomalous fading correction for feldspar IRSL (Kars et al., 2008)

The newly introduced function calc_Kars2008() applies the approach described in Kars et al. (2008), developed from the model of Huntley (2006) to calculate the expected sample particular fraction of saturation of a feldspar and also to calculate fading corrected age using this model. The density of recombination centres ρ’ is a crucial parameter of this model and must be determined separately from a fading measurement. The function analyse_FadingMeasurement() can be used to calculate the sample specific ρ’ value.

Below an example with the example data provided by the package:

data("ExampleData.Fading", envir = environment())
fading_data <- ExampleData.Fading$fading.data$IR50

rhop <- analyse_FadingMeasurement(fading_data, 
                                  plot = FALSE, 
                                  verbose = FALSE, 
                                  n.MC = 999)

lxtx_data <- ExampleData.Fading$equivalentDose.data$IR50

kars_res <- calc_Kars2008(data = lxtx_data,
                          rhop = rhop,
                          ddot = c(7.00, 0.004),
                          readerDdot = c(0.134, 0.0067),
                          n.MC = 999)

## Warning: 'calc_Kars2008' is deprecated.
## Use 'calc_Huntley2006' instead.
## See help("Deprecated")

## 
## [calc_Huntley2006()]
## 
##  -------------------------------
##  (n/N) [-]:   0.15 ± 0.02
##  (n/N)_SS [-]:    0.36 ± 0.06
## 
##  ---------- Measured -----------
##  DE [Gy]:     130.97 ± 17.1
##  D0 [Gy]:     539.01 ± 20.76
##  Age [ka]:    18.71 ± 2.62
## 
##  ---------- Un-faded -----------
##  D0 [Gy]:     624.66 ± 12.36
## 
##  ---------- Simulated ----------
##  DE [Gy]:     305.39 ± 38.31
##  D0 [Gy]:     570.09 ± 4.68
##  Age [ka]:    43.63 ± 5.89
##  Age @2D0 [ka]:   162.88 ± 8.25
##  -------------------------------

The calc_Kars2008() function also calculates the level of saturation \(\left(\frac{n}{N}\right)\) and the field saturation (i.e. athermal steady state, \(\left(\frac{n}{N}\right)_{SS}\)) value for the sample under investigation using the sample specific ρ’, unfaded D0 and environmental dose rate \(\dot{D}\) values, following the approach of Kars et al. (2008).

Average Dose Model (Guérin et al., 2017)

To overcome the drawbacks of commonly used age (dose) models, Guérin et al., 2017 introduced a new dose model that calculates the average dose and their extrinsic dispersion and standard error by bootstrapping. The function fits neatly into the collection of approaches dealing with age (dose) models. Example for the package example data set:

data(ExampleData.DeValues, envir = environment())
AD <- calc_AverageDose(ExampleData.DeValues$CA1[1:56,],
sigma_m = 0.1)

## 
## [calc_AverageDose()]
## 
## >> Initialisation <<
## n:        56
## delta:        65.7939285714286
## sigma_m:  0.1
## sigma_d:  0.286159381384861
## 
## >> Calculation <<
## log likelihood:   -19.251
## confidence intervals
## --------------------------------------------------
##                          IC_delta      IC_sigma_d
## level                        0.95          0.9500
## CredibleIntervalInf         60.84          0.2145
## CredibleIntervalSup         69.99          0.3955
## --------------------------------------------------
## 
## >> Results <<
## ----------------------------------------------------------
## Average dose:      65.3597   se(Aver. dose):  2.4757
## sigma_d:   0.3092    se(sigma_d):     0.0471
## ----------------------------------------------------------

Getting closer with GitHub

As some of you may already know, the R package 'Luminescence' is actively developed and maintained on the web-based Git repository hosting service GitHub. In this package version, we introduce a couple of new functions that make use of the public GitHub API v3.

With github_issues() you can query known issues (output shortened):

github_issues()

## NA
## NA
## NA
## NA
## NA
## NA
## NA
## NA
## NA
## NA
## NA

github_branches() can be used to check all currently available development branches. The output further provides an install command that can be used to install a specific development branch manually.

github_branches()

##              BRANCH                                      SHA
## 1 dev_OSLcomponents ddce1b82ce51a5b955a96056800084718adb7c25
## 2         dev_0.9.x fa48e2585e86134729fcd9750f5ed27627f32b78
## 3            master b8ba3dfdcee5c129172c191ca631265177458dde
## 4           surfexp 17a482f4e2e82d5a2fe83af20a5b4844197176f0
##                                                            INSTALL
## 1 devtools::install_github('r-lum/luminescence@dev_OSLcomponents')
## 2         devtools::install_github('r-lum/luminescence@dev_0.9.x')
## 3            devtools::install_github('r-lum/luminescence@master')
## 4           devtools::install_github('r-lum/luminescence@surfexp')

Finally, github_commits() returns the latest n code commits to the package:

github_commits(n = 1)

##                                        SHA AUTHOR                 DATE
## 1 b8ba3dfdcee5c129172c191ca631265177458dde RLumSK 2020-11-03T12:27:42Z
##               MESSAGE
## 1 Update GitHub pages

Ultimately, all these functions are the foundation for the also newly introduced function install_DevelopmentVersion(); a convenient implementation for installing the development version of the R package 'Luminescence' directly from GitHub. This function uses github_branches() to check which development branches of the R package 'Luminescence' are currently available on GitHub. The user is then prompted to choose one of the branches to install. It further checks whether the R package 'devtools' is currently installed and available on the system. Finally, it prints R code to the console that the user can copy and paste into the R console in order to install the desired development version of the package.

Alternatively, with force_install = TRUE the functions checks if 'devtools' is available and then attempts to install the chosen development branch via install_github().

install_DevelopmentVersion()
install_DevelopmentVersion(force_install = TRUE)

Pipe your data

In the R-community a new operator, called “magrittr forward-pipe operator” or short %>%, from the package magrittr turned out as being very efficient for R code scripting. With this operator, values are piped from one function to another. Example:

rnorm(1000) %T>% hist(freq = FALSE, breaks = "FD") %>% density %>% lines

To further support this operator, the package magrittr is now loaded by default when attaching the package 'Luminescence'

Other enhancements

• Thanks to Antoine Zink the function read_Daybreak2R() now also handles binary files produced by the software TLAPLLIC v.3.2, used for a Daybreak, model 1100.