Learn R Programming
Luminescence (version 1.1.2)

read_XSYG2R: Import XSYG files into R

Description

Imports XSYG-files produced by a Freiberg Instruments lexsyg reader into R.

Usage

read_XSYG2R(
  file,
  recalculate.TL.curves = TRUE,
  n_records = NULL,
  fastForward = FALSE,
  import = TRUE,
  pattern = "\\.xsyg",
  auto_linearity_correction = FALSE,
  verbose = TRUE,
  txtProgressBar = TRUE
)

Value

Using the option import = FALSE

A list consisting of two elements is shown:

  • data.frame with information on file.

  • data.frame with information on the sequences stored in the XSYG file.

Using the option import = TRUE (default)

A list is provided, the list elements contain:

Sequence.Header

data.frame with information on the sequence.

Sequence.Object

RLum.Analysis containing the curves.

Arguments

file

character or list (required): path and file name of the XSYG file. If input is a list it should comprise only characters representing each valid path and XSYG-file names. Alternatively, the input character can be just a directory (path), in which case the function tries to detect and import all XSYG-files found in the directory.

recalculate.TL.curves

logical (with default): if set to TRUE, TL curves are returned as temperature against count values (see details for more information) Note: The option overwrites the time vs. count TL curve. Select FALSE to import the raw data delivered by the lexsyg. Works for TL curves and spectra.

n_records

numeric (with default): number of records to be imported; by default the function attempts to import all records.

fastForward

logical (with default): if TRUE for a more efficient data processing only a list of RLum.Analysis objects is returned.

import

logical (with default): if set to FALSE, only the XSYG file structure is shown.

pattern

character (with default): regular expression pattern passed to list.files to construct a list of files to read (used only when a path is provided).

auto_linearity_correction

logical (with default): enable/disable automatic count linearity correction. Because the information on the detectors are not consistent and are not consistently stored, this option should be used with caution.

verbose

logical (with default): enable/disable output to the terminal.

txtProgressBar

logical (with default): enable/disable the progress bar during import. Ignored if verbose = FALSE.

Function version

0.7.1

How to cite

Kreutzer, S., Colombo, M., 2025. read_XSYG2R(): Import XSYG files into R. Function version 0.7.1. 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.2. https://r-lum.github.io/Luminescence/

Author

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

Details

How does the import function work?

The function uses the 'XML' package to parse the file structure. Each sequence is subsequently translated into an RLum.Analysis object.

General structure XSYG format

<?xml?>
<Sample>
  <Sequence>
    <Record>
      <Curve name="first curve" />
      <Curve name="curve with data">x0 , y0 ; x1 , y1 ; x2 , y2 ; x3 , y3</Curve>
    </Record>
  </Sequence>
</Sample>

So far, each XSYG file can only contain one <Sample></Sample>, but multiple sequences.

Each record may comprise several curves.

TL curve recalculation

On the FI lexsyg device TL curves are recorded as time against count values. Temperature values are monitored on the heating plate and stored in a separate curve (time vs. temperature). If the option recalculate.TL.curves = TRUE is chosen, the time values for each TL curve are replaced by temperature values.

Practically, this means combining two matrices (Time vs. Counts and Time vs. Temperature) with different row numbers by their time values. Three cases are considered:

  1. HE: Heating element

  2. PMT: Photomultiplier tube

  3. Interpolation is done using the function approx

CASE (1): nrow(matrix(PMT)) > nrow(matrix(HE))

Missing temperature values from the heating element are calculated using time values from the PMT measurement.

CASE (2): nrow(matrix(PMT)) < nrow(matrix(HE))

Missing count values from the PMT are calculated using time values from the heating element measurement.

CASE (3): nrow(matrix(PMT)) == nrow(matrix(HE))

A new matrix is produced using temperature values from the heating element and count values from the PMT.

Note: Please note that due to the recalculation of the temperature values based on values delivered by the heating element, it may happen that multiple count values exists for each temperature value and temperature values may also decrease during heating, not only increase.

Count linearity correction

If the argument auto_linearity_correction = TRUE, the function offers a, theoretically, automated linearity correction of the PMT signal using the internal function correct_PMTLinearity. The critical parameter is the count-pair resolution, which is provided to the function automatically depending on the detector. Currently, the following settings are used:

DETECTORCOUNT-PAIR-RESOLUTION
UVVIS18 ns
NIR5070 ns
NIR4070 ns
ETPMT25 ns

Unfortunately, not all XSYG files provide correct information on the used detector, depending on software version. Hence, in case of doubt, please verify the settings and conduct a manual correction if required.

Advanced file import

To allow for a more efficient usage of the function, instead of single path to a file just a directory can be passed as input. In this particular case the function tries to extract all XSYG-files found in the directory and import them all. Using this option internally the function constructs as list of the XSYG-files found in the directory. Please note no recursive detection is supported as this may lead to endless loops.

References

Grehl, S., Kreutzer, S., Hoehne, M., 2013. Documentation of the XSYG file format. Unpublished Technical Note. Freiberg, Germany

Further reading

XML: https://en.wikipedia.org/wiki/XML

See Also

'XML', RLum.Analysis, RLum.Data.Curve, approx, correct_PMTLinearity

Examples

Run this code

##(1) import XSYG file to R (uncomment for usage)

#FILE <- file.choose()
#temp <- read_XSYG2R(FILE)

##(2) additional examples for pure XML import using the package XML
##    (uncomment for usage)

  ##import entire XML file
  #FILE <- file.choose()
  #temp <- XML::xmlRoot(XML::xmlTreeParse(FILE))

  ##search for specific subnodes with curves containing 'OSL'
  #getNodeSet(temp, "//Sample/Sequence/Record[@recordType = 'OSL']/Curve")

##(2) How to extract single curves ... after import
data(ExampleData.XSYG, envir = environment())

##grep one OSL curves and plot the first curve
OSLcurve <- get_RLum(OSL.SARMeasurement$Sequence.Object, recordType="OSL")[[1]]

##(3) How to see the structure of an object?
structure_RLum(OSL.SARMeasurement$Sequence.Object)

Run the code above in your browser using DataLab