R Luminescence version > 0.7.0
- Advanced Fish -

R Luminescence Team

2017-02-19

Dear R Luminescence users!

We are happy to announce that another new version of our R package (0.7.3) just made it to CRAN. As usual: many thanks for your helpful suggestions and comments! This is a major update and comes with a lot of bugfixes and several new functions serving various requests out of the community. We are excited to present some the new possibilities below. For a full list of all changes, please check the CRAN webpage here.

What’s new?

New analysis functions

This release comes with two (one of them long requested) new analysis functions:

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.72 (%/decade)
## g-value (norm. 2 days):  6.01 ± 0.73 (%/decade)
## ---------------------------------------------------
## rho':            3.87e-06 ± 4.95e-07
## log10(rho'):     -5.41 ± 0.06
## ---------------------------------------------------

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
## 1 0.67         0 0.70       0.00          0.87           0.91
## 2 1.33         0 1.43       0.01          0.88           0.90
## 3 0.36         0 0.45       0.00          1.21           1.03
## 4 0.40         0 0.42       0.00          1.05           1.02
## 5 1.92         0 1.93       0.01          0.90           0.93
## 6 1.87         0 1.84       0.01          0.96           0.95
##   IRSL_BSL_RATIO
## 1           1.05
## 2           1.07
## 3           1.27
## 4           1.06
## 5           1.01
## 6           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.

New models

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)

## 
## [calc_Kars2008()]
## 
##  -------------------------------
##  (n/N) [-]:   0.15 ± 0.11
##  (n/N)_SS [-]:    0.35 ± 0.06
## 
##  ---------- Measured -----------
##  DE [Gy]:     130.97 ± 14.86
##  D0 [Gy]:     539.01 ± 19.53
##  Age [ka]:    18.71 ± 2.32
## 
##  ---------- Simulated ----------
##  DE [Gy]:     317.2 ± 36.06
##  D0 [Gy]:     623.42 ± 32.12
##  Age [ka]:    45.31 ± 5.63
## 
##  ---------- Un-faded -----------
##  D0 [Gy]:     625.02 ± 12.37
##  -------------------------------

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         61.06          0.2119
## CredibleIntervalSup         70.20          0.4011
## --------------------------------------------------
## 
## >> Results <<
## ----------------------------------------------------------
## Average dose:      65.3597   se(Aver. dose):  2.4181
## sigma_d:   0.3092    se(sigma_d):     0.0482
## ----------------------------------------------------------

Conversions

Even data export to CSV-files is already part of R’s base functionality; we decided to make it even easier and more straight forward. Four new functions allow a direct and straight forward conversion from proprietary input formats to CSV-files

Miscellaneous

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()
## title: "Extent plot_DetPlot() for TL data"
## number: 10
## url: "https://api.github.com/repos/R-Lum/Luminescence/issues/10"
## created: 2016-09-19T12:28:35Z
## updated: 2016-10-04T10:06:57Z
## creator: RLumSK
## status: open
## milestone: "Release version 0.8.0"
## description: >
##     Actually the production of the De(t) plot is limited for OSL data, but I can make also sense for TL  
##     data. Internally: use the function calc_TLLxTxRatio()

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_0.7.0_JF d378446b10e739c64bd6fe634a8dc3f2bbcac97f
## 2    dev_0.8.0 c0e139b990855f50ddee7fd2a26b8a977c954df9
## 3       master a51937493d6c88526e909774cfb2c1a3c4b3fcf3
##                                                       INSTALL
## 1 devtools::install_github('r-lum/luminescence@dev_0.7.0_JF')
## 2    devtools::install_github('r-lum/luminescence@dev_0.8.0')
## 3       devtools::install_github('r-lum/luminescence@master')

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

github_commits(n = 1)
##                                        SHA AUTHOR                 DATE
## 1 a51937493d6c88526e909774cfb2c1a3c4b3fcf3 RLumSK 2017-02-16T17:36:49Z
##                                                 MESSAGE
## 1 Fix wrong URL\n\n# Conflicts:\n#\tman/calc_MinDose.Rd

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.

References

Huntley, D.J., Lamothe, M., 2001. Ubiquity of anomalous fading in K-feldspars and the measurement and correction for it in optical dating. Canadian Journal of Earth Sciences 38, 1093–1106. doi:10.1139/cjes-38-7-1093

Huntley, D.J., 2006. An explanation of the power-law decay of luminescence. Journal of Physics: Condensed Matter 18, 1359-1365. doi:10.1088/0953-8984/18/4/020

Kars, R.H., Wallinga, J., Cohen, K.M., 2008. A new approach towards anomalous fading correction for feldspar IRSL dating-tests on samples in field saturation. Radiation Measurements 43, 786-790. doi:10.1016/j.radmeas.2008.01.021