# Release R Luminescence version 0.7.0

#### - Advanced Fish-

###### by R Luminescence Team (February 20, 2017)

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 website 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.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.

### 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)
```

```
## 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
## ----------------------------------------------------------
```

### 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

`convert_BIN2CSV()`

`convert_Daybreak2CSV()`

`convert_PSL2CSV()`

`convert_XSYG2CSV()`

`write_RLum2CSV()`

### 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()`

```
## 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.

## 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