feemparafac {albatross}

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 R^2 below ctol, the algorithm stops.

rescale

Rescale the resulting factors to leave all the variance in the given mode: emission, excitation, or sample (default). Set to NA to disable.

retries

Retry for given number of tries until parafac returns a successfully fitted model or stops due to the iteration number limit. Raise a fatal error if all tries were unsuccessful.

subset

An integer or logical vector choosing the samples from X, as in feemparafac(X[,,subset], ...). Defaults to the whole cube.

envir

An environment to look up X in.

x, object

An object returned by feemparafac.

type

Given a fitted PARAFAC model:

X_{i,j,k} = \sum_r A_{i,r} B_{j,r} C_{k,r}

With \mathbf{A} corresponding to fluorescence emission loadings, \mathbf{B} corresponding to fluorescence excitation loadings, and \mathbf{C} corresponding to the scores of the components in different samples, the following plots can be produced:

image

Plot the factors (“loadings”) as a series of pseudo-colour images of outer products \mathbf{a}_r \times \mathbf{b}_r^\top

lines

Plot the factors \mathbf a_r and \mathbf b_r as functions of wavelengths, with each pair of factors on a different panel.

Fitted PARAFAC coefficients can be returned in the following forms:

emission, excitation, samples

Return the contents of \mathbf{A}, \mathbf{B} or \mathbf{C}, respectively, as a data.frame with three columns, the first one (named wavelength or sample) containing the independent variable (\lambda_\mathrm{em} / \lambda_\mathrm{ex} / sample name or number), the second one (named value) containing the values and the third one (named factor) containing the factor numbers.

scores

Same as samples.

loadings

Same as “emission” and “excitation” combined using rbind, with a fourth column (mode) added, naming the kinds of loadings.

all

A list with names “emission”, “excitation”, “samples” containing results of coef(object, "emission"), coef(object, "excitation"), coef(object, "samples"), respectively.

surfaces

A data.frame containing the columns emission, excitation (containing the wavelengths), intensity (containing the values of the outer product \mathbf{a}_r \times \mathbf{b}_r^\top ), and factor (containing the factor numbers r).

neworder

A permutation of integers between 1 and ncol(x$A) (the number of components) specifying the new order of factors. Forwarded to reorder.parafac. Incompatible with the like argument.

like

A feemparafac object.

In reorder, the factors in x will be reordered to match the factors in like according to the smallest of the cosine similarities (congru) for the emission and excitation wavelengths.

In rescale, every factor matrix \mathbf{A} from x that was specified in mode will be multiplied by scaling factors \mathbf{c} so in order to minimise \| \mathbf{A}_\mathtt{like} - \mathrm{diag}(\mathbf c) \mathbf{A}_\mathtt{x} \|^2 .

mode

The modes to rescale, with "A", "B", "C" corresponding to emission, excitation, and samples, respectively. When like is specified, defaults to c("A", "B"). Forwarded to rescale.parafac.

newscale

The desired root-mean-square for each column of the modes being rescaled. Forwarded to rescale.parafac. Incompatible with the like argument.

absorb

The mode that should absorb the inverse rescaling coefficients. When like is specified, defaults to "C". Forwarded to rescale.parafac.

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 \mathbf{X} - \hat{\mathbf{X}} , with an additional class feem.resid set. Objects of this class are plotted with a different default palette, see plot.feem.resid.

References

Bro R (1997). “PARAFAC. Tutorial and applications.” Chemometrics and Intelligent Laboratory Systems, 38(2), 149-171. doi:10.1016/S0169-7439(97)00032-4.

See Also

The parafac class structure; write.openfluor, feemcube for methods specific to values returned from this function.

The rescale generic is re-exported from the multiway package.

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))