NMF (version 0.20.6)

NMFStop: Stopping Criteria for NMF Iterative Strategies

Description

The function documented here implement stopping/convergence criteria commonly used in NMF algorithms.

NMFStop acts as a factory method that creates stopping criterion functions from different types of values, which are subsequently used by NMFStrategyIterative objects to determine when to stop their iterative process.

nmf.stop.iteration generates a function that implements the stopping criterion that limits the number of iterations to a maximum of n), i.e. that returns TRUE if i>=n, FALSE otherwise.

nmf.stop.threshold generates a function that implements the stopping criterion that stops when a given stationarity threshold is achieved by successive iterations. The returned function is identical to nmf.stop.stationary, but with the default threshold set to threshold.

More precisely, the objective function is computed over $n$ successive iterations (specified in argument check.niter), every check.interval iterations. The criterion stops when the absolute difference between the maximum and the minimum objective values over these iterations is lower than a given threshold $\alpha$ (specified in stationary.th):

nmf.stop.connectivity implements the stopping criterion that is based on the stationarity of the connectivity matrix.

Usage

NMFStop(s, check = TRUE)
  nmf.stop.iteration(n)
  nmf.stop.threshold(threshold)
  nmf.stop.stationary(object, i, y, x, stationary.th = .Machine$double.eps, check.interval = 5 * check.niter, check.niter = 10L, ...)
  nmf.stop.connectivity(object, i, y, x, stopconv = 40, check.interval = 10, ...)

Arguments

s

specification of the stopping criterion. See section Details for the supported formats and how they are processed.

check

logical that indicates if the validity of the stopping criterion function should be checked before returning it.

n

maximum number of iteration to perform.

threshold

default stationarity threshold

object

an NMF strategy object

i

the current iteration

y

the target matrix

x

the current NMF model

stationary.th

maximum absolute value of the gradient, for the objective function to be considered stationary.

check.interval

interval (in number of iterations) on which the stopping criterion is computed.

check.niter

number of successive iteration used to compute the stationnary criterion.

...

extra arguments passed to the function objective, which computes the objective value between x and y.

stopconv

number of iterations intervals over which the connectivity matrix must not change for stationarity to be achieved.

Value

a function that can be passed to argument .stop of function nmf, which is typically used when the algorith is implemented as an iterative strategy.a function that can be used as a stopping criterion for NMF algorithms defined as NMFStrategyIterative objects. That is a function with arguments (strategy, i, target, data, ...) that returns TRUE if the stopping criterion is satisfied -- which in turn stops the iterative process, and FALSE otherwise.

Details

NMFStop can take the following values:

function

is returned unchanged, except when it has no arguments, in which case it assumed to be a generator, which is immediately called and should return a function that implements the actual stopping criterion;

integer

the value is used to create a stopping criterion that stops at that exact number of iterations via nmf.stop.iteration;

numeric

the value is used to create a stopping criterion that stops when at that stationary threshold via nmf.stop.threshold;

character

must be a single string which must be an access key for registered criteria (currently available: “connectivity” and “stationary”), or the name of a function in the global environment or the namespace of the loading package.

$$ \left| \frac{\max_{i- N_s + 1 \leq k \leq i} D_k - \min_{i - N_s +1 \leq k \leq i} D_k}{n} \right| \leq \alpha, $$