R: Generic Interface for Nonnegative Matrix Factorisation Models

NMF-class {NMF}

R Documentation

Generic Interface for Nonnegative Matrix Factorisation Models

Description

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.

Usage

  misc(object, ...)

  ## S4 method for signature 'NMF'
x$name

  ## S4 replacement method for signature 'NMF'
x$name<-value

  ## S4 method for signature 'NMF'
.DollarNames(x, pattern = "")

Arguments

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

Details

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, and references and links therein for details on the built-in implementations of the standard NMF model and its extensions.

Slots

misc: A list that is used internally to temporarily store algorithm parameters during the computation.

Methods

[

signature(x = "NMF"): This method provides a convenient way of sub-setting objects of class NMF, using a matrix-like syntax.

It allows to consistently subset one or both matrix factors in the NMF model, as well as retrieving part of the basis components or part of the mixture coefficients with a reduced amount of code.

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, 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, that should be overloaded by sub-classes, and throws an error if called.

basis<-

signature(object = "NMF"): Default methods that calls .basis<- and check the validity of the updated object.

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, 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, that should be overloaded by sub-classes, and throws an error if called.

coef<-

signature(object = "NMF"): Default methods that calls .coef<- and check the validity of the updated object.

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 for more details.

.DollarNames

signature(x = "NMF"): Auto-completion for NMF objects

.DollarNames

signature(x = "NMF"): Auto-completion for NMF 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, 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 Models

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

Implementing NMF models

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.
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 and its extensions (e.g. classes NMFOffset or NMFns).

Creating NMF objects

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

References

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, <URL: http://dx.doi.org/10.1038/44565>, <URL: http://www.ncbi.nlm.nih.gov/pubmed/10548103>.

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. <URL: http://dx.doi.org/10.1002/env.3170050203>, <URL: http://www3.interscience.wiley.com/cgi-bin/abstract/113468839/ABSTRACT>.

Examples



# show all the NMF models available (i.e. the classes that inherit from class NMF)
nmfModels()
# show all the built-in NMF models available
nmfModels(builtin.only=TRUE)

# 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()
nmfModel(3)
nmfModel(3, model='NMFns')

[Package NMF version 0.27 Index]

Generic Interface for Nonnegative Matrix Factorisation Models

Description

Usage

Arguments

Details

Slots

Methods

Implementing NMF models

Creating NMF objects

References

See Also

Examples