The class `NMF`

is a *virtual class* that
defines a common interface to handle Nonnegative Matrix
Factorization models (NMF models) in a generic way.
Provided a minimum set of generic methods is implemented
by concrete model classes, these benefit from a whole set
of functions and utilities to perform common computations
and tasks in the context of Nonnegative Matrix
Factorization.

The function `misc`

provides access to miscellaneous
data members stored in slot `misc`

(as a
`list`

), which allow extensions of NMF models to be
implemented, without defining a new S4 class.

misc(object, ...) S4 (NMF) `$`(x, name) S4 (NMF) `$`(x, name) <- value S4 (NMF) `.DollarNames`(x, pattern = "")

- object
- an object that inherit from class
`NMF`

- ...
- extra arguments (not used)
- x
- object from which to extract element(s) or in which to replace element(s).
- name
- A literal character string or a name
(possibly backtick quoted). For extraction, this
is normally (see under ‘Environments’) partially
matched to the
`names`

of the object. - value
- typically an array-like R object of a
similar class as
`x`

. - pattern
- A regular expression. Only matching names are returned.

Class `NMF`

makes it easy to develop new models that
integrate well into the general framework implemented by
the *NMF* package.

Following a few simple guidelines, new types of NMF
models benefit from all the functionalities available for
the built-in NMF models -- that derive themselves from
class `NMF`

. See section *Implementing NMF
models* below.

See `NMFstd-class`

, and references and links
therein for details on the built-in implementations of
the standard NMF model and its extensions.

- miscA list that is used internally to temporarily store algorithm parameters during the computation.

