NMF-class {NMF} | R Documentation |
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.
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.
The minimum requirement to define a new NMF model that integrates into the framework of the NMF package are the followings:
NMF
and implements the new model.
Say class myNMF
.
myNMF
:
signature(object = "myNMF", value = "matrix")
:
Must return the estimation of the target matrix as fitted by the NMF model
object
.
signature(object = "myNMF")
:
Must return the matrix of basis vectors (e.g. the first matrix factor in
the standard NMF model).
signature(object = "myNMF", value = "matrix")
:
Must return object
with the matrix of basis vectors set to
value
.
signature(object = "myNMF")
:
Must return the matrix of mixture coefficients (e.g. the second matrix
factor in the standard NMF model).
signature(object = "myNMF", value = "matrix")
:
Must return object
with the matrix of mixture coefficients set to
value
.
The NMF package ensures these methods are defined for classes that
inherits from class NMF
, as the methods defined for signatures
(object='NMF', ...)
and (object='NMF', value='matrix')
throw an error when called.
random
(signature(object="myNMF", target="numeric")).
This method should fill model object
(of class myNMF
) with
random values to fit a target matrix, whose dimension is given
by the 2-length numeric vector target
.
For concrete examples of NMF models implementations, see class
NMFstd
and its extensions (e.g. classes
NMFOffset
or NMFns
).
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.
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.
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
.
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
.
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
.
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<-
.
signature(object = "NMF")
:
This is a simple alias to method coef
.
See also coefficients
.
signature(object = "NMF", value = "matrix")
:
This is a simple alias to method coef<-
.
See also coef
.
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.
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.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.
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.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.
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.
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.
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. 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. 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.
heatmap.2
with parameters
tuned for displaying NMF results.
See metaHeatmap
for more details.
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.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.
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.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
missing
random(x, c(nrow(x), ncol(x)))
,
that is a random NMF model with the same dimensions as defined in model x
.
matrix
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
.
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.
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.
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.
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.
signature(x = "NMF")
:
compute the average sparseness of the basis vectors or mixture coefficients.
See Hoyer (2004) for more details. 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.Renaud Gaujoux renaud@cbio.uct.ac.za
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.
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.
# 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')