read_gasex_file {PhotoGEA}R Documentation

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,
    remove_NA_rows = 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.

remove_NA_rows

A logical value indicating whether to remove any rows whose values are all NA; this argument will be passed to the specialized reading functions; see below for more details.

...

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:

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:

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

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

Any additional arguments specified via ... will be passed to these functions, along with the value of remove_NA_rows.

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:

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

[Package PhotoGEA version 1.3.3 Index]