Luminescence (version 1.1.1)

extract_IrradiationTimes: Extract Irradiation Times from an XSYG-file or RLum.Analysis object

Description

Extracts irradiation times, dose and times since last irradiation, from a Freiberg Instruments XSYG-file. These information can be further used to update an existing BINX-file.

Usage

extract_IrradiationTimes(
  object,
  file.BINX,
  recordType = c("irradiation (NA)", "IRSL (UVVIS)", "OSL (UVVIS)", "TL (UVVIS)"),
  return_same_as_input = FALSE,
  compatibility.mode = TRUE,
  txtProgressBar = TRUE
)

Value

An RLum.Results object is returned with the following structure:

.. $irr.times (data.frame)

If return_same_as_input = TRUE an RLum.Analysis or a list of it, but we updated info elements including irradiation times.

If a BINX-file path and name is set, the output will be additionally transferred into a new BINX-file (with the function name as suffix) located in the folder of the input BINX-file. Note that this will not work if the input object is a file path to an XSYG-file, instead of a link to only one file. In this case the argument input for file.BINX is ignored.

In the self call mode (input is a list of RLum.Analysis objects a list of RLum.Results is returned.

Arguments

object

character, RLum.Analysis or list (required): path and file name of the XSYG file or an RLum.Analysis produced by the function read_XSYG2R; alternatively, a list of RLum.Analysis can be provided.

Note: If an RLum.Analysis is used, any input for the arguments file.BINX and recordType will be ignored!

file.BINX

character (optional): path and file name of an existing BINX-file. If a file name is provided the file will be updated with the information from the XSYG file in the same folder as the original BINX-file.

Note: The XSYG and the BINX-file must originate from the same measurement!

recordType

character (with default): select relevant curves types from the XSYG file or RLum.Analysis object. As the XSYG-file format comprises much more information than usually needed for routine data analysis and allowed in the BINX-file format, only the relevant curves are selected by using the function get_RLum. The argument recordType works as described for this function.

Note: A wrong selection will causes a function error. Please change this argument only if you have reasons to do so.

return_same_as_input

logical (with default): if set to TRUE, an updated RLum.Analysis object (or a list of it) is returned, with each record having gained two new info element fields: IRR_TIME and TIMESCINCEIRR. This makes the RLum.Analysis object compatible with external functions that search explicitly for IRR_TIME and TIMESCINCEIRR.

compatibility.mode

logical (with default): whether all position values should be reset to a maximum value of 48 (see write_R2BIN). Only used if file.BINX is specified.

txtProgressBar

logical (with default): enable/disable the progress bar during import and export.

Function version

0.4.0

How to cite

Kreutzer, S., 2025. extract_IrradiationTimes(): Extract Irradiation Times from an XSYG-file or RLum.Analysis object. Function version 0.4.0. 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., Colombo, M., Steinbuch, L., Boer, A.d., 2025. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 1.1.1. https://r-lum.github.io/Luminescence/

Author

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

Details

The function was written to compensate missing information in the BINX-file output of Freiberg Instruments lexsyg readers. As all information are available within the XSYG-file anyway, these information can be extracted and used for further analysis or/and to stored in a new BINX-file, which can be further used by other software, e.g., Analyst (Geoff Duller).

Typical application example: g-value estimation from fading measurements using the Analyst or any other self-written script.

Beside some simple data transformation steps, the function relies on read_XSYG2R, read_BIN2R, write_R2BIN for data import and export.

Calculation details

• The value DURATION.STEP is calculated as START + the end of the time axis for all curves except for TL, where the function tries to extract meta information about the duration.

• The value END is calculated as START + DURACTION.STEP

• All curves for which no prior irradiation was detected receive an -1 (Analyst convention)

• Irradiation steps have always IRR_TIME = 0

References

Duller, G.A.T., 2015. The Analyst software package for luminescence data: overview and recent improvements. Ancient TL 33, 35-42. tools:::Rd_expr_doi("10.26034/la.atl.2015.489")

See Also

RLum.Analysis, RLum.Results, Risoe.BINfileData, read_XSYG2R, read_BIN2R, write_R2BIN

Examples

## take system file
xsyg <- system.file("extdata/XSYG_file.xsyg", package="Luminescence")

## the import is automatically
## but you can import it before
irr_times <- extract_IrradiationTimes(xsyg)
irr_times$irr.times

if (FALSE) {
# (1) - example for your own data

# set files and run function
file.XSYG <- file.choose()
file.BINX <- file.choose()

extract_IrradiationTimes(file.XSYG = file.XSYG, file.BINX = file.BINX)

# export results additionally to a CSV-file in the same directory as the XSYG-file
write.table(x = get_RLum(output),
 file = paste0(file.BINX,"_extract_IrradiationTimes.csv"),
 sep = ";",
 row.names = FALSE)
}