read_gasex_file: Reading a gas exchange log file

In PhotoGEA: Photosynthetic Gas Exchange Analysis

Reading a gas exchange log file

Description

Tool for reading log files created by gas exchange measurement instruments and storing their contents in exdf objects.

Usage

  read_gasex_file(
    file_name,
    timestamp_colname = NA,
    posix_options = list(),
    file_type = 'AUTO',
    instrument_type = 'AUTO',
    standardize_columns = TRUE,
    ...
  )

Arguments

file_name	A relative or absolute path to a log file containing gas exchange data.
timestamp_colname	The name of the column that contains the timestamp of each measurement; typically, this is something like 'time' or 'TIMESTAMP'.
posix_options	Optional arguments to pass to as.POSIXlt; must be formatted as a list of named elements. See details below for more information.
file_type	The type of file to be loaded. If file_type is 'AUTO', then the file type will be automatically determined from the extension of file_name. The other supported options are 'plaintext', 'Excel', and 'data'.
instrument_type	The type of measurement instrument that produced the log file. If instrument_type is 'AUTO', then the instrument type will be determined from the file_type. The other supported options are 'Licor LI-6800' and 'CR3000'.
standardize_columns	A logical value indicating whether to standardize columns; see details below.
...	Additional arguments to be passed to specialized reading functions; see below for more details.

Details

Some log files contain Unicode characters in some column names and units, but these characters cannot be represented properly in R. To address this, Unicode characters are replaced with reasonable alternatives; for example, the character for the capital Greek letter delta is replaced with the word Delta. The replacement rules are stored in a data frame that can be accessed via PhotoGEA:::UNICODE_REPLACEMENTS, and more information can be found in the source code (R/unicode_replacements.R).

Sometimes it is useful to "standardize" the names, units, or categories of columns in instrument log files. This can be helpful in several situations:

• An instrument may not be consistent with the name of a column; for example, Licor LI-6800s may may have a PhiPs2 or PhiPS2 column depending on the version of the operating system running on the machine.

• An instrument may not specify the units of a column; for example, Licor LI-6800s do not specify that PhiPS2 has units of dimensionless.

• An instrument may use different names or different units than another instrument for the same measured quantity.

To deal with these situations, it is possible to "standardize" the column names, units, and categories when reading an instrument file. A list of definitions for all standardizations can be accessed from an R session by typing View(PhotoGEA:::gasex_column_conversions).

When reading a log file, it can be useful to identify the timestamp column so its values can be properly interpreted as POSIXlt objects. If timestamp_colname is NA, this conversion will be skipped. By default, read_gasex_file calls as.POSIXlt with origin = '1970-01-01' and tz = ''. With these options, any numeric timestamps (such as 1692386305.5) will be interpreted as the number of seconds since January 1, 1970 (the UNIX standard) and the time will be expressed using the local system time. This works well in many situations. However, if a log file was created in a different time zone than the local one, it may be necessary to specify the time zone. This can be done via the posix_options argument. For example, to interpret the timestamp as a time in US Central time, set posix_options = list(tz = 'US/Central'). This may be necessary when using pair_gasex_and_tdl to match timestamps between different log files.

When automatically determining the file type from its extension, the following rules are used:

• A .xlsx extension corresponds to file_type = 'Excel'.

• A .dat extension corresponds to file_type = 'data'.

• A file with no extension corresponds to file_type = 'plaintext'.

When automatically determining the instrument type from the file type, the following rules are used:

• File types of 'Excel' and 'plaintext' correspond to instrument_type = 'Licor LI-6800'.

• A file type of 'data' corresponds to instrument_type = 'CR3000'.

Internally, this function calls one of several other (non-exported) functions depending on the values of instrument_type and file_type:

• read_licor_6800_plaintext (for instrument_type = 'LI-6800' and file_type = 'plaintext')

• read_licor_6800_Excel (for instrument_type = 'LI-6800' and file_type = 'Excel')

• read_cr3000 (for instrument_type = 'CR3000' and file_type = 'data')

Any additional arguments specified via ... will be passed to these functions.

IMPORTANT NOTE ABOUT LICOR EXCEL FILES: by default, Licor Excel files do not "calculate" formula values. This causes a problem when reading them in R, since any data entry determined from a formula will be read as 0. To fix this issue for a Licor Excel file, open it in in Excel, go to the Formulas menu, and choose Calculate Now. (Alternatively, press F9.) Then save the file and close it. See read_licor_6800_Excel for more details.

Value

An exdf object that fully includes all the data from the log file. In addition to the required elements of an exdf object, the following "extra" elements are also included:

• file_name: A copy of the input argument with the same name.

• instrument_type: A copy of the input argument with the same name.

• file_type: A copy of the input argument with the same name, unless it was set to 'AUTO'; in that case, the file type that was determined from the file's extension.

• timestamp_colname: A copy of the input argument with the same name, unless it was set to 'AUTO'; in that case, the instrument type that was determined from the file type.

Examples

# Example: Eeading a Licor Excel file that is included with the PhotoGEA
# package. Here we specify 'time' as the name of the timestamp column.
licor_file <- read_gasex_file(
  PhotoGEA_example_file_path('ball_berry_1.xlsx'),
  'time'
)

licor_file$file_name     # A record of where the data came from
str(licor_file)          # View the contents of the exdf object's main_data
str(licor_file$preamble) # View the Licor file's preamble data

PhotoGEA documentation built on April 11, 2025, 5:48 p.m.