verify_SingleGrainData: Verify single grain data sets and check for invalid grains,...

In Luminescence: Comprehensive Luminescence Dating Data Analysis

Verify single grain data sets and check for invalid grains, i.e. zero-light level grains

Description

This function tries to identify automatically zero-light level curves (grains) from single grain data measurements.

Usage

verify_SingleGrainData(
  object,
  threshold = 10,
  cleanup = FALSE,
  cleanup_level = "aliquot",
  verbose = TRUE,
  plot = FALSE,
  ...
)

Arguments

object	Risoe.BINfileData or RLum.Analysis (required): input object. The function also accepts a list with objects of allowed type.
threshold	numeric (with default): numeric threshold value for the allowed difference between the mean and the var of the count values (see details)
cleanup	logical (with default): if set to TRUE curves identified as zero light level curves are automatically removed. Output is an object as same type as the input, i.e. either Risoe.BINfileData or RLum.Analysis
cleanup_level	character (with default): selects the level for the clean-up of the input data sets. Two options are allowed: "curve" or "aliquot": If "curve" is selected every single curve marked as invalid is removed. If "aliquot" is selected, curves of one aliquot (grain or disc) can be marked as invalid, but will not be removed. An aliquot will be only removed if all curves of this aliquot are marked as invalid.
verbose	logical (with default): enables or disables the terminal feedback
plot	logical (with default): enables or disables the graphical feedback
...	further parameters to control the plot output; if selected. Supported arguments main, ylim

Details

How does the method work?

The function compares the expected values (E(X)) and the variance (Var(X)) of the count values for each curve. Assuming that the background roughly follows a Poisson distribution the absolute difference of both values should be zero or at least around zero as

E(x) = Var(x) = \lambda

Thus the function checks for:

abs(E(x) - Var(x)) >= \Theta

With \Theta an arbitrary, user defined, threshold. Values above the threshold indicating curves comprising a signal.

Note: the absolute difference of E(X) and Var(x) instead of the ratio was chosen as both terms can become 0 which would result in 0 or Inf, if the ratio is calculated.

Value

The function returns

———————————–
⁠[ NUMERICAL OUTPUT ]⁠
———————————–

RLum.Results-object

slot:****⁠@data⁠

Element	Type	Description
⁠$unique_pairs⁠	data.frame	the unique position and grain pairs
⁠$selection_id⁠	numeric	the selection as record ID
⁠$selection_full⁠	data.frame	implemented models used in the baSAR-model core

slot:****⁠@info⁠

The original function call

Output variation

For cleanup = TRUE the same object as the input is returned, but cleaned up (invalid curves were removed). This means: Either an Risoe.BINfileData or an RLum.Analysis object is returned in such cases. An Risoe.BINfileData object can be exported to a BIN-file by using the function write_R2BIN.

Function version

0.2.3

How to cite

Kreutzer, S., 2024. verify_SingleGrainData(): Verify single grain data sets and check for invalid grains, i.e. zero-light level grains. Function version 0.2.3. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J., Mercier, N., Philippe, A., Riedesel, S., Autzen, M., Mittelstrass, D., Gray, H.J., Galharret, J., 2024. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.24. https://CRAN.R-project.org/package=Luminescence

Note

This function can work with Risoe.BINfileData objects or RLum.Analysis objects (or a list of it). However, the function is highly optimised for Risoe.BINfileData objects as it make sense to remove identify invalid grains before the conversion to an RLum.Analysis object.

The function checking for invalid curves works rather robust and it is likely that Reg0 curves within a SAR cycle are removed as well. Therefore it is strongly recommended to use the argument cleanup = TRUE carefully.

Author(s)

Sebastian Kreutzer, Institute of Geography, Heidelberg University (Germany) , RLum Developer Team

See Also

Risoe.BINfileData, RLum.Analysis, write_R2BIN, read_BIN2R

Examples

##01 - basic example I
##just show how to apply the function
data(ExampleData.XSYG, envir = environment())

##verify and get data.frame out of it
verify_SingleGrainData(OSL.SARMeasurement$Sequence.Object)$selection_full

##02 - basic example II
data(ExampleData.BINfileData, envir = environment())
id <- verify_SingleGrainData(object = CWOSL.SAR.Data,
cleanup_level = "aliquot")$selection_id

## Not run: 
##03 - advanced example I
##importing and exporting a BIN-file

##select and import file
file <- file.choose()
object <- read_BIN2R(file)

##remove invalid aliquots(!)
object <- verify_SingleGrainData(object, cleanup = TRUE)

##export to new BIN-file
write_R2BIN(object, paste0(dirname(file),"/", basename(file), "_CLEANED.BIN"))

## End(Not run)

Luminescence documentation built on June 22, 2024, 9:54 a.m.