feem {albatross}

Create a fluorescence excitation-emission matrix object

Description

Functions to create fluorescence excitation-emission matrix objects from R matrices coupled with excitation and emission wavelengths, three-column data.frames containing (\lambda_\mathrm{em}, \lambda_\mathrm{ex}, I) tuples or files.

Usage

  feem(x, ...)
  ## S3 method for class 'matrix'
feem(x, emission, excitation, scale = 1, ...)
  ## S3 method for class 'data.frame'
feem(
    x, scale = 1, emission = 'emission',
    excitation = 'excitation', intensity = 'intensity', ...
  )
  ## S3 method for class 'character'
feem(x, format, ...)
  ## S3 method for class 'connection'
feem(x, format, ...)

Arguments

x

The source of the information to create a FEEM object from: a matrix, a three-column data.frame, a file path as a single string, or a connection.

If converting a matrix, its rows should correspond to different fluorescence emission wavelengths specified in the emission argument; conversely, its columns should correspond to excitation wavelengths specified in the excitation argument.

If converting a data.frame, it should have exactly three columns containing emission wavelengths, excitation wavelength, and intensity values. The names of the columns are expected to be “emission”, “excitation”, and “intensity”, respectively, but can be overridden using namesake arguments.

If reading a single file by file path or connection, the format argument must specify the kind of file to parse, see below.

emission

If converting a matrix, this should be a vector of emission wavelengths, each wavelength corresponding to a row of the matrix.

If converting a data.frame, this optional argument specifies the name of the column containing the emission wavelengths.

excitation

If converting a matrix, this should be a vector of excitation wavelengths, each wavelength corresponding to a column of the matrix.

If converting a data.frame, this optional argument specifies the name of the column containing the excitation wavelengths.

intensity

If converting a data.frame, this optional argument specifies the name of the column containing the fluorescence intensities.

scale

The scale value of a EEM is preserved through the analysis procedure to divide the resulting score values after running PARAFAC. If the EEM has been pre-multiplied prior to creating the FEEM object, you can set the multiplier here.

format

table

The FEEM is assumed to be stored as a plain text matrix, readable using read.table, with the first column and the first row containing wavelengths. For example, it is possible to import CSV files obtained from a HORIBA Aqualog® fluorometer by using feem(file, 'table', sep = ',').

Rows are assumed to correspond to emission wavelengths, columns are assumed to correspond to excitation wavelengths; if that's not the case, set the transpose argument to TRUE.

If there are unmeasured points in the spectrum (e.g. the anti-Stokes area) encoded as special numbers (e.g. stored as zeroes or -100), specify their values as the na argument (numeric vector). The function will check for triangles filled with these values (such that a threshold \Delta exists where for all \lambda_\mathrm{em} - \lambda_\mathrm{ex} > \Delta or \lambda_\mathrm{em} - \lambda_\mathrm{ex} < \Delta , X(\lambda_\mathrm{em}, \lambda_\mathrm{ex}) \in \mathtt{na} ) and replace them with NAs. If the unmeasured values are not stored as numbers, use the na.strings argument of read.table to specify them.

The fileEncoding argument is treated specially (but preserving the read.table semantics regarding numbers), preventing errors in case the session charset cannot represent all characters from the file: the contents are first converted to UTF-8, then forwarded to read.table. This only works when file is a file path, not a connection. (When passing a connection with an encoding attribute set, make sure that the file contents after decoding can be represented in the session charset.)

The dec argument is also treated specially, making it possible to read a column containing both numbers (with a decimal comma) and strings and then convert them to numbers (transforming the strings into NA_real_).

All other arguments are passed to read.table, with fill defaulting to TRUE instead of FALSE.

panorama

Read a ‘.dat’ file as created by “Panorama” software that comes with FLUORAT®-02-PANORAMA fluorometer. Such files contain a header describing the wavelength range, e.g.:

   240.0   650.0     1.0    ; Emission(columns)
   230.0   320.0     5.0    ; Excitation(rows)

The header is followed by the intensity data as matrix, whitespace-separated. Missing points (anti-Stokes area) stored as 0 or 100 and are automatically filtered out on import. No additional parameters are accepted.

F900txt

Read an emission map text file created by “F900” software that comes with Edinburgh Instruments fluorescence spectrometers. Separated by empty lines, these files are assumed to contain:

1. Sample name

2. Metadata of each emission scan, with names in the first column, including the excitation wavelengths

3. Fluorescence values with emission wavelengths in the first column

The fileEncoding argument specifies the encoding of the text file and has a safe default of “latin1”. It should typically correspond to the ANSI code page on the computer running F900 that was used to create the file. See iconvlist() for a list of encodings understood by R.

The sep argument specifies the column separator used in the file. A semicolon ; is typically used, though other options are possible.

...

When converting matrices and data.frames, extra arguments besides those specified above are not allowed.

When reading the FEEM from a file, additional arguments may be passed to format-specific reading functions, see above.

Details

Transposing a feem object using t will remove the class attribute, returning an ordinary matrix.

Value

A FEEM object is a matrix with the following attributes added:

emission

Fluorescence emission wavelengths corresponding to the rows of the matrix, nm.

excitation

Fluorescence excitation wavelengths corresponding to the columns of the matrix, nm.

dimnames

Dimension names, copies of information above. Used only for presentation purposes.

scale

Scale factor, preserved through the analysis, which may be used later to undo the scaling. Initially 1.

See Also

FEEM methods: plot.feem, as.data.frame.feem, [.feem, feemgrid, feemife, feemscale, feemscatter.

Examples

  feem(matrix(1:40, ncol = 8), 1:5, 1:8)
  feem(
    data.frame(x = 1:10, y = 21:30, z = 31:40),
    emission = 'x', excitation = 'y', intensity = 'z'
  )
  feem(
    system.file('extdata/ho_aq.csv', package = 'albatross'),
    'table', sep = ','
  )
  feem(
    system.file('extdata/F900.txt', package = 'albatross'), 'F900txt'
  )