feemflame {albatross}

Fluorescence and scAttering Model Estimation

Description

Given a FEEM cube, model the fluorescence and the scattering signals at the same time as a sum of a PARAFAC model and a low-rank unfolded matrix factorisation.

Usage

  feemflame(
    X, ffac, sfac, maxiter = 32, widths = rep(25, 4), Raman.shift = 3400,
    ctol = 1e-04, progress = TRUE, control.parafac, control.cmf
  )
  ## S3 method for class 'feemflame'
fitted(object, ...)
  ## S3 method for class 'feemflame'
residuals(object, ...)
  ## S3 method for class 'feemflame'
coef(
    object, type = c(
      "fluorescence",
      "scores", "loadings", "emission", "excitation", "samples",
      "scattering", "sc.scores", "sc.loadings"
    ), ...
  )
  ## S3 method for class 'feemflame'
plot(
    x, type = c('both', 'fl.image', 'fl.lines'), ...
  )

Arguments

X

A feemcube object.

ffac

The number of trilinear components used to model fluorescence, passed to feemparafac.

sfac

The number of bilinear (low-rank matrix factorisation) components used to model the scattering signal.

maxiter

Maximum number of alternating PARAFAC and constrained matrix factorisation iterations.

widths

Widths of the scattering regions, like in feemscatter: A numeric vector of length 4 containing the widths (in nm) of the scattering signal, in the following order:

1. Rayleigh scattering

2. Raman scattering

3. Rayleigh scattering, 2\lambda

4. Raman scattering, 2\lambda

Raman.shift

Raman shift of the scattering signal, in \textrm{cm}^{-1}, like in feemscatter.

ctol

Given L = ||\mathbf X - \hat{\mathbf X}||^2 , stop when \frac{|\Delta L|}{L} \le \mathtt{ctol} .

progress

Print progress information on the console, including the iteration number, relative sum of squared residuals, and relative change in sum of squared residuals.

control.parafac, control.cmf

Named lists of additional arguments to be passed to the underlying functions. Both default to list(ctol = 1e-4, maxit = 10), which makes both steps to run for 10 iterations or stop when the absolute change in R^2 is less than 10^{-4}, whichever happens sooner.

object, x

A feemflame object.

type

coef

Determines the type of coefficients to return:

fluorescence

Equivalent to calling coef.feemparafac on the fluorescence model (default).

scores, loadings, emission, excitation, samples

Equivalent to calling coef.feemparafac on the fluorescence model and passing the respective type argument.

sc.scores

A data.frame containing the following columns:

sample

Sample numbers or names.

value

Scattering intensity value for a given factor.

factor

The number of the scattering component.

sc.loadings

A data.frame containing the following columns:

emission, excitation

The wavelengths corresponding to the value of the scattering profile.

value

Scattering intensity value for a given factor.

factor

The number of the scattering component.

scattering

A list with names “scores” and “loadings” containing results of coef(object, 'sc.scores') and coef(object, 'sc.loadings'), respectively.

plot

Describes the kind of plot to produce:

both

Plot the loadings of the fluorescence and scattering models as false colour images.

fl.image, fl.lines

Equivalent to calling plot.feemparafac on the fluorescence model with the argument “image” or “lines”, respectively.

...

No other parameters are allowed.

Details

FLAME models the input data as a sum of fluorescence signal (PARAFAC model) and scattering signal (low rank model):

X_k(\lambda^\mathrm{em}_i, \lambda^\mathrm{ex}_j) = \underbrace{\sum_p A_{i,p} B_{j,p} C_{k,p}}_{\mbox{fluorescence}} + \underbrace{\sum_q S_{i,j,q} D_{k,q}}_{\mbox{scattering}}

The function alternates between fitting the PARAFAC model on the dataset with scattering signal subtracted and fitting the low-rank model on the dataset with fluorescence signal subtracted. The PARAFAC model is fitted using the feemparafac function. The low-rank model is fitted by means of unfolding the wavelength dimensions into one, resulting in a matrix, followed by the same alternating least squares procedure as done in multivariate curve resolution. Both models are constrained to result in non-negative factors.

The low-rank model is additionally constrained to zero outside the scattering region. The scattering region is defined the same way as in feemscatter, using the widths and the Raman.shift arguments.

Initial PARAFAC model is fitted with the scattering region set to missing. The low-rank model is initialised with truncated singular value decomposition forced to be non-negative.

Value

feemflame

An object of class feemflame, which is a list containing the following components:

fl

A feemparafac object containing the fluorescence part of the model.

sc

An object of internal class cmf. Please don't rely on its structure.

fitted.feemflame

A feemcube object containing the part of X fitted by the model.

residuals.feemparafac

A feemcube object equal to \mathbf{X} - \hat{\mathbf{X}} , with an extra class feem.resid set. Objects of this class are plotted with a different default palette, see plot.feem.resid.

coef.feemflame

See the description of the type argument.

Note

The structure of the feemflame object, the initialisation, and the constraints may be subject to change in a future version.

References

Tauler R, Marqués I, Casassas E (1998). “Multivariate curve resolution applied to three-way trilinear data: Study of a spectrofluorimetric acid-base titration of salicylic acid at three excitation wavelengths.” Journal of Chemometrics, 12(1), 55-75. doi:10.1002/(SICI)1099-128X(199801/02)12:1<55::AID-CEM501>3.0.CO;2-#.

Krylov I, Labutin T, Rinnan Å, Bro R (2021). “Modelling of scattering signal for direct PARAFAC decompositions of excitation-emission matrices.” 17th Scandinavian Symposium on Chemometrics. https://web.archive.org/web/20220314144225/https://ssc17.org/abstract/Krylov1.html. https://files.libs.chem.msu.ru/~ivan/SSC17/P13.pdf.

See Also

feemparafac, feemcube

Examples

  data(feems)
  cube <- feemscale(cube)
  factors <- feemflame(cube, ffac = 3, sfac = 1)
  str(coef(factors))
  str(coef(factors, 'scattering'))
  plot(factors)