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.
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, ...)
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.
specification of the stopping criterion. See section Details for the supported formats and how they are processed.
logical that indicates if the validity of the stopping criterion function should be checked before returning it.
maximum number of iteration to perform.
default stationarity threshold
an NMF strategy object
the current iteration
the target matrix
the current NMF model
maximum absolute value of the gradient, for the objective function to be considered stationary.
interval (in number of iterations) on which the stopping criterion is computed.
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.
number of iterations intervals over which the connectivity matrix must not change for stationarity to be achieved.
NMFStop can take the following values:
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;
the value is used to create a
stopping criterion that stops at that exact number of
iterations via nmf.stop.iteration;
the value is used to create a stopping
criterion that stops when at that stationary threshold
via nmf.stop.threshold;
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, $$