# KL-nmf: NMF Algorithm/Updates for Kullback-Leibler Divergence In NMF: Algorithms and Framework for Nonnegative Matrix Factorization (NMF)

 nmf_update.brunet_R R Documentation

## NMF Algorithm/Updates for Kullback-Leibler Divergence

### Description

The built-in NMF algorithms described here minimise the Kullback-Leibler divergence (KL) between an NMF model and a target matrix. They use the updates for the basis and coefficient matrices (`W` and `H`) defined by Brunet et al. (2004), which are essentially those from Lee et al. (2001), with an stabilisation step that shift up all entries from zero every 10 iterations, to a very small positive value.

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

Algorithms ‘brunet’ and ‘.R#brunet’ provide the complete NMF algorithm from Brunet et al. (2004), using the C++-optimised and pure R updates `nmf_update.brunet` and `nmf_update.brunet_R` respectively.

Algorithm ‘KL’ provides an NMF algorithm based on the C++-optimised version of the updates from Brunet et al. (2004), 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 ‘brunet’.

### Usage

``````  nmf_update.brunet_R(i, v, x, eps = .Machine\$double.eps,
...)

nmf_update.brunet(i, v, x, copy = FALSE,
eps = .Machine\$double.eps, ...)

nmfAlgorithm.brunet_R(..., .stop = NULL,
maxIter = nmf.getOption("maxIter") %||% 2000,
eps = .Machine\$double.eps, stopconv = 40,
check.interval = 10)

nmfAlgorithm.brunet(..., .stop = NULL,
maxIter = nmf.getOption("maxIter") %||% 2000,
copy = FALSE, eps = .Machine\$double.eps, stopconv = 40,
check.interval = 10)

nmfAlgorithm.KL(..., .stop = NULL,
maxIter = nmf.getOption("maxIter") %||% 2000,
copy = FALSE, eps = .Machine\$double.eps,
stationary.th = .Machine\$double.eps,
check.interval = 5 * check.niter, check.niter = 10L)
``````

### Arguments

 `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.

### Details

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

### Author(s)

Original implementation in MATLAB: Jean-Philippe Brunet brunet@broad.mit.edu

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