NMF-class {NMF}R Documentation

Interface class for Nonnegative Matrix Factorisation models

Description

This is a virtual class that defines a common interface to handle Nonnegative Matrix Factorisation models (NMF models) in a generic way.

It provides the definition for a minimum set of generic methods that are used in common computations and tasks in the context of Nonnegative Matrix Factorisations.

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

Following a few simple guidelines, new models benefit from all the functionalities available to built-in NMF models – that derive themselves from class NMF. See section Defining new NMF models below.

See section NMFstd, references and links therein for details on the standard NMF model and its – built-in – extensions.

Slots

This class doesn't contain any slot. Its purpose is to define a common interface for NMF models as a collection of generic methods. Classes that inherits from class NMF are responsible for the management of data storage and the implementation of the interface's pure virtual methods.

Defining new NMF models

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

For concrete examples of NMF models implementations, see class NMFstd and its extensions (e.g. classes NMFOffset or NMFns).

Objects from the 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 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 newNMF enables to easily create valid NMF objects in a variety of common situations. See newNMF for more details.

Methods

[
signature(object = "NMF"): sub-setting method for object of class NMF. Row subsets are applied to the basis matrix rows, while column subsets are applied to the mixture coefficient matrix. It returns an object of class NMF whose basis matrix and/or mixture coefficient matrix have been subset accordingly.
basis
signature(object = "NMF"): returns the matrix of basis vectors according to the model defined in object. This is a pure virtual method that needs to be defined for the sub-classes of class NMF that implements concrete models. See also basis.
basis<-
signature(object = "NMF", value = "matrix"): sets the matrix of basis vectors in object, and returns the updated object. This is a pure virtual method that needs to be defined for the sub-classes of class NMF that implements concrete models. See also basis.
coef
signature(object = "NMF"): returns the matrix of mixture coefficients according to the model defined in object. This is a pure virtual method that needs to be defined for the sub-classes of class NMF that implements concrete models. See also coef.
coef<-
signature(object = "NMF", value = "matrix"): sets the matrix of mixture coefficients in object, and returns the updated object. This is a pure virtual method that needs to be defined for the sub-classes of class NMF that implements concrete models. See also coef<-.
coefficients
signature(object = "NMF"): This is a simple alias to method coef. See also coefficients.
coefficients<-
signature(object = "NMF", value = "matrix"): This is a simple alias to method coef<-. See also coef.
connectivity
signature(x = "NMF"): returns the connectivity matrix associated to the clusters based on NMF factorization x. The connectivity matrix C of a clustering is the symmetric matrix that shows the shared membership of the samples: entry C_{ij} is 1 if samples i and j belong to the same cluster, 0 otherwise.
dim
signature(x = "NMF"): returns a 3-length vector containing the dimension of the target matrix together with the NMF factorization rank. For example c(2000,30,3) for a NMF object that fits a 2000x30 target matrix using 3 basis vectors.
distance
signature(target = "matrix", x = "NMF"): returns the distance between a target matrix and a NMF model, according to a given measure. See function distance for more details.
entropy
signature(x = "NMF", class = "factor"): computes the entropy of NMF model x given a priori known groups of samples. See generic function entropy for more details.
featureNames
signature(object = "NMF"): returns the row names of the basis matrix. If BioConductor is installed this method is defined for the generic function featureNames from the Biobase package.
featureNames<-
signature(object = "NMF", value = "ANY"): sets the row names of the basis matrix. Argument value must be in a format accepted by the rownames method defined for matrices. If BioConductor is installed this method is defined for the generic function featureNames<- from the Biobase package.
fitted
signature(object = "NMF"): computes the target matrix estimated by NMF model object. This is a pure virtual method that needs to be implemented by the sub-classes of class NMF that implements concrete models.
featureScore
signature(x = "NMF"): Computes a score for each feature that reflects its specificity to one of the basis vector. The definition of the score follows Kim and Park (2007). See references for more details.
extractFeatures
signature(x = "NMF"): extract the features that are the most specific to each basis vector. It follows Kim and Park (2007)'s methodology. See references for more details.
is.empty.nmf
signature(object = "NMF"): Tells if object is an empty the NMF model, that is it contains no data. It returns TRUE if the matrices of basis vectors and mixture coefficients have respectively zero rows and zero columns. It returns FALSE otherwise. This means that an empty model can still have a non-zero number of basis vectors. For example, this happens in the case of NMF models created using factory method newNMF with no initialisation for any factor matrices.
metaHeatmap
Produces a heatmap of the basis or mixture matrix using function heatmap.2 with parameters tuned for displaying NMF results. See metaHeatmap for more details.
nbasis
signature(x = "NMF"): returns the number of basis vectors used in NMF model x. It is the number of columns of the matrix of basis vectors.
predict
signature(object = "NMF"): returns a factor that gives the predicted cluster index for each sample (resp. for each feature) based on NMF factorization object. The index correspond to the basis vector that most contribute to the sample (resp. to which the feature contribute the most). See predict details on extra arguments.

purity
signature(x = "NMF", class = "factor"): computes the purity of NMF model x given a priori known groups of samples. The purity definition can be found in Kim and Park (2007). See references for more details.
random
signature(x = "NMF", target): seeds NMF model x with random values drawn from a random distribution. The result is a NMF model of the same class as x with basis and mixture matrices filled with random values.

Argument target can be either:

numeric
it must be of length 2 (resp. 1), and give the dimension of the target matrix (resp. symmetric matrix) to fit. The result is a random NMF model.

missing
it returns random(x, c(nrow(x), ncol(x))), that is a random NMF model with the same dimensions as defined in model x.
matrix
it returns random(x, dim(target)), that is a random NMF model that fits a matrix of the same dimension as target. The values are drawn within the interval [0, max(target)].

This method's version with signature (object='NMF', target='numeric') might need to be overloaded if the initialisation of the specific NMF model requires setting values for data other than the basis and mixture matrices. The overloading methods must call the generic version using function callNextMethod.

rss
signature(object = "NMF"): returns the Residual Sum of Squares (RSS) between the target matrix and its estimation by the NMF model object. Hutchins et al. (2008) used the variation of the RSS in combination with Lee and Seung's algorithm to estimate the correct number of basis vectors. See rss for details on its usage.

sampleNames
signature(object = "NMF"): returns the column names of the mixture coefficient matrix. If BioConductor is installed this method is defined for the generic function sampleNames from the Biobase package.
sampleNames<-
signature(object = "NMF", value = "ANY"): sets the columns names of the basis matrix. Argument value must be in a format accepted by the colnames method defined for matrices. If BioConductor is installed this method is defined for the generic function sampleNames<- from the Biobase package.
show
signature(object = "NMF"): standard generic show method for objects of class NMF. It displays the model class (i.e. the name of the sub-class that implements the concrete model), the dimension of the target matrix, and the number of basis vectors.
sparseness
signature(x = "NMF"): compute the average sparseness of the basis vectors or mixture coefficients. See Hoyer (2004) for more details.
summary
signature(x = "NMF"): standard generic summary method for objects of class NMF. It computes a set of measures to evaluate the quality of the factorization.

Author(s)

Renaud Gaujoux renaud@cbio.uct.ac.za

References

Definition of Nonnegative Matrix Factorization in its modern formulation:

Lee D.D. and Seung H.S. (1999). Learning the parts of objects by non-negative matrix factorization. Nature, 401, 788–791.

Historical first definition and algorithms:

Paatero, P., Tapper, U. (1994). Positive matrix factorization: A non-negative factor model with optimal utilization of error estimates of data values. Environmetrics, 2, 111–126 , doi:10.1002/env.3170050203.

Reference for some utility functions:

Kim, H. and Park, H. (2007). Sparse non-negative matrix factorizations via alternating non-negativity-constrained least squares for microarray data analysis. Bioinformatics.

Hoyer (2004). Non-negative matrix factorization with sparseness constraints. Journal of Machine Learning Research, 5, 1457-1469.

See Also

Main interface to perform NMF in nmf-methods.

Built-in NMF models and factory method in newNMF.

Method seed to set NMF objects with values suitable to start algorithms with.

Examples


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

# class NMF is a virtual class so cannot be instantiated: 
# the following generates an error
## Not run: new('NMF')

# To instantiate a NMF model, use factory method newNMF (see ?newNMF)
newNMF(3)
newNMF(3, model='NMFns')


[Package NMF version 0.2.4 Index]