In the following we give you detailed instructions on how the R function library (package) OSLdecompostion can be used in conjunction with the Luminescence package to analyse SAR protocol measured data sets. Instructions how to install the OSLdecompostion package and how to update the Luminescence package to version 0.9.9 can be found in the Download & Installation webpage. The OSLdecompostion package can also be used without the Luminescence package and for other than SAR data sets.

## 1 SAR protocol measurements

We recommend to copy & paste the following code example into a new R script and run it once to see what happen. Then costumize the script the way we describe it in the following sections.

### 1.1 Script example

# Load R packages
library(OSLdecomposition)
library(Luminescence)

# Load example data from the Luminescence package
data(ExampleData.BINfileData, envir = environment())
data_set <- Risoe.BINfileData2RLum.Analysis(CWOSL.SAR.Data)

# Check the data for consistency and shorten the measurement duration
data_set <- RLum.OSL_correction(data_set)

# Identify the OSL components globally (Step 1)
data_set <- RLum.OSL_global_fitting(data_set)

# Separate OSL components in each record
data_set <- RLum.OSL_decomposition(data_set)

# Calculate the equivalent doses for the fast component
De_fast <- analyse_SAR.CWOSL(data_set, OSL.component = 1)

# ... and also for the medium component
De_medium <- analyse_SAR.CWOSL(data_set, OSL.component = 2)

# Compare both in a kernel density plot
plot_KDE(list(De_fast, De_medium))

The output will look like this:

> # Load example data from the Luminescence package
> data(ExampleData.BINfileData, envir = environment())
> data_set <- Risoe.BINfileData2RLum.Analysis(CWOSL.SAR.Data)

> # Check the data for consistency and shorten the measurement duration
> data_set <- RLum.OSL_correction(data_set)
CORRECTION STEP 1 ----- Check records for consistency in the detection settings -----
All OSL records have the same detection settings
(time needed: 1.28 s)

CORRECTION STEP 2 ----- Cut records at specific time -----
Measurement duration of 336 records reduced to 20 s
(time needed: 0.1 s)

> # Identify the OSL components globally (Step 1)
> data_set <- RLum.OSL_global_fitting(data_set)
STEP 1.1 ----- Build global average curve from all CW-OSL curves -----
Built global average curve from arithmetic means from first 500 data points of all 336 OSL records
(time needed: 10.59 s)

STEP 1.2 ----- Perform multi-exponential curve fitting -----

Decay rates (s^-1):
Cycle       Comp. 1     Comp. 2     Comp. 3     Comp. 4     Comp. 5         RSS     F-value
K = 1         3.115                                                   1.356e+06         Inf
K = 2         3.456     0.05745                                       5.802e+04        5551
K = 3         4.006        1.25     0.02935                                2966        4585
K = 4         4.908       2.664      0.4329     0.01578                   327.3        1983
K = 5         5.342       3.024      0.9848      0.2568    0.009924       292.8       28.83
Left loop because F-test value (F = 28.83) fell below threshold value (F = 150)
-> The F-test suggests the K = 4 model

Photoionisation cross sections (cm^2):
Cycle     Comp. 1              Comp. 2              Comp. 3              Comp. 4              Comp. 5
K = 1    3.76e-17
K = 2    4.17e-17             6.94e-19
K = 3    4.84e-17             1.51e-17             3.54e-19 (Slow2)
K = 4    5.93e-17             3.22e-17             5.23e-18 (Medium)    1.91e-19 (Slow2)
K = 5    6.45e-17             3.65e-17             1.19e-17             3.1e-18 (Medium)     1.2e-19 (Slow2)
-> Most known quartz OSL components found in the K = 4 model
(time needed: 108.59 s)

> # Separate OSL components in each record
> data_set <- RLum.OSL_decomposition(data_set)
STEP 2.1 ----- Define signal bin intervals -----
Find intervals with lowest component cross correlation by maximising the denominator determinant in Cramers rule:
Maximum determinant = 0.1377 with interval dividing channels at i = 10, 73
(time needed: 1.13 s)

STEP 2.2 ----- Decompose each  OSL  curve -----
Calculate signal intensity n in each OSL  by ' det+nls ' algorithm with empiric error estimation
Table of input decay constants and signal bin intervals for [decompose_OSLcurve()]:
name     lambda t.start t.end ch.start ch.end
1 Component 1 4.00622665    0.00  0.40        1     10
2 Component 2 1.25030289    0.40  2.92       11     73
3       Slow2 0.02934643    2.92 20.00       74    500

........................
Successfully decomposed 336 records
(time needed: 11.19 s)

> # Calculate the equivalent doses for the fast component
> De_fast <- analyse_SAR.CWOSL(data_set, OSL.component = 1)
[plot_GrowthCurve()] Fit: EXP (interpolation) | De = 1875.01 | D01 = 1989.56
[plot_GrowthCurve()] Fit: EXP (interpolation) | De = 1532.6 | D01 = 2177.44
[plot_GrowthCurve()] Fit: EXP (interpolation) | De = 1386.16 | D01 = 2076.68
... (output shortened)

> # ... and also for the medium component
> De_medium <- analyse_SAR.CWOSL(data_set, OSL.component = 2)
[plot_GrowthCurve()] Fit: EXP (interpolation) | De = 539.85 | D01 = 913.61
[plot_GrowthCurve()] Fit: EXP (interpolation) | De = 911.61 | D01 = 1078.48
[plot_GrowthCurve()] Fit: EXP (interpolation) | De = 2046.94 | D01 = 1062.6
... (output shortened)

> # Compare both in a kernel density plot
> plot_KDE(list(De_fast, De_medium))

In the output diagram, black data points are Fast component equivalent dose values and red data points are Medium component equivalent dose values.

### 1.2 Analyse your own data set

To read a BIN or BINX data file, replace code lines 5 to 7 of the script above with:

# Chose input file and convert it into a RLum.data object
file_path <- file.choose()
data_set <- read_BIN2R(data_set, fastForward = TRUE)

You can also read XSYG files by using read_XSYG2R().

### 1.3 Automatically created reports

You can activate the output of detailed reports for the component identification and separation steps with the parameter report. Replace code line 12 to 16 with the following code snippet:

# Identify the OSL components globally (Step 1)
data_set <- RLum.OSL_global_fitting(data_set, report = TRUE)

# Separate OSL components in each record
data_set <- RLum.OSL_decomposition(data_set, report = TRUE)

For each step, a new tab with the analysis report will automatically open in your browser. Examples for another data set can be found can be found here and here.

As default, these reports are not saved and will be deleted the moment you end your R session. To save them as HTML file, define the parameter report_dir with an directory path of your choice. Be aware, that R does not accept “\” as folder separator. You have to use either “/” or “\\”. The following code will save the reports into your input file directory (see section 1.2):

# Identify the OSL components globally (Step 1)
data_set <- RLum.OSL_global_fitting(data_set, report = TRUE, report_dir = file_path)

# Separate OSL components in each record
data_set <- RLum.OSL_decomposition(data_set, report = TRUE, report_dir = file_path)

If you want to save the reports to your desktop, add this code line (might not work on all systems):

file_path <- file.path(dirname(path.expand('~')),'Desktop')

Per default, the report diagrams are saved as PDF vector graphics into the subfolder /report_figures. You can change the image output format by setting the parameter image_format:

# Separate OSL components in each record
data_set <- RLum.OSL_decomposition(data_set, report = TRUE, report_dir = file_path, image_format = "jpg")

### 1.5 Photo-ionisation cross sections

The function RLum.OSL_global_fitting() estimates the photo-ionisation cross section values of the signal components and compares it with literature values for quartz. The requirement for correct cross section values is, that the stimulation wavelength and the stimulation stimulation intensity are specified correctly. Default values are stimulation.wavelength = 470 (nm) and stimulation.intensity = 35 (mW/cm²). In the example script, the default stimulation intensity is too low. We estimate from figure 2 in the auto-report that 75 mW/cm² should be about right:

data_set <- RLum.OSL_global_fitting(data_set, stimulation_intensity = 75)

We obtain better suiting photoionisation cross section values:

Photoionisation cross sections (cm^2):
Cycle     Comp. 1              Comp. 2              Comp. 3              Comp. 4              Comp. 5
K = 1    1.76e-17
K = 2    1.95e-17 (Fast)      3.24e-19 (Slow2)
K = 3    2.26e-17 (Fast)      7.05e-18 (Medium)    1.65e-19 (Slow2)
K = 4    2.77e-17 (Fast)      1.5e-17              2.44e-18             8.89e-20
K = 5    3.01e-17 (Fast)      1.7e-17              5.55e-18 (Medium)    1.45e-18 (Slow1)     5.59e-20
-> Most known quartz OSL components found in the K = 3 model 

### 1.4 CW-OSL model selection

The single curve component separation function RLum.OSL_decomposition() uses the 3-component-model (K = 3) as default. You can change the used model manually with the parameter K. In the above example, the K = 2 might also lead to sufficient results. We can test this by setting:

data_set <- RLum.OSL_decomposition(data_set, K = 2)

For other data sets, the K = 3 model might not sufficiently describe the complexity of the CW-OSL decays and the K = 4 is a better choice. But be aware that precision and robustness against systematic errors of the decomposition process declines with an increasing number of components. The approach should be: As much as necessary, as little as possible

## 2 General remarks

This tutorial will grow with the time. You can call additional information for all functions by typing ? before the function in the R console. For example, this command will call the documentation of the correction step:

?RLum.OSL_correction

© Dirk Mittelstraß, 2020 - 2021 | This website was created with Rmarkdown