2.1 @METADATA

Once imported, the object (here bin_data) contains elements called slots. One is METADATA, which is a data.frame, and it includes all metadata of the measurements as some kind of big spreadsheet you may have already seen in the central window of the software Analyst (Duller 2015).

head(bin_data@METADATA)

2.2 @DATA

The second slot, DATA, is of type list. The element contains the actual measurement data in the order they were recorded. In R they are represented as numeric vectors.

## show first 20 data points 
## of the first record
bin_data@DATA[[1]][1:20]

##  [1] 1057  952  876  798  835  730  726  646  650  553  526  562  507  443  398
## [16]  388  367  369  336  304

Every single row in METADATA refers to one record in DATA. The link between the two is the column ID in METADATA.

It is essential to understand that DATA only contains count data of the measurement, which means y values only. It looks odd, but the data are stored for memory efficiency reasons in the BIN/BINX files. The x values (time or temperatures values) are calculated on the fly if needed using the METADATA information.

3.1 Import and export

args(read_BIN2R)

## function (file, show.raw.values = FALSE, position = NULL, n.records = NULL, 
##     zero_data.rm = TRUE, duplicated.rm = FALSE, fastForward = FALSE, 
##     show.record.number = FALSE, txtProgressBar = TRUE, forced.VersionNumber = NULL, 
##     ignore.RECTYPE = FALSE, pattern = NULL, verbose = TRUE, ...) 
## NULL

read_BIN2R(file = "/myBIN_file_folder/", pattern = "Aberystwyth")

## import only records from position 1
read_BIN2R(file, position = 1)

## import only the first 100 records (regardless the position number)
read_BIN2R(file, n.records = 100)

## import BIN-file version 3
V3 <- read_BIN2R(file, verbose = FALSE)

## export to version 8, here a temporary file
write_R2BIN(V3, tempfile(), version = "8", txtProgressBar = FALSE)

output_path <- tempdir()
convert_BIN2CSV(file, path = output_path, verbose = FALSE)
head(list.files(output_path))

## [1] "[[1]]_1_OSL.csv"  "[[1]]_10_OSL.csv" "[[1]]_11_TL.csv"  "[[1]]_12_OSL.csv"
## [5] "[[1]]_13_OSL.csv" "[[1]]_14_TL.csv"

3.2 Merging files

The idea of merging BIN/BINX files is probably self-explanatory. You may have split your measurements into different files on purpose, or you want to combine measurements that had stopped in the middle, and because of it, you had to re-run the sequence and ended up with multiple files. The function of merge_Risoe.BINfileData() takes either file names (or path to files) or object names of files already imported via read_BIN2R(). We can try this with our BIN/BINX file we have imported a few lines above (the object called bin_data).

merge_Risoe.BINfileData(c(bin_data, bin_data))

## 
## [Risoe.BINfileData object]
## 
##  BIN/BINX version      3
##  Object date:          271020, 281020, 291020
##  User:                 Default
##  System ID:            150
##  Overall records:      1584
##  Records type:         IRSL  (n = 72)
##                        OSL   (n = 1008)
##                        TL    (n = 504)
##  Position range:       1 : 72
##  Grain range:          0 : 0
##  Run range:            1 : 8
##  Set range:            3 : 6

The output is another time a Risoe.BINfileData-class object, with a crucial difference: Now, the position number runs from 1 to 72(!). Obviously, if there were a Risø device with a carousel with so many aliquot positions, it is not commercially available. The reason for this recalculation of position is that data analysis is usually carried out based on position numbers. But if we append the new data without taking care of the position numbers, position numbers appear twice (or multiple times).

Such behaviour might be wanted, for instance, if the reason for merging BIN/BINX files was a broken measurement. More likely, however, is that you have measured one sample over, let’s say, two carousels (\(2\times48\) positions), simply because you wanted to increase the number of aliquots. In that case, you want to treat each of the positions unique because they represent individual aliquots, and the merge function takes care of it.

You can control this behaviour by setting the parameter keep.position.number to either FALSE (the default) or TRUE. Additionally, you may have used only every 2^nd or 3^rd position on your sample carousel of the reader. It would not matter for any subsequent analysis but you may want to preserve that information. For this purpose, you can use the argument position.number.append.gap.

3.3 Subsetting of records

Subsetting or selecting particular records from BIN/BINX file is probably the most complicated part. I have seen a couple of times that users first did this with the Analyst before importing the file into R. Well, there is no need for it. One way of selecting data we have already described in Fuchs et al. (2015).

