# 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 (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, ...)```

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

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

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

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

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

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