R: Distances and Objective Functions

deviance {NMF} | R Documentation

## Distances and Objective Functions

### Description

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.

### Usage

      deviance(object, ...)

      ## S4 method for signature 'NMF'
    deviance(object, y,
        method = c("", "KL", "euclidean"), ...)

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

      ## S4 method for signature 'NMFfit'
    deviance(object, y, method, ...)

      ## S4 method for signature 'NMFStrategy'
    deviance(object, x, y, ...)

### Arguments

`y` | a matrix compatible with the NMF model `object`, i.e. `y` must have the same dimension as `fitted(object)`.
`method` | 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.
`x` | an NMF model that estimates `y`.
`object` | an object for which the deviance is desired.

### Value

`deviance` returns a nonnegative numerical value

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

### Methods

deviance

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

deviance

  `signature(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.

deviance

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

deviance

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

### See Also

Other stats: `deviance,NMF-method`, `hasTrack`, `residuals`, `residuals<-`, `trackError`

[Package NMF version 0.21.0 Index]