- [
`signature(x = "NMF")`

: This method provides a convenient way of sub-setting objects of class`NMF`

, using a matrix-like syntax.See

`[,NMF-method`

for more details. - $
`signature(x = "NMF")`

: shortcut for`x@misc[[name, exact=TRUE]]`

respectively. - $
`signature(x = "NMF")`

: shortcut for`x@misc[[name, exact=TRUE]]`

respectively. - $<-
`signature(x = "NMF")`

: shortcut for`x@misc[[name]] <- value`

- $<-
`signature(x = "NMF")`

: shortcut for`x@misc[[name]] <- value`

- .basis
`signature(object = "NMF")`

: Pure virtual method for objects of class`NMF-class`

, that should be overloaded by sub-classes, and throws an error if called. - .basis<-
`signature(object = "NMF", value = "matrix")`

: Pure virtual method for objects of class`NMF-class`

, that should be overloaded by sub-classes, and throws an error if called. - basiscor
`signature(x = "NMF", y = "matrix")`

: Computes the correlations between the basis vectors of`x`

and the columns of`y`

. - basiscor
`signature(x = "NMF", y = "NMF")`

: Computes the correlations between the basis vectors of`x`

and`y`

. - basiscor
`signature(x = "NMF", y = "missing")`

: Computes the correlations between the basis vectors of`x`

. - basismap
`signature(object = "NMF")`

: Plots a heatmap of the basis matrix of the NMF model`object`

. This method also works for fitted NMF models (i.e.`NMFfit`

objects). - c
`signature(x = "NMF")`

: Binds compatible matrices and NMF models together. - .coef
`signature(object = "NMF")`

: Pure virtual method for objects of class`NMF-class`

, that should be overloaded by sub-classes, and throws an error if called. - .coef<-
`signature(object = "NMF", value = "matrix")`

: Pure virtual method for objects of class`NMF-class`

, that should be overloaded by sub-classes, and throws an error if called. - coefficients
`signature(object = "NMF")`

: Alias to`coef,NMF`

, therefore also pure virtual. - coefmap
`signature(object = "NMF")`

: The default method for NMF objects has special default values for some arguments of`aheatmap`

(see argument description). - connectivity
`signature(object = "NMF")`

: Computes the connectivity matrix for an NMF model, for which cluster membership is given by the most contributing basis component in each sample. See`predict,NMF-method`

. - consensus
`signature(object = "NMF")`

: This method is provided for completeness and is identical to`connectivity`

, and returns the connectivity matrix, which, in the case of a single NMF model, is also the consensus matrix. - consensushc
`signature(object = "NMF")`

: Compute the hierarchical clustering on the connectivity matrix of`object`

. - consensusmap
`signature(object = "NMF")`

: Plots a heatmap of the connectivity matrix of an NMF model. - deviance
`signature(object = "NMF")`

: Computes the distance between a matrix and the estimate of an`NMF`

model. - dim
`signature(x = "NMF")`

: method for NMF objects for the base generic`dim`

. It returns all dimensions in a length-3 integer vector: the number of row and columns of the estimated target matrix, as well as the factorization rank (i.e. the number of basis components). - dimnames
`signature(x = "NMF")`

: Returns the dimension names of the NMF model`x`

.It returns either NULL if no dimnames are set on the object, or a 3-length list containing the row names of the basis matrix, the column names of the mixture coefficient matrix, and the column names of the basis matrix (i.e. the names of the basis components).

- dimnames<-
`signature(x = "NMF")`

: sets the dimension names of the NMF model`x`

.`value`

can be`NULL`

which resets all dimension names, or a 1, 2 or 3-length list providing names at least for the rows of the basis matrix.See

`dimnames<-,NMF-method`

for more details. - .DollarNames
`signature(x = "NMF")`

: Auto-completion for`NMF-class`

objects - .DollarNames
`signature(x = "NMF")`

: Auto-completion for`NMF-class`

objects - extractFeatures
`signature(object = "NMF")`

: Select basis-specific features from an NMF model, by applying the method`extractFeatures,matrix`

to its basis matrix. - featureScore
`signature(object = "NMF")`

: Computes feature scores on the basis matrix of an NMF model. - fitted
`signature(object = "NMF")`

: Pure virtual method for objects of class`NMF-class`

, that should be overloaded by sub-classes, and throws an error if called. - ibterms
`signature(object = "NMF")`

: Default pure virtual method that ensure a method is defined for concrete NMF model classes. - icterms
`signature(object = "NMF")`

: Default pure virtual method that ensure a method is defined for concrete NMF model classes. - loadings
`signature(x = "NMF")`

: Method loadings for NMF ModelsThe method

`loadings`

is identical to`basis`

, but do not accept any extra argument.See

`loadings,NMF-method`

for more details. - metaHeatmap
`signature(object = "NMF")`

: Deprecated method that is substituted by`coefmap`

and`basismap`

. - nmf.equal
`signature(x = "NMF", y = "NMF")`

: Compares two NMF models.Arguments in

`...`

are used only when`identical=FALSE`

and are passed to`all.equal`

. - nmf.equal
`signature(x = "NMF", y = "NMFfit")`

: Compares two NMF models when at least one comes from a NMFfit object, i.e. an object returned by a single run of`nmf`

. - nmf.equal
`signature(x = "NMF", y = "NMFfitX")`

: Compares two NMF models when at least one comes from multiple NMF runs. - nneg
`signature(object = "NMF")`

: Apply`nneg`

to the basis matrix of an`NMF`

object (i.e.`basis(object)`

). All extra arguments in`...`

are passed to the method`nneg,matrix`

. - predict
`signature(object = "NMF")`

: Default method for NMF models - profcor
`signature(x = "NMF", y = "matrix")`

: Computes the correlations between the basis profiles of`x`

and the rows of`y`

. - profcor
`signature(x = "NMF", y = "NMF")`

: Computes the correlations between the basis profiles of`x`

and`y`

. - profcor
`signature(x = "NMF", y = "missing")`

: Computes the correlations between the basis profiles of`x`

. - rmatrix
`signature(x = "NMF")`

: Returns the target matrix estimate of the NMF model`x`

, perturbated by adding a random matrix generated using the default method of`rmatrix`

: it is a equivalent to`fitted(x) + rmatrix(fitted(x), ...)`

.This method can be used to generate random target matrices that depart from a known NMF model to a controlled extend. This is useful to test the robustness of NMF algorithms to the presence of certain types of noise in the data.

- rnmf
`signature(x = "NMF", target = "numeric")`

: Generates a random NMF model of the same class and rank as another NMF model.This is the workhorse method that is eventually called by all other methods. It generates an NMF model of the same class and rank as

`x`

, compatible with the dimensions specified in`target`

, that can be a single or 2-length numeric vector, to specify a square or rectangular target matrix respectively.See

`rnmf,NMF,numeric-method`

for more details. - rnmf
`signature(x = "NMF", target = "missing")`

: Generates a random NMF model of the same dimension as another NMF model.It is a shortcut for

`rnmf(x, nrow(x), ncol(x), ...)`

, which returns a random NMF model of the same class and dimensions as`x`

. - rposneg
`signature(object = "NMF")`

: Apply`rposneg`

to the basis matrix of an`NMF`

object. - show
`signature(object = "NMF")`

: Show method for objects of class`NMF`

- sparseness
`signature(x = "NMF")`

: Compute the sparseness of an object of class`NMF`

, as the sparseness of the basis and coefficient matrices computed separately.It returns the two values in a numeric vector with names ‘basis’ and ‘coef’.

- summary
`signature(object = "NMF")`

: Computes summary measures for a single NMF model.The following measures are computed:

See

`summary,NMF-method`

for more details.

The class `NMF`

only defines a basic data/low-level
interface for NMF models, as a collection of generic
methods, responsible with data handling, upon which
relies a comprehensive set of functions, composing a rich
higher-level interface.

Actual NMF models are defined as sub-classes that
inherits from class `NMF`

, and implement the
management of data storage, providing definitions for the
interface's pure virtual methods.

The minimum requirement to define a new NMF model that
integrates into the framework of the *NMF* package
are the followings:

- Define a class that inherits from class
`NMF`

and implements the new model, say class`myNMF`

. - Implement the following S4 methods for the new
class
`myNMF`

:- fitted
`signature(object = "myNMF", value = "matrix")`

: Must return the estimated target matrix as fitted by the NMF model`object`

. - basis
`signature(object = "myNMF")`

: Must return the basis matrix(e.g. the first matrix factor in the standard NMF model). - basis<-
`signature(object = "myNMF", value = "matrix")`

: Must return`object`

with the basis matrix set to`value`

. - coef
`signature(object = "myNMF")`

: Must return the matrix of mixture coefficients (e.g. the second matrix factor in the standard NMF model). - coef<-
`signature(object = "myNMF", value = "matrix")`

: Must return`object`

with the matrix of mixture coefficients set to`value`

.

The

*NMF*package provides "pure virtual" definitions of these methods for class`NMF`

(i.e. with signatures`(object='NMF', ...)`

and`(object='NMF', value='matrix')`

) that throw an error if called, so as to force their definition for model classes. - fitted
- Optionally, implement method
`rnmf`

(signature(x="myNMF", target="ANY")). This method should call`callNextMethod(x=x, target=target, ...)`

and fill the returned NMF model with its specific data suitable random values.

For concrete examples of NMF models implementations, see
class `NMFstd-class`

and its extensions
(e.g. classes `NMFOffset-class`

or
`NMFns-class`

).

Strictly speaking, because class `NMF`

is virtual,
no object of class `NMF`

can be instantiated, only
objects from its sub-classes. However, those objects are
sometimes shortly referred in the documentation and
vignettes as "`NMF`

objects" instead of "objects
that inherits from class `NMF`

".

For built-in models or for models that inherit from the
standard model class `NMFstd-class`

, the
factory method `nmfModel`

enables to easily create
valid `NMF`

objects in a variety of common
situations. See documentation for the the factory method
`nmfModel`

for more details.

Definition of Nonnegative Matrix Factorization in its modern formulation: Lee et al. (1999)

Historical first definition and algorithms: Paatero et al. (1994)

Lee DD and Seung HS (1999). "Learning the parts of
objects by non-negative matrix factorization." _Nature_,
*401*(6755), pp. 788-91. ISSN 0028-0836,

Paatero P and Tapper U (1994). "Positive matrix
factorization: A non-negative factor model with optimal
utilization of error estimates of data values."
_Environmetrics_, *5*(2), pp. 111-126.

```
# show all the NMF models available (i.e. the classes that inherit from class NMF)
nmfModels()
```

```
## [1] "NMFstd" "NMFOffset" "NMFns"
```

```
# show all the built-in NMF models available
nmfModels(builtin.only=TRUE)
```

```
## [1] "NMFstd" "NMFOffset" "NMFns"
```

```
# class NMF is a virtual class so cannot be instantiated:
try( new('NMF') )
# To instantiate an NMF model, use the factory method nmfModel. see ?nmfModel
nmfModel()
```

```
## <Object of class:NMFstd>
## features: 0
## basis/rank: 0
## samples: 0
```

```
nmfModel(3)
```

```
## <Object of class:NMFstd>
## features: 0
## basis/rank: 3
## samples: 0
```

```
nmfModel(3, model='NMFns')
```

```
## <Object of class:NMFns>
## features: 0
## basis/rank: 3
## samples: 0
## theta: 0.5
```

```
```

`nmf-methods`

.
Built-in NMF models and factory method in
`nmfModel`

.
Method `seed`

to set NMF objects with values
suitable to start algorithms with.
Other NMF-interface: `basis`

,
`.basis`

, `.basis<-`

,
`basis<-`

, `coef`

,
`.coef`

, `.coef<-`

,
`coef<-`

, `coefficients`

,
`loadings,NMF-method`

,
`nmfModel`

, `nmfModels`

,
`rnmf`

, `scoef`