NMFStop {NMF} | R Documentation

## 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 α (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.

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

| [max( D(i- N_s + 1), ..., D(i) ) - min( D(i- N_s + 1), ..., D(i) )] / n | <= alpha

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

[Package NMF version 0.20.6 Index]