NMF: Frobenius-nmf – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

Frobenius-nmf

NMF Algorithm/Updates for Frobenius Norm

Description

The built-in NMF algorithms described here minimise the Frobenius norm (Euclidean distance) between an NMF model and a target matrix. They use the updates for the basis and coefficient matrices (W and H) defined by Lee et al. (2001).

nmf_update.lee implements in C++ an optimised version of the single update step.

Algorithms ‘lee’ and ‘.R#lee’ provide the complete NMF algorithm from Lee et al. (2001), using the C++-optimised and pure R updates nmf_update.lee and nmf_update.lee_R respectively.

Algorithm ‘Frobenius’ provides an NMF algorithm based on the C++-optimised version of the updates from Lee et al. (2001), which uses the stationarity of the objective value as a stopping criterion nmf.stop.stationary, instead of the stationarity of the connectivity matrix nmf.stop.connectivity as used by ‘lee’.

Usage

nmf_update.lee_R(i, v, x, rescale = TRUE, eps = 10^-9,
    ...)

  nmf_update.lee(i, v, x, rescale = TRUE, copy = FALSE,
    eps = 10^-9, weight = NULL, ...)

  nmfAlgorithm.lee_R(..., .stop = NULL,
    maxIter = nmf.getOption("maxIter") %||% 2000,
    rescale = TRUE, eps = 10^-9, stopconv = 40,
    check.interval = 10)

  nmfAlgorithm.lee(..., .stop = NULL,
    maxIter = nmf.getOption("maxIter") %||% 2000,
    rescale = TRUE, copy = FALSE, eps = 10^-9,
    weight = NULL, stopconv = 40, check.interval = 10)

  nmfAlgorithm.Frobenius(..., .stop = NULL,
    maxIter = nmf.getOption("maxIter") %||% 2000,
    rescale = TRUE, copy = FALSE, eps = 10^-9,
    weight = NULL, stationary.th = .Machine$double.eps,
    check.interval = 5 * check.niter, check.niter = 10L)

Arguments

`rescale`	logical that indicates if the basis matrix W should be rescaled so that its columns sum up to one.
`i`	current iteration number.
`v`	target matrix.
`x`	current NMF model, as an `NMF` object.
`eps`	small numeric value used to ensure numeric stability, by shifting up entries from zero to this fixed value.
`...`	extra arguments. These are generally not used and present only to allow other arguments from the main call to be passed to the initialisation and stopping criterion functions (slots `onInit` and `Stop` respectively).
`copy`	logical that indicates if the update should be made on the original matrix directly (`FALSE`) or on a copy (`TRUE` - default). With `copy=FALSE` the memory footprint is very small, and some speed-up may be achieved in the case of big matrices. However, greater care should be taken due the side effect. We recommend that only experienced users use `copy=TRUE`.
`.stop`	specification of a stopping criterion, that is used instead of the one associated to the NMF algorithm. It may be specified as: the access key of a registered stopping criterion; a single integer that specifies the exact number of iterations to perform, which will be honoured unless a lower value is explicitly passed in argument `maxIter`. a single numeric value that specifies the stationnarity threshold for the objective function, used in with `nmf.stop.stationary`; a function with signature `(object="NMFStrategy", i="integer", y="matrix", x="NMF", ...)`, where `object` is the `NMFStrategy` object that describes the algorithm being run, `i` is the current iteration, `y` is the target matrix and `x` is the current value of the NMF model.
`maxIter`	maximum number of iterations to perform.
`stopconv`	number of iterations intervals over which the connectivity matrix must not change for stationarity to be achieved.
`check.interval`	interval (in number of iterations) on which the stopping criterion is computed.
`stationary.th`	maximum absolute value of the gradient, for the objective function to be considered stationary.
`check.niter`	number of successive iteration used to compute the stationnary criterion.
`weight`	numeric vector of sample weights, e.g., used to normalise samples coming from multiple datasets. It must be of the same length as the number of samples/columns in `v` – and `h`.

Details

nmf_update.lee_R implements in pure R a single update step, i.e. it updates both matrices.

Author(s)

Original update definition: D D Lee and HS Seung

Port to R and optimisation in C++: Renaud Gaujoux

References

Lee DD and Seung H (2001). "Algorithms for non-negative matrix factorization." _Advances in neural information processing systems_. <URL: http://scholar.google.com/scholar?q=intitle:Algorithms+for+non-negative+matrix+factorization\#0>.

NMF

Algorithms and Framework for Nonnegative Matrix Factorization (NMF)

v0.23.0

GPL (>= 2)

Authors

Renaud Gaujoux, Cathal Seoighe

Initial release

2020-07-30