NMFStrategyIterative-class: Interface for Algorithms: Implementation for Iterative NMF...

In renozao/NMF: Algorithms and Framework for Nonnegative Matrix Factorization (NMF)

Description

This class provides a specific implementation for the generic function run – concretising the virtual interface class NMFStrategy, for NMF algorithms that conform to the following iterative schema (starred numbers indicate mandatory steps):

• 1. Initialisation

• 2*. Update the model at each iteration

• 3. Stop if some criterion is satisfied

• 4. Wrap up

This schema could possibly apply to all NMF algorithms, since these are essentially optimisation algorithms, almost all of which use iterative methods to approximate a solution of the optimisation problem. The main advantage is that it allows to implement updates and stopping criterion separately, and combine them in different ways. In particular, many NMF algorithms are based on multiplicative updates, following the approach from Lee and Seung (2001), which are specially suitable to be cast into this simple schema.

Usage

## S4 method for signature 'NMFStrategyIterative'
show(object)

## S4 method for signature 'NMFStrategyIterative,mMatrix,NMFfit'
run(
  object,
  y,
  x,
  .stop = NULL,
  maxIter = nmf.getOption("maxIter") %||% 2000L,
  ...
)

## S3 method for class 'NMFStrategyIterative'
nmfFormals(x, runtime = FALSE, ...)

Arguments

object	an object of class NMFStrategyIterative
y	the target data that we want to approximate, passed as a matrix(-like) object.
x	an NMFfit object used as a starting point/seed by the algorithm.
.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.
...	arguments that are passed to all step functions onInit, Update, Stop and onReturn.
runtime	(internal use only) single logical that indicates if arguments should be split between those passed internally and of passed down from the top call.

Slots

onInit

optional function that performs some initialisation or pre-processing on the model, before starting the iteration loop.

Update

mandatory function that implement the update step, which computes new values for the model, based on its previous value. It is called at each iteration, until the stopping criterion is met or the maximum number of iteration is achieved.

Stop

optional function that implements the stopping criterion. It is called before each Update step. If not provided, the iterations are stopped after a fixed number of updates.

onReturn

optional function that wraps up the result into an NMF object. It is called just before returning the

Methods (by generic)

• show(object = NMFStrategyIterative): Show method for objects of class NMFStrategyIterative

• run(object = NMFStrategyIterative,y = mMatrix,x = NMFfit): Runs an NMF iterative algorithm on a target matrix y.

• nmfFormals(NMFStrategyIterative): Returns the extra arguments that can be passed to the algorithm that is composed by an NMFStrategyIterative object.

  These are the union of the formal arguments of all the functional steps in the algorithm: onInit, Update, Stop, onReturn.

References

Lee DD, 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>.

renozao/NMF documentation built on June 14, 2020, 9:35 p.m.