ID <- bin_data@METADATA[bin_data@METADATA$RUN == 1,"ID"]

This call would give you the record identifiers of all records with the attribute run = 1. From there, we could move on to only what we need (see Fuchs et al. 2015 for more details). When the paper was written (not when it was published), this was the way to select records. It was a little bit cumbersome and not really clean, and the way to go later, was to use the RLum objects instead (briefly below).

Because I personally stopped working with BIN/BINX files regularly, and if I would use RLum objects, it took me a while before I realised that people were still trying to select records that way. I could see the beauty. The big table is why selecting records according to their metadata in the Analyst is easy. So why not making it as easy as in the Analyst? The function here is called subset(). This function is around even without the 'Luminescence' package to subset data.frames in R. For the 'Luminescence' package, I added a new method to this function to work with the Risoe.BINfileData objects. In other words, the function subset() works like you expect it from working if you are familiar with base R and handling data.frames. Only here it takes care of the peculiarities of the Risoe.BINfileData objects.

subset(bin_data, RUN == 1)

## 
## [Risoe.BINfileData object]
## 
##  BIN/BINX version      3
##  Object date:          271020
##  User:                 Default
##  System ID:            150
##  Overall records:      108
##  Records type:         OSL   (n = 72)
##                        TL    (n = 36)
##  Position range:       1 : 36
##  Grain range:          0 : 0
##  Run range:            1 : 1
##  Set range:            3 : 6

This is essentially the same selection we did a few lines above. The only difference is that the output is again a Risoe.BINfileData. And it can be done more sophisticated. For example, we could select only records of 10 to 20 with run number > 2.

subset(bin_data, POSITION >= 10 & POSITION <= 30 & RUN > 2)

## 
## [Risoe.BINfileData object]
## 
##  BIN/BINX version      3
##  Object date:          281020, 291020
##  User:                 Default
##  System ID:            150
##  Overall records:      336
##  Records type:         IRSL  (n = 21)
##                        OSL   (n = 210)
##                        TL    (n = 105)
##  Position range:       10 : 30
##  Grain range:          0 : 0
##  Run range:            3 : 8
##  Set range:            3 : 6

This is a quick way of selecting the right curves needed for the analysis. Supported fields are all(!) column names of the METADATA slot (colnames(bin_data@METADATA)).

3.4 Changing the metadata of a record

Sometimes it is necessary to correct the data before we can process them further. A typical example would be the ltype, the type of luminescence. For instance, our imported dataset has three different curve types.

unique(bin_data@METADATA$LTYPE)

## [1] "OSL"  "TL"   "IRSL"

Let’s assume we want to treat the IRSL curves as OSL curves, and therefore we have to rename them first. We can modify them to replace all relevant entries by using base R functionality.

new_bin_data <- bin_data
new_bin_data@METADATA[new_bin_data@METADATA$LTYP == "IRSL", "LTYPE"] <- "OSL"

3.5 Changing records

Changing count values in the record works likewise. For example, to replace all values in record number 5 with the noise we could write:

## set plot panel showing 1 row and 2 columns
par(mfrow = c(1,2))

## plot records as it appears before the replacement
plot(new_bin_data@DATA[[5]], main = "before")

## replace values in record
new_bin_data@DATA[[5]] <- runif(length(new_bin_data@DATA[[5]]))

## plot record after the replacement
plot(new_bin_data@DATA[[5]], main = "after")

3.6 Plotting

It is always a good idea to look at your data before processing them. Of course, we may use standard R functions, such as plot() as shown above. Still, to have all the information about the curve type and the correct axes labelling at hand, it is easier to automatically use a function that does all of it.

## set plot panel (three rows, eight columns) 
par(mfrow = c(3,8))

## plot dataset
plot_Risoe.BINfileData(bin_data, position = 1)

This plotting function does not do much but comes with some handy arguments such as sorter, set to POSITION by default. But it can be set to any other argument to see curves in a different order. Equally interesting might be the option curve.transformation, which converts CW-OSL and CW-IRSL curves into pseudo-LM curves after suggested by Bos and Wallinga (2012).

par(mfrow = c(1,3))
plot_Risoe.BINfileData(
  bin_data,
  position = 1,
  run = 2,
  curve.transformation = "CW2pLMi"
)

The transformation happens on the fly, and of course, the function only transposes curves where such a transformation makes sense. In our case, the TL curve remains untouched.