Step 1: Load the package ‘Luminescence’

Simple, but indispensable, our first step is loading the R package ’Luminescence':

library(Luminescence)

Step 2: Load and select your data

Without data, no data analysis. We now import the measurement data into R by calling the function read_BIN2R() (if you have XSYG-files, use read_XSYG2R() instead). The function file.choose() opens an external window to allow a very convenient file selection. The argument fastForward makes sure that the data are directly available in the format we want to have them.

file <- file.choose()
temp <- read_BIN2R(file, fastForward = TRUE)

Not every data set is instantly ready to be analysed, e.g., the data set may contain additional information, which are not needed for the analysis. This is the case for our test data set. As written in Fuchs et al. (2015), only the first 20 aliquots follow the common SAR procedure, i.e. a consecutive sequence of irradiation, heating, OSL (\(L_x\)), irradiation, heating and OSL (\(T_x\)). Therefore, we have to limit our data set to the first 20 aliquots:

temp.sel <- temp[1:20]

Note: Further limitations can be applied by using the function get_RLum(). Type ?get_RLum in your R console to get further information. Please do not forget to set the parameter get_RLum(...,drop = FALSE) otherwise your object will look different from what the function expects as input.

Step 3: Run the SAR analysis

Now the data are ready and can be analysed calling the function analyse_SAR.CWOSL:

results <- analyse_SAR.CWOSL(
  object = temp.sel,
  signal.integral.min = 1,
  signal.integral.max = 5,
  background.integral.min = 200,
  background.integral.max = 250,
  fit.method = "EXP",
  rejection.criteria = list(
    recycling.ratio = 10,
    recuperation.rate = 10,
    testdose.error = 10,
    palaeodose.error = 20,
    exceed.max.regpoint = TRUE),
  plot_onePage = TRUE
)

Figure 1: Example output for one aliquot.

The graphical output consists of three different plot sets: (A) the preheat curves (here as TL) and the OSL curves used to calculate \(L_{x}/T_{x}\), (B) the dose response curve and (C) a plot showing visualising the rejection criteria and, if measured, the IRSL curve checking for a potential feldspar contamination of the quartz sample.

To modify arguments or to understand the meaning of the given arguments, please type ?analyse_SAR.CWOSL in your R console.

The results of the analysis is a complex R object (here named results), which can be used for further analysis.

results

## 
##  [RLum.Results-class]
##   originator: analyse_SAR.CWOSL()
##   data: 4
##       .. $data : data.frame
##   .. $LnLxTnTx.table : data.frame
##   .. $rejection.criteria : data.frame
##   .. $Formula : list
##   additional info elements:  20

To show only the obtained equivalent dose \(D_{e}\) values, the following line needs to be typed on the R console:

head(results$data)

head(results$data[,c("De", "RC.Status")])

##          De RC.Status
## 1 1195.3066        OK
## 2  517.3256        OK
## 3 1586.1348        OK
## 4 2594.8597        OK
## 5 1098.9140        OK
## 6 1445.5594        OK

head(results$rejection.criteria)

df <- merge(results$data, results$rejection.criteria, by = "UID")

Step 4: Plot your data

The last step. No luminescence data analysis without a graphical representation of the results. Below we have chosen the abanico plot (Dietze et al. 2016) to visualise the final \(D_e\) distribution. The prior used function subset ensures that only values are shown, which have successfully been passed the rejection criteria.

df <- subset(results$data, RC.Status == "OK")
plot_AbanicoPlot(df[,1:2], zlab = expression(paste(D[e], " [s]")))

The compact call

Now let’s do all of this in a single, neat call using the |> pipe operator supported in R >= 4.0.0 onwards.

Note: Minor differences in the plot are due to the Monte Carlo runs used for the estimation of the uncertainty.

results <- read_BIN2R(file, verbose = FALSE, fastForward = TRUE)[1:20] |>
  analyse_SAR.CWOSL(
    signal.integral.min = 1,
    signal.integral.max = 5,
    background.integral.min = 200,
    background.integral.max = 250,
    fit.method = "EXP",
    rejection.criteria = list(
      recycling.ratio = 10,
      recuperation.rate = 10,
      testdose.error = 10,
      palaeodose.error = 20,
      exceed.max.regpoint = TRUE),
    plot = FALSE,
    verbose = FALSE) |>
  get_RLum(data.object = "data") |>
  subset(RC.Status == "OK") |>
  plot_AbanicoPlot(zlab = expression(paste(D[e], " [s]")))