Description Usage Arguments Details Value Functions Slots Implementing NMF models Creating NMF objects Methods (by generic) References See Also Examples
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 | ## S4 method for signature 'NMF'
fitted(object, ...)
## S4 method for signature 'NMF'
.basis(object, ...)
## S4 replacement method for signature 'NMF,mMatrix'
.basis(object) <- value
## S4 method for signature 'NMF'
.coef(object, ...)
## S4 replacement method for signature 'NMF,mMatrix'
.coef(object) <- value
## S4 method for signature 'NMF'
scoef(object, scale = 1)
## S3 method for class 'NMF'
scale(x, center = c("basis", "coef"), scale = 1)
## S4 method for signature 'NMF'
show(object)
misc(object, ...)
## S4 method for signature 'NMF'
x$name
## S4 replacement method for signature 'NMF'
x$name <- value
## S3 method for class 'NMF'
.DollarNames(x, pattern = "")
## S4 method for signature 'NMF'
.DollarNames(x, pattern = "")
## S4 method for signature 'NMF'
rmatrix(x, ...)
## S4 method for signature 'NMF'
sparseness(x)
## S4 method for signature 'NMF,matrix'
basiscor(x, y, ...)
## S4 method for signature 'matrix,NMF'
basiscor(x, y, ...)
## S4 method for signature 'NMF,NMF'
basiscor(x, y, ...)
## S4 method for signature 'NMF,missing'
basiscor(x, y, ...)
## S4 method for signature 'NMF,matrix'
profcor(x, y, ...)
## S4 method for signature 'matrix,NMF'
profcor(x, y, ...)
## S4 method for signature 'NMF,NMF'
profcor(x, y, ...)
## S4 method for signature 'NMF,missing'
profcor(x, y, ...)
## S4 method for signature 'NMF'
connectivity(object, no.attrib = FALSE)
## S3 method for class 'NMF'
anyNA(x, recursive = FALSE)
## S3 method for class 'NMF'
t(x)
## S4 method for signature 'NMF'
c(x, ..., margin = 3L, recursive = FALSE)
## S4 method for signature 'NMF'
ibterms(object, ...)
## S4 method for signature 'NMF'
icterms(object, ...)
## S4 method for signature 'NMF,NMFfit'
nmf.equal(x, y, ...)
## S4 method for signature 'NMF'
nrun(object)
## S4 method for signature 'NMF'
consensus(object, ...)
## S4 method for signature 'NMF,NMFfitX'
nmf.equal(x, y, ...)
## S3 method for class 'NMF'
silhouette(x, what = NULL, order = NULL, ...)
|
object |
an object that inherit from class |
... |
extra arguments not used. |
scale |
scaling coefficient applied to D, i.e. the value of alpha,
or, if |
x |
an NMF object, as returned by |
center |
either a numeric normalising vector delta, or either
|
no.attrib |
a logical that indicates if attributes containing information
about the NMF model should be attached to the result ( |
margin |
integer that indicates the margin along which to concatenate
(only used when
If missing the margin is heuristically determined by looking at common dimensions between the objects. |
what |
defines the type of clustering the computed silhouettes are
meant to assess: |
order |
integer indexing vector that can be used to force the silhouette order. |
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.
an NMF object
misc
: 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
A list that is used internally to temporarily store algorithm parameters during the computation.
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
:
signature(object = "myNMF", value = "matrix")
:
Must return the estimated target matrix as fitted by the NMF model
object
.
signature(object = "myNMF")
:
Must return the basis matrix(e.g. the first matrix factor in
the standard NMF model).
signature(object = "myNMF", value = "matrix")
:
Must return object
with the basis matrix 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 \emph{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
).
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.
.basis:
.basis(object = NMF)
: Pure virtual method for objects of class NMF
, that
should be overloaded by sub-classes, and throws an error if called.
.basis<-:
.basis<-(object = NMF,value = mMatrix)
: Pure virtual method for objects of class NMF
, that
should be overloaded by sub-classes, and throws an error if called.
.coef:
.coef(object = NMF)
: Pure virtual method for objects of class NMF
, that
should be overloaded by sub-classes, and throws an error if called.
.coef<-:
.coef<-(object = NMF,value = mMatrix)
: Pure virtual method for objects of class NMF
, that
should be overloaded by sub-classes, and throws an error if called.
[:
[(x = NMF,i = ANY,j = ANY,drop = ANY)
: Sub-setting NMF Objects
This method provides a convenient way of sub-setting objects of class NMF
,
using a matrix-like syntax.
$:
$(x = NMF)
: shortcut for x@misc[[name, exact=TRUE]]
respectively.
$<-:
$<-(x = NMF)
: shortcut for x@misc[[name]] <- value
basis<-:
basis<-(object = NMF)
: Default methods that calls .basis<-
and check the validity of the
updated object.
basiscor:
basiscor(x = NMF,y = matrix)
: Computes the correlations between the basis vectors of x
and
the columns of y
.
basiscor(x = matrix,y = NMF)
: Computes the correlations between the columns of x
and the the basis vectors of y
.
basiscor(x = NMF,y = NMF)
: Computes the correlations between the basis vectors of x
and y
.
basiscor(x = NMF,y = missing)
: Computes the correlations between the basis vectors of x
.
basismap:
basismap(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:
c(x = NMF)
: Concatenating NMF Models
Binds compatible matrices and NMF models together.
canFit:
canFit(x = NMFStrategy,y = NMF)
: Tells if an NMF algorithm can fit the same class of models as y
coef<-:
coef<-(object = NMF)
: Default methods that calls .coef<-
and check the validity of the
updated object.
coefficients:
coefficients(object = NMF)
: Alias to coef,NMF
, therefore also pure virtual.
coefmap:
coefmap(object = NMF)
: The default method for NMF objects has special default values for
some arguments of aheatmap
(see argument description).
connectivity:
connectivity(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:
consensus(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:
consensushc(object = NMF)
: Compute the hierarchical clustering on the connectivity matrix of object
.
consensusmap:
consensusmap(object = NMF)
: Plots a heatmap of the connectivity matrix of an NMF model.
deviance:
deviance(object = NMF)
: Computes the distance between a matrix and the estimate of an NMF
model.
dim:
dim(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:
dimnames(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<-:
dimnames<-(x = NMF,value = ANY)
: 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.
The optional second element of value
(NULL if absent) is used to set
the column names of the coefficient matrix.
The optional third element of value
(NULL if absent) is used to set
both the column names of the basis matrix and the row names of the
coefficient matrix.
extractFeatures:
extractFeatures(object = NMF)
: Select basis-specific features from an NMF model, by applying the method
extractFeatures,matrix
to its basis matrix.
featureScore:
featureScore(object = NMF)
: Computes feature scores on the basis matrix of an NMF model.
fit<-:
fit<-(object = NMFfit,value = NMF)
: Updates the NMF model object stored in slot 'fit'
with a new value.
fitted:
fitted(object = NMF)
: Pure virtual method for objects of class NMF
, that
should be overloaded by sub-classes, and throws an error if called.
ibterms:
ibterms(object = NMF)
: Default pure virtual method that ensure a method is defined for concrete
NMF model classes.
icterms:
icterms(object = NMF)
: Default pure virtual method that ensure a method is defined for concrete
NMF model classes.
loadings:
loadings(x = NMF)
: Method loadings for NMF Models
The method loadings
is identical to basis
, but do
not accept any extra argument.
metaHeatmap:
metaHeatmap(object = NMF)
: Deprecated method that is substituted by coefmap
and basismap
.
nmf:
nmf(x = mMatrix,rank = NMF,method = ANY)
: Fits an NMF model using the NMF model rank
to seed the computation,
i.e. as a starting point.
This method is provided for convenience as a shortcut for
nmf(x, nbasis(object), method, seed=object, ...)
It discards any value passed in argument seed
and uses the NMF model passed
in rank
instead.
It throws a warning if argument seed
not missing.
If method
is missing, this method will call the method
nmf,matrix,numeric,NULL
, which will infer an algorithm suitable for fitting an
NMF model of the class of rank
.
nmf.equal:
nmf.equal(x = NMF,y = NMF)
: Compares two NMF models.
Arguments in ...
are used only when identical=FALSE
and are
passed to all.equal
.
nmf.equal(x = NMFfit,y = NMF)
: 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(x = NMFfitX,y = NMF)
: Compares two NMF models when at least one comes from multiple NMF runs.
nmf.equal(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(x = NMF,y = NMFfitX)
: Compares two NMF models when at least one comes from multiple NMF runs.
nneg:
nneg(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
.
nrun:
nrun(object = NMF)
: This default fallback method always returns 1L
.
predict:
predict(object = NMF)
: Default method for NMF models
profcor:
profcor(x = NMF,y = matrix)
: Computes the correlations between the basis profiles of x
and
the rows of y
.
profcor(x = matrix,y = NMF)
: Computes the correlations between the rows of x
and the basis
profiles of y
.
profcor(x = NMF,y = NMF)
: Computes the correlations between the basis profiles of x
and y
.
profcor(x = NMF,y = missing)
: Computes the correlations between the basis profiles of x
.
rmatrix:
rmatrix(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:
rnmf(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.
The second dimension can also be passed via argument ncol
, so that
calling rnmf(x, 20, 10, ...)
is equivalent to rnmf(x, c(20, 10), ...)
,
but easier to write.
The entries are uniformly drawn between 0
and max
(optionally specified in ...
) that defaults to 1.
By default the dimnames of x
are set on the returned NMF model.
This behaviour is disabled with argument keep.names=FALSE
.
See nmfModel
.
rnmf(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:
rposneg(object = NMF)
: Apply rposneg
to the basis matrix of an NMF
object.
run:
run(object = NMFStrategy,y = mMatrix,x = NMF)
: Method to run an NMF algorithm directly starting from a given NMF model.
scale:
scale(NMF)
: Rescaling NMF Models
Rescales an NMF model keeping the fitted target matrix identical.
Standard NMF models are identifiable modulo a scaling factor, meaning that the basis components and basis profiles can be rescaled without changing the fitted values:
X = W H = (W D) (D^-1 H)
with D= alpha * diag(1/delta_1, ..., 1/delta_r)
The default call scale(object)
rescales the basis NMF object so that each
column of the basis matrix sums up to one.
seed:
seed(x = mMatrix,model = NMF,method = NMFSeed)
: This is the workhorse method that seeds an NMF model object using a given
seeding strategy defined by an NMFSeed
object, to fit a given
target matrix.
show:
show(object = NMF)
: Show method for objects of class NMF
silhouette:
silhouette(NMF)
: Silhouette of NMF Clustering
sparseness:
sparseness(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:
summary(object = NMF)
: Computes summary measures for a single NMF model.
The following measures are computed:
t:
t(NMF)
: Transformation of NMF Model Objects
t
transpose an NMF model, by transposing and swapping its basis and
coefficient matrices: t([W,H]) = [t(H), t(W)].
The function t
is a generic defined in the base package.
The method t.NMF
defines the trasnformation for the general NMF interface.
This method may need to be overloaded for NMF models, whose structure requires
specific handling.
Definition of Nonnegative Matrix Factorization in its modern formulation: Lee DD, Seung HS (1999). “Learning the parts of objects by non-negative matrix factorization.” _Nature_, *401*(6755), 788-91. ISSN 0028-0836, doi: 10.1038/44565 (URL: https://doi.org/10.1038/44565).
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_, *5*(2), 111-126. doi: 10.1002/env.3170050203 (URL: https://doi.org/10.1002/env.3170050203).
Main interface function nmf to perform NMF.
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()
,
nmfModel()
,
rnmf()
Other transforms:
nneg()
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 | # 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')
# random 3-rank 10x5 NMF model
x <- rnmf(3, 10, 5)
# rescale based on basis
colSums(basis(x))
colSums(basis(scale(x)))
rx <- scale(x, 'basis', 10)
colSums(basis(rx))
rowSums(coef(rx))
# rescale based on coef
rowSums(coef(x))
rowSums(coef(scale(x, 'coef')))
rx <- scale(x, 'coef', 10)
rowSums(coef(rx))
colSums(basis(rx))
# fitted target matrix is identical but the factors have been rescaled
rx <- scale(x, 'basis')
all.equal(fitted(x), fitted(rx))
all.equal(basis(x), basis(rx))
# generate noisy fitted target from an NMF model (the true model)
gr <- as.numeric(mapply(rep, 1:3, 3))
h <- outer(1:3, gr, '==') + 0
x <- rnmf(10, H=h)
y <- rmatrix(x)
## Not run:
# show heatmap of the noisy target matrix: block patterns should be clear
aheatmap(y)
## End(Not run)
# test NMF algorithm on noisy data
# add some noise to the true model (drawn from uniform [0,1])
res <- nmf(rmatrix(x), 3)
summary(res)
# add more noise to the true model (drawn from uniform [0,10])
res <- nmf(rmatrix(x, max=10), 3)
summary(res)
x <- rnmf(3, 100, 20)
x
# transpose
y <- t(x)
y
# factors are swapped-transposed
stopifnot( identical(basis(y), t(coef(x))) )
stopifnot( identical(coef(y), t(basis(x))) )
x <- rmatrix(100, 20, dimnames = list(paste0('a', 1:100), letters[1:20]))
# NB: using low value for maxIter for the example purpose only
res <- nmf(x, 4, nrun = 5, maxIter = 50)
# sample clustering from best fit
plot(silhouette(res))
# from consensus
plot(silhouette(res, what = 'consensus'))
# feature clustering
plot(silhouette(res, what = 'features'))
# average silhouette are computed in summary measures
summary(res)
# consensus silhouettes are ordered as on default consensusmap heatmap
## Not run: op <- par(mfrow = c(1,2))
consensusmap(res)
si <- silhouette(res, what = 'consensus')
plot(si)
## Not run: par(op)
# if the order is based on some custom numeric weights
## Not run: op <- par(mfrow = c(1,2))
cm <- consensusmap(res, Rowv = runif(ncol(res)))
# NB: use reverse order because silhouettes are plotted top-down
si <- silhouette(res, what = 'consensus', order = rev(cm$rowInd))
plot(si)
## Not run: par(op)
# do the reverse: order the heatmap as a set of silhouettes
si <- silhouette(res, what = 'features')
## Not run: op <- par(mfrow = c(1,2))
basismap(res, Rowv = si)
plot(si)
## Not run: par(op)
|
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.