Distances and Objective Functions


The NMF package defines methods for the generic deviance from the package stats, to compute approximation errors between NMF models and matrices, using a variety of objective functions.

nmfDistance returns a function that computes the distance between an NMF model and a compatible matrix.


deviance(object, ...)

S4 (NMF)
`deviance`(object, y, method = c("", "KL", "euclidean"), ...)

nmfDistance(method = c("", "KL", "euclidean"))

S4 (NMFfit)
`deviance`(object, y, method, ...)

S4 (NMFStrategy)
`deviance`(object, x, y, ...)


a matrix compatible with the NMF model object, i.e. y must have the same dimension as fitted(object).
a character string or a function with signature (x="NMF", y="matrix", ...) that implements a distance measure between an NMF model x and a target matrix y, i.e. an objective function to use to compute the deviance. In deviance, it is passed to nmfDistance to get the function that effectively computes the deviance.
extra parameters passed to the objective function.
an NMF model that estimates y.
an object for which the deviance is desired.


deviance returns a nonnegative numerical value

nmfDistance returns a function with least two arguments: an NMF model and a matrix.


  1. deviancesignature(object = "NMF"): Computes the distance between a matrix and the estimate of an NMF model.

  2. deviancesignature(object = "NMFfit"): Returns the deviance of a fitted NMF model.

    This method returns the final residual value if the target matrix y is not supplied, or the approximation error between the fitted NMF model stored in object and y. In this case, the computation is performed using the objective function method if not missing, or the objective of the algorithm that fitted the model (stored in slot 'distance').

    If not computed by the NMF algorithm itself, the value is automatically computed at the end of the fitting process by the function nmf, using the objective function associated with the NMF algorithm, so that it should always be available.

  3. deviancesignature(object = "NMFfitX"): Returns the deviance achieved by the best fit object, i.e. the lowest deviance achieved across all NMF runs.

  4. deviancesignature(object = "NMFStrategy"): Computes the value of the objective function between the estimate x and the target y.