feemparafac: Compute PARAFAC on a FEEM cube object and access the results
In albatross: PARAFAC Analysis of Fluorescence Excitation-Emission Matrices

feemparafac

R Documentation

Compute PARAFAC on a FEEM cube object and access the results

Description

feemparafac forwards its arguments to parafac from the multiway package, optionally rescales the result and attaches a few attributes. Resulting objects of class feemparafac can be accessed using methods presented below.

Usage

  feemparafac(
    X, ..., const = rep('nonneg', 3), ctol = 1e-6,
    rescale = 3, retries = 10, subset = TRUE, envir = NULL
  )
  ## S3 method for class 'feemparafac'
plot(x, type = c("image", "lines"), ...)
  ## S3 method for class 'feemparafac'
coef(
    object, type = c(
      "all", "scores", "loadings", "surfaces",
      "emission", "excitation", "samples"
    ), ...
  )
  ## S3 method for class 'feemparafac'
fitted(object, ...)
  ## S3 method for class 'feemparafac'
residuals(object, ...)
  ## S3 method for class 'feemparafac'
reorder(x, neworder, like, ...)
  ## S3 method for class 'feemparafac'
rescale(x, mode, newscale, absorb, like, ...)

Arguments

`X`	A FEEM cube object. The per-sample factors will be multiplied by `attr(X, 'scales')` stored in it. If `envir` is `NULL` (by default), this should be just a value. If `envir` is given, this should be a name of the value to `get` from the environment.
`...`	feemparafac Passed as-is to `parafac`. plot.feemparafac Passed as-is to lattice functions `levelplot` and `xyplot`. reorder.feemparafac, rescale.feemparafac Forwarded to the respective multiway functions. coef.feemparafac, fitted.feemparafac, residuals.feemparafac No other parameters are allowed.
`const`	A character vector of length 3 specifying the constraints for all modes of `X`, passed to `parafac`. Defaults to non-negativity. See `const` for more information.
`ctol`	The stopping criterion used by `parafac`. When a step results in an absolute change in 3{R^2

R^2R2 below ctol, the algorithm stops.

Details

feemparafac tries hard to guarantee the convergence flag to be 0 (normal convergence) or 1 (iteration number limit reached), but never 2 (a problem with the constraints). A fatal error is raised if repeated runs of parafac do not return a (semi-)successfully fitted model.

After the PARAFAC decomposition is calculated, the scores are multiplied by the scales attribute of the X object, making them represent the cube with scaling undone. Use feemscale(remember = FALSE) if you don't want to undo the scaling.

The output option is fixed to "best" value. Obtaining a list of alternative solutions can therefore be achieved by running:

replicate(n, feemparafac(..., nstart = 1), simplify = FALSE)

The subset and envir options are useful to repeatedly perform PARAFAC on different subsets of the same FEEM cube, e.g. in jack-knifing or split-half analysis. Since feemparafac keeps a reference to the its X and envir arguments, the use of subset should ensure that the same FEEM cube is referenced from multiple feemparafac objects instead of creating copies of its subsets. Additionally, environment objects are not duplicated on save or load, so storing X in an environment and passing it to multiple invocations of feemparafac will save a lot of memory when the results are serialised together.

plot.feemparafac provides sane defaults for lattice options such as xlab, ylab, as.table, auto.key, type, cuts, col.regions, but they can be overridden.

Value

`feemparafac`	An object of classes `feemparafac` and `parafac` with the following attributes added: cube A copy of the `X` argument. subset A copy of the `subset` argument. envir A copy of the `envir` argument. time The time it took to compute the decomposition as an object of class `proc_time`. Only the time taken to run `multiway::parafac` (including the retries, if the decomposition failed) is included. The time taken to rescale the scores should be negligible. `rownames` are added from the original data cube to the `A`, `B`, `C` components of the list returned by `parafac`. Use `feemcube` on the return value to access the original data cube.
`plot.feemparafac`	A lattice plot object. Its `print` or `plot` method will draw the plot on an appropriate plotting device.
`coef.feemparafac`	A `data.frame` or a list of them (only if `type` is “all”). See the description of the `type` argument for more information.
`fitted.feemparafac`	A `feemcube` object comparable to `X` as it was decomposed by `parafac`, ignoring the scaling.
`resid.feemparafac`	A `feemcube` object equal to 3{ \mathbf{X} - \hat{\mathbf{X}}

X - fitted(X)X - X̂, with an additional class feem.resid set. Objects of this class are plotted with a different default palette, see plot.feem.resid.

References

\reference

Bro1997

Examples

  data(feems)
  cube <- feemscale(feemscatter(cube, c(24, 14)), na.rm = TRUE)
  (factors <- feemparafac(cube, nfac = 3, ctol = 1e-4))
  plot(factors, 'image')
  plot(factors, 'line')
  head(coef(factors, 'loadings'))
  str(coef(factors, 'all'))
  str(feemcube(factors)) # original cube is retained
  plot(fitted(factors))
  plot(resid(factors))

albatross documentation built on May 29, 2024, 9:10 a.m.