Package 'NMF'

Description

This package provides a framework to perform Non-negative Matrix Factorization (NMF). It implements a set of already published algorithms and seeding methods, and provides a framework to test, develop and plug new/custom algorithms. Most of the built-in algorithms have been optimized in C++, and the main interface function provides an easy way of performing parallel computations on multicore machines.

Details

nmf Run a given NMF algorithm

Author(s)

Renaud Gaujoux [email protected]

References

https://cran.r-project.org/

See Also

nmf

Examples

# generate a synthetic dataset with known classes
n <- 50; counts <- c(5, 5, 8);
V <- syntheticNMF(n, counts)

# perform a 3-rank NMF using the default algorithm
res <- nmf(V, 3)

basismap(res)
coefmap(res)

Description

This is the workhorse function for the higher-level function fcnnls, which implements the fast nonnegative least-square algorithm for multiple right-hand-sides from Van Benthem et al. (2004) to solve the following problem:

$\begin{array}{l} \min \|Y - X K\|_F\\ \mbox{s.t. } K>=0 \end{array}$

where $Y$ and $X$ are two real matrices of dimension $n \times p$ and $n \times r$ respectively, and $\|.\|_F$ is the Frobenius norm.

The algorithm is very fast compared to other approaches, as it is optimised for handling multiple right-hand sides.

Usage

.fcnnls(x, y, verbose = FALSE, pseudo = FALSE, eps = 0)

Arguments

Value

A list with the following elements:

References

Van Benthem M and Keenan MR (2004). "Fast algorithm for the solution of large-scale non-negativity-constrained least squares problems." _Journal of Chemometrics_, *18*(10), pp. 441-450. ISSN 0886-9383, <URL: http://dx.doi.org/10.1002/cem.889>, <URL: http://doi.wiley.com/10.1002/cem.889>.

Description

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.

Usage

## S4 method for signature 'NMF'
x[i, j, ..., drop = FALSE]

Arguments

Details

The returned value depends on the number of subset index passed and the value of argument drop:

• No index as in x[] or x[,]: the value is the object x unchanged.

• One single index as in x[i]: the value is the complete NMF model composed of the selected basis components, subset by i, except if argument drop=TRUE, or if it is missing and i is of length 1. Then only the basis matrix is returned with dropped dimensions: x[i, drop=TRUE] <=> drop(basis(x)[, i]).

  This means for example that x[1L] is the first basis vector, and x[1:3, drop = TRUE] is the matrix composed of the 3 first basis vectors – in columns.

  Note that in version <= 0.18.3, the call x[i, drop = TRUE.or.FALSE] was equivalent to basis(x)[, i, drop=TRUE.or.FALSE].

• More than one index with drop=FALSE (default) as in x[i,j], x[i,], x[,j], x[i,j,k], x[i,,k], etc...: the value is a NMF object whose basis and/or mixture coefficient matrices have been subset accordingly. The third index k affects simultaneously the columns of the basis matrix AND the rows of the mixture coefficient matrix. In this case argument drop is not used.

• More than one index with drop=TRUE and i xor j missing: the value returned is the matrix that is the more affected by the subset index. That is that x[i, , drop=TRUE] and x[i, , k, drop=TRUE] return the basis matrix subset by [i,] and [i,k] respectively, while x[, j, drop=TRUE] and x[, j, k, drop=TRUE] return the mixture coefficient matrix subset by [,j] and [k,j] respectively.

Examples

# create a dummy NMF object that highlight the different way of subsetting
a <- nmfModel(W=outer(seq(1,5),10^(0:2)), H=outer(10^(0:2),seq(-1,-10)))
basisnames(a) <- paste('b', 1:nbasis(a), sep='')
rownames(a) <- paste('f', 1:nrow(a), sep='')
colnames(a) <- paste('s', 1:ncol(a), sep='')

# or alternatively:
# dimnames(a) <- list( features=paste('f', 1:nrow(a), sep='')
#					, samples=paste('s', 1:ncol(a), sep='')
#					, basis=paste('b', 1:nbasis(a)) )

# look at the resulting NMF object
a
basis(a)
coef(a)

# extract basis components
a[1]
a[1, drop=FALSE] # not dropping matrix dimension
a[2:3]

# subset on the features
a[1,]
a[2:4,]
# dropping the NMF-class wrapping => return subset basis matrix
a[2:4,, drop=TRUE]

# subset on the samples
a[,1]
a[,2:4]
# dropping the NMF-class wrapping => return subset coef matrix
a[,2:4, drop=TRUE]

# subset on the basis => subsets simultaneously basis and coef matrix
a[,,1]
a[,,2:3]
a[4:5,,2:3]
a[4:5,,2:3, drop=TRUE] # return subset basis matrix
a[,4:5,2:3, drop=TRUE] # return subset coef matrix

# 'drop' has no effect here
a[,,2:3, drop=TRUE]

Description

The functions documented here provide advanced functionalities useful when developing within the framework implemented in the NMF package.

which.best returns the index of the best fit in a list of NMF fit, according to some quantitative measure. The index of the fit with the lowest measure is returned.

Usage

which.best(object, FUN = deviance, ...)

Arguments

Description

Given a numerical vector, this function computes an aggregated value using one of the following methods: best or mean

Usage

## S3 method for class 'measure'
aggregate(x, method = c("best", "mean"), decreasing = FALSE, ...)

Arguments

Description

The function aheatmap plots high-quality heatmaps, with a detailed legend and unlimited annotation tracks for both columns and rows. The annotations are coloured differently according to their type (factor or numeric covariate). Although it uses grid graphics, the generated plot is compatible with base layouts such as the ones defined with 'mfrow' or layout, enabling the easy drawing of multiple heatmaps on a single a plot – at last!.

Usage

aheatmap(x, color = "-RdYlBu2:100", breaks = NA,
    border_color = NA, cellwidth = NA, cellheight = NA,
    scale = "none", Rowv = TRUE, Colv = TRUE,
    revC = identical(Colv, "Rowv") || is_NA(Rowv) || (is.integer(Rowv) && 
        length(Rowv) > 1) || is(Rowv, "silhouette"),
    distfun = "euclidean", hclustfun = "complete",
    reorderfun = function(d, w) reorder(d, w),
    treeheight = 50, legend = TRUE, annCol = NA,
    annRow = NA, annColors = NA, annLegend = TRUE,
    labRow = NULL, labCol = NULL, subsetRow = NULL,
    subsetCol = NULL, txt = NULL, fontsize = 10,
    cexRow = min(0.2 + 1/log10(nr), 1.2),
    cexCol = min(0.2 + 1/log10(nc), 1.2), filename = NA,
    width = NA, height = NA, main = NULL, sub = NULL,
    info = NULL, verbose = getOption("verbose"),
    gp = gpar())

Arguments

Details

The development of this function started as a fork of the function pheatmap from the pheatmap package, and provides several enhancements such as:

• argument names match those used in the base function heatmap;

• unlimited number of annotation for both columns and rows, with simplified and more flexible interface;

• easy specification of clustering methods and colors;

• return clustering data, as well as grid grob object.

Please read the associated vignette for more information and sample code.

PDF graphic devices

if plotting on a PDF graphic device – started with pdf, one may get generate a first blank page, due to internals of standard functions from the grid package that are called by aheatmap. The NMF package ships a custom patch that fixes this issue. However, in order to comply with CRAN policies, the patch is not applied by default and the user must explicitly be enabled it. This can be achieved on runtime by either setting the NMF specific option 'grid.patch' via nmf.options(grid.patch=TRUE), or on load time if the environment variable 'R_PACKAGE_NMF_GRID_PATCH' is defined and its value is something that is not equivalent to FALSE (i.e. not ”, 'false' nor 0).

Author(s)

Original version of pheatmap: Raivo Kolde

Enhancement into aheatmap: Renaud Gaujoux

Examples

## See the demo 'aheatmap' for more examples:
## Not run: 
demo('aheatmap')

## End(Not run)

# Generate random data
n <- 50; p <- 20
x <- abs(rmatrix(n, p, rnorm, mean=4, sd=1))
x[1:10, seq(1, 10, 2)] <- x[1:10, seq(1, 10, 2)] + 3
x[11:20, seq(2, 10, 2)] <- x[11:20, seq(2, 10, 2)] + 2
rownames(x) <- paste("ROW", 1:n)
colnames(x) <- paste("COL", 1:p)

## Default heatmap
aheatmap(x)

## Distance methods
aheatmap(x, Rowv = "correlation")
aheatmap(x, Rowv = "man") # partially matched to 'manhattan'
aheatmap(x, Rowv = "man", Colv="binary")

# Generate column annotations
annotation = data.frame(Var1 = factor(1:p %% 2 == 0, labels = c("Class1", "Class2")), Var2 = 1:10)
aheatmap(x, annCol = annotation)

Description

Returns the method names used to compute the NMF fits in the list. It returns NULL if the list is empty.

Usage

## S4 method for signature 'NMFList'
algorithm(object, string = FALSE,
    unique = TRUE)

Arguments

Description

The functions documented here are S4 generics that define an general interface for – optimisation – algorithms.

This interface builds upon the broad definition of an algorithm as a workhorse function to which is associated auxiliary objects such as an underlying model or an objective function that measures the adequation of the model with observed data. It aims at complementing the interface provided by the stats package.

Usage

algorithm(object, ...)

  algorithm(object, ...)<-value

  seeding(object, ...)

  seeding(object, ...)<-value

  niter(object, ...)

  niter(object, ...)<-value

  nrun(object, ...)

  objective(object, ...)

  objective(object, ...)<-value

  runtime(object, ...)

  runtime.all(object, ...)

  seqtime(object, ...)

  modelname(object, ...)

  run(object, y, x, ...)

  logs(object, ...)

  compare(object, ...)

Arguments

Details

algorithm and algorithm<- get/set an object that describes the algorithm used to compute another object, or with which it is associated. It may be a simple character string that gives the algorithm's names, or an object that includes the algorithm's definition itself (e.g. an NMFStrategy object).

seeding get/set the seeding method used to initialise the computation of an object, i.e. usually the function that sets the starting point of an algorithm.

niter and niter<- get/set the number of iterations performed to compute an object. The function niter<- would usually be called just before returning the result of an algorithm, when putting together data about the fit.

nrun returns the number of times the algorithm has been run to compute an object. Usually this will be 1, but may be be more if the algorithm involves multiple starting points.

objective and objective<- get/set the objective function associated with an object. Some methods for objective may also compute the objective value with respect to some target/observed data.

runtime returns the CPU time required to compute an object. This would generally be an object of class proc_time.

runtime.all returns the CPU time required to compute a collection of objects, e.g. a sequence of independent fits.

seqtime returns the sequential CPU time – that would be – required to compute a collection of objects. It would differ from runtime.all if the computations were performed in parallel.

modelname returns a the type of model associated with an object.

run calls the workhorse function that actually implements a strategy/algorithm, and run it on some data object.

logs returns the log messages output during the computation of an object.

compare compares objects obtained from running separate algorithms.

Methods

algorithm

signature(object = "NMFfit"): Returns the name of the algorithm that fitted the NMF model object.

algorithm

signature(object = "NMFList"): Returns the method names used to compute the NMF fits in the list. It returns NULL if the list is empty.

See algorithm,NMFList-method for more details.

algorithm

signature(object = "NMFfitXn"): Returns the name of the common NMF algorithm used to compute all fits stored in object

Since all fits are computed with the same algorithm, this method returns the name of algorithm that computed the first fit. It returns NULL if the object is empty.

algorithm

signature(object = "NMFSeed"): Returns the workhorse function of the seeding method described by object.

algorithm

signature(object = "NMFStrategyFunction"): Returns the single R function that implements the NMF algorithm – as stored in slot algorithm.

algorithm<-

signature(object = "NMFSeed", value = "function"): Sets the workhorse function of the seeding method described by object.

algorithm<-

signature(object = "NMFStrategyFunction", value = "function"): Sets the function that implements the NMF algorithm, stored in slot algorithm.

compare

signature(object = "NMFfitXn"): Compares the fits obtained by separate runs of NMF, in a single call to nmf.

logs

signature(object = "ANY"): Default method that returns the value of attribute/slot 'logs' or, if this latter does not exists, the value of element 'logs' if object is a list. It returns NULL if no logging data was found.

modelname

signature(object = "ANY"): Default method which returns the class name(s) of object. This should work for objects representing models on their own.

For NMF objects, this is the type of NMF model, that corresponds to the name of the S4 sub-class of NMF, inherited by object.

modelname

signature(object = "NMFfit"): Returns the type of a fitted NMF model. It is a shortcut for modelname(fit(object).

modelname

signature(object = "NMFfitXn"): Returns the common type NMF model of all fits stored in object

Since all fits are from the same NMF model, this method returns the model type of the first fit. It returns NULL if the object is empty.

modelname

signature(object = "NMFStrategy"): Returns the model(s) that an NMF algorithm can fit.

niter

signature(object = "NMFfit"): Returns the number of iteration performed to fit an NMF model, typically with function nmf.

Currently this data is stored in slot 'extra', but this might change in the future.

niter<-

signature(object = "NMFfit", value = "numeric"): Sets the number of iteration performed to fit an NMF model.

This function is used internally by the function nmf. It is not meant to be called by the user, except when developing new NMF algorithms implemented as single function, to set the number of iterations performed by the algorithm on the seed, before returning it (see NMFStrategyFunction).

nrun

signature(object = "ANY"): Default method that returns the value of attribute ‘nrun’.

Such an attribute my be attached to objects to keep track of data about the parent fit object (e.g. by method consensus), which can be used by subsequent function calls such as plot functions (e.g. see consensusmap). This method returns NULL if no suitable data was found.

nrun

signature(object = "NMFfitX"): Returns the number of NMF runs performed to create object.

It is a pure virtual method defined to ensure nrun is defined for sub-classes of NMFfitX, which throws an error if called.

Note that because the nmf function allows to run the NMF computation keeping only the best fit, nrun may return a value greater than one, while only the result of the best run is stored in the object (cf. option 'k' in method nmf).

nrun

signature(object = "NMFfit"): This method always returns 1, since an NMFfit object is obtained from a single NMF run.

nrun

signature(object = "NMFfitX1"): Returns the number of NMF runs performed, amongst which object was selected as the best fit.

nrun

signature(object = "NMFfitXn"): Returns the number of runs performed to compute the fits stored in the list (i.e. the length of the list itself).

objective

signature(object = "NMFfit"): Returns the objective function associated with the algorithm that computed the fitted NMF model object, or the objective value with respect to a given target matrix y if it is supplied.

See objective,NMFfit-method for more details.

runtime

signature(object = "NMFfit"): Returns the CPU time required to compute a single NMF fit.

runtime

signature(object = "NMFList"): Returns the CPU time required to compute all NMF fits in the list. It returns NULL if the list is empty. If no timing data are available, the sequential time is returned.

See runtime,NMFList-method for more details.

runtime.all

signature(object = "NMFfit"): Identical to runtime, since their is a single fit.

runtime.all

signature(object = "NMFfitX"): Returns the CPU time required to compute all the NMF runs. It returns NULL if no CPU data is available.

runtime.all

signature(object = "NMFfitXn"): If no time data is available from in slot ‘runtime.all’ and argument null=TRUE, then the sequential time as computed by seqtime is returned, and a warning is thrown unless warning=FALSE.

See runtime.all,NMFfitXn-method for more details.

seeding

signature(object = "NMFfit"): Returns the name of the seeding method that generated the starting point for the NMF algorithm that fitted the NMF model object.

seeding

signature(object = "NMFfitXn"): Returns the name of the common seeding method used the computation of all fits stored in object

Since all fits are seeded using the same method, this method returns the name of the seeding method used for the first fit. It returns NULL if the object is empty.

seqtime

signature(object = "NMFList"): Returns the CPU time that would be required to sequentially compute all NMF fits stored in object.

This method calls the function runtime on each fit and sum up the results. It returns NULL on an empty object.

seqtime

signature(object = "NMFfitXn"): Returns the CPU time that would be required to sequentially compute all NMF fits stored in object.

This method calls the function runtime on each fit and sum up the results. It returns NULL on an empty object.

Interface fo NMF algorithms

This interface is implemented for NMF algorithms by the classes NMFfit, NMFfitX and NMFStrategy, and their respective sub-classes. The examples given in this documentation page are mainly based on this implementation.

Examples

#----------
# modelname,ANY-method
#----------
# get the type of an NMF model
modelname(nmfModel(3))
modelname(nmfModel(3, model='NMFns'))
modelname(nmfModel(3, model='NMFOffset'))

#----------
# modelname,NMFStrategy-method
#----------
# get the type of model(s) associated with an NMF algorithm
modelname( nmfAlgorithm('brunet') )
modelname( nmfAlgorithm('nsNMF') )
modelname( nmfAlgorithm('offset') )

Description

basis and basis<- are S4 generic functions which respectively extract and set the matrix of basis components of an NMF model (i.e. the first matrix factor).

The methods .basis, .coef and their replacement versions are implemented as pure virtual methods for the interface class NMF, meaning that concrete NMF models must provide a definition for their corresponding class (i.e. sub-classes of class NMF). See NMF for more details.

coef and coef<- respectively extract and set the coefficient matrix of an NMF model (i.e. the second matrix factor). For example, in the case of the standard NMF model $V \equiv WH$, the method coef will return the matrix $H$.

.coef and .coef<- are low-level S4 generics that simply return/set coefficient data in an object, leaving some common processing to be performed in coef and coef<-.

Methods coefficients and coefficients<- are simple aliases for methods coef and coef<- respectively.

scoef is similar to coef, but returns the mixture coefficient matrix of an NMF model, with the columns scaled so that they sum up to a given value (1 by default).

Usage

basis(object, ...)

  ## S4 method for signature 'NMF'
basis(object, all = TRUE, ...)

  .basis(object, ...)

  basis(object, ...)<-value

  ## S4 replacement method for signature 'NMF'
basis(object, use.dimnames = TRUE,
    ...)<-value

  .basis(object)<-value

  ## S4 method for signature 'NMF'
loadings(x)

  coef(object, ...)

  ## S4 method for signature 'NMF'
coef(object, all = TRUE, ...)

  .coef(object, ...)

  coef(object, ...)<-value

  ## S4 replacement method for signature 'NMF'
coef(object, use.dimnames = TRUE,
    ...)<-value

  .coef(object)<-value

  coefficients(object, ...)

  ## S4 method for signature 'NMF'
coefficients(object, all = TRUE, ...)

  scoef(object, ...)

  ## S4 method for signature 'NMF'
scoef(object, scale = 1)

  ## S4 method for signature 'matrix'
scoef(object, scale = 1)

Arguments

Details

For example, in the case of the standard NMF model $V \equiv W H$, the method basis will return the matrix $W$.

basis and basis<- are defined for the top virtual class NMF only, and rely internally on the low-level S4 generics .basis and .basis<- respectively that effectively extract/set the coefficient data. These data are post/pre-processed, e.g., to extract/set only their non-fixed terms or check dimension compatibility.

coef and coef<- are S4 methods defined for the corresponding generic functions from package stats (See coef). Similarly to basis and basis<-, they are defined for the top virtual class NMF only, and rely internally on the S4 generics .coef and .coef<- respectively that effectively extract/set the coefficient data. These data are post/pre-processed, e.g., to extract/set only their non-fixed terms or check dimension compatibility.

Methods

basis

signature(object = "ANY"): Default method returns the value of S3 slot or attribute 'basis'. It returns NULL if none of these are set.

Arguments ... are not used by this method.

basis

signature(object = "NMFfitXn"): Returns the basis matrix of the best fit amongst all the fits stored in object. It is a shortcut for basis(fit(object)).

.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 = "NMFstd"): Get the basis matrix in standard NMF models

This function returns slot W of object.

.basis

signature(object = "NMFfit"): Returns the basis matrix from an NMF model fitted with function nmf.

It is a shortcut for .basis(fit(object), ...), dispatching the call to the .basis method of the actual NMF model.

.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 = "NMFstd", value = "matrix"): Set the basis matrix in standard NMF models

This function sets slot W of object.

.basis<-

signature(object = "NMFfit", value = "matrix"): Sets the the basis matrix of an NMF model fitted with function nmf.

It is a shortcut for .basis(fit(object)) <- value, dispatching the call to the .basis<- method of the actual NMF model. It is not meant to be used by the user, except when developing NMF algorithms, to update the basis matrix of the seed object before returning it.

basis<-

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

coef

signature(object = "NMFfitXn"): Returns the coefficient matrix of the best fit amongst all the fits stored in object. It is a shortcut for coef(fit(object)).

.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 = "NMFstd"): Get the mixture coefficient matrix in standard NMF models

This function returns slot H of object.

.coef

signature(object = "NMFfit"): Returns the the coefficient matrix from an NMF model fitted with function nmf.

It is a shortcut for .coef(fit(object), ...), dispatching the call to the .coef method of the actual NMF model.

.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 = "NMFstd", value = "matrix"): Set the mixture coefficient matrix in standard NMF models

This function sets slot H of object.

.coef<-

signature(object = "NMFfit", value = "matrix"): Sets the the coefficient matrix of an NMF model fitted with function nmf.

It is a shortcut for .coef(fit(object)) <- value, dispatching the call to the .coef<- method of the actual NMF model. It is not meant to be used by the user, except when developing NMF algorithms, to update the coefficient matrix in the seed object before returning it.

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.

loadings

signature(x = "NMF"): Method loadings for NMF Models

The method loadings is identical to basis, but do not accept any extra argument.

The method loadings is provided to standardise the NMF interface against the one defined in the stats package, and emphasises the similarities between NMF and PCA or factorial analysis (see loadings).

See Also

Other NMF-interface: .DollarNames,NMF-method, misc, NMF-class, $<-,NMF-method, $,NMF-method, nmfModel, nmfModels, rnmf

Examples

#----------
# scoef
#----------
# Scaled coefficient matrix
x <- rnmf(3, 10, 5)
scoef(x)
scoef(x, 100)

#----------
# .basis,NMFstd-method
#----------
# random standard NMF model
x <- rnmf(3, 10, 5)
basis(x)
coef(x)

# set matrix factors
basis(x) <- matrix(1, nrow(x), nbasis(x))
coef(x) <- matrix(1, nbasis(x), ncol(x))
# set random factors
basis(x) <- rmatrix(basis(x))
coef(x) <- rmatrix(coef(x))

# incompatible matrices generate an error:
try( coef(x) <- matrix(1, nbasis(x)-1, nrow(x)) )
# but the low-level method allow it
.coef(x) <- matrix(1, nbasis(x)-1, nrow(x))
try( validObject(x) )

Description

basiscor computes the correlation matrix between basis vectors, i.e. the columns of its basis matrix – which is the model's first matrix factor.

profcor computes the correlation matrix between basis profiles, i.e. the rows of the coefficient matrix – which is the model's second matrix factor.

Usage

basiscor(x, y, ...)

  profcor(x, y, ...)

Arguments

Details

Each generic has methods defined for computing correlations between NMF models and/or compatible matrices. The computation is performed by the base function cor.

Methods

basiscor

signature(x = "NMF", y = "matrix"): Computes the correlations between the basis vectors of x and the columns of y.

basiscor

signature(x = "matrix", y = "NMF"): Computes the correlations between the columns of x and the the basis vectors 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.

profcor

signature(x = "NMF", y = "matrix"): Computes the correlations between the basis profiles of x and the rows of y.

profcor

signature(x = "matrix", y = "NMF"): Computes the correlations between the rows of x and the basis profiles 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.

Examples

# generate two random NMF models
a <- rnmf(3, 100, 20)
b <- rnmf(3, 100, 20)

# Compute auto-correlations
basiscor(a)
profcor(a)
# Compute correlations with b
basiscor(a, b)
profcor(a, b)

# try to recover the underlying NMF model 'a' from noisy data
res <- nmf(fitted(a) + rmatrix(a), 3)

# Compute correlations with the true model
basiscor(a, res)
profcor(a, res)

# Compute correlations with a random compatible matrix
W <- rmatrix(basis(a))
basiscor(a, W)
identical(basiscor(a, W), basiscor(W, a))

H <- rmatrix(coef(a))
profcor(a, H)
identical(profcor(a, H), profcor(H, a))

Description

The methods dimnames, rownames, colnames and basisnames and their respective replacement form allow to get and set the dimension names of the matrix factors in a NMF model.

dimnames returns all the dimension names in a single list. Its replacement form dimnames<- allows to set all dimension names at once.

rownames, colnames and basisnames provide separate access to each of these dimension names respectively. Their respective replacement form allow to set each dimension names separately.

Usage

basisnames(x, ...)

  basisnames(x, ...)<-value

  ## S4 method for signature 'NMF'
dimnames(x)

  ## S4 replacement method for signature 'NMF'
dimnames(x)<-value

Arguments

Details

The function basisnames is a new S4 generic defined in the package NMF, that returns the names of the basis components of an object. Its default method should work for any object, that has a suitable basis method defined for its class.

The method dimnames is implemented for the base generic dimnames, which make the base function rownames and colnames work directly.

Overall, these methods behave as their equivalent on matrix objects. The function basisnames<- ensures that the dimension names are handled in a consistent way on both factors, enforcing the names on both matrix factors simultaneously.

The function basisnames<- is a new S4 generic defined in the package NMF, that sets the names of the basis components of an object. Its default method should work for any object, that has suitable basis<- and coef<- methods method defined for its class.

Methods

basisnames

signature(x = "ANY"): Default method which returns the column names of the basis matrix extracted from x, using the basis method.

For NMF objects these also correspond to the row names of the coefficient matrix.

basisnames<-

signature(x = "ANY"): Default method which sets, respectively, the row and the column names of the basis matrix and coefficient matrix of x to value.

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.

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.

Examples

# create a random NMF object
a <- rnmf(2, 5, 3)

# set dimensions
dims <- list( features=paste('f', 1:nrow(a), sep='')
				, samples=paste('s', 1:ncol(a), sep='')
				, basis=paste('b', 1:nbasis(a), sep='') )
dimnames(a) <- dims
dimnames(a)
basis(a)
coef(a)

# access the dimensions separately
rownames(a)
colnames(a)
basisnames(a)

# set only the first dimension (rows of basis): the other two dimnames are set to NULL
dimnames(a) <- dims[1]
dimnames(a)
basis(a)
coef(a)

# set only the two first dimensions (rows and columns of basis and coef respectively):
# the basisnames are set to NULL
dimnames(a) <- dims[1:2]
dimnames(a)
basis(a)

# reset the dimensions
dimnames(a) <- NULL
dimnames(a)
basis(a)
coef(a)

# set each dimensions separately
rownames(a) <- paste('X', 1:nrow(a), sep='') # only affect rows of basis
basis(a)

colnames(a) <- paste('Y', 1:ncol(a), sep='') # only affect columns of coef
coef(a)

basisnames(a) <- paste('Z', 1:nbasis(a), sep='') # affect both basis and coef matrices
basis(a)
coef(a)

Description

The package NMF provides an optional layer for working with common objects and functions defined in the Bioconductor platform.

Details

It provides:

• computation functions that support ExpressionSet objects as inputs.

• aliases and methods for generic functions defined and widely used by Bioconductor base packages.

• specialised visualisation methods that adapt the titles and legend using bioinformatics terminology.

• functions to link the results with annotations, etc...

Description

canFit is an S4 generic that tests if an algorithm can fit a particular model.

Usage

canFit(x, y, ...)

  ## S4 method for signature 'NMFStrategy,character'
canFit(x, y,
    exact = FALSE)

Arguments

Methods

canFit

signature(x = "NMFStrategy", y = "character"): Tells if an NMF algorithm can fit a given class of NMF models

canFit

signature(x = "NMFStrategy", y = "NMF"): Tells if an NMF algorithm can fit the same class of models as y

canFit

signature(x = "character", y = "ANY"): Tells if a registered NMF algorithm can fit a given NMF model

See Also

Other regalgo: nmfAlgorithm

Description

The functions documented here allow to compare the fits computed in different NMF runs. The fits do not need to be from the same algorithm, nor have the same dimension.

Usage

## S4 method for signature 'NMFfit'
compare(object, ...)

  ## S4 method for signature 'list'
compare(object, ...)

  ## S4 method for signature 'NMFList'
summary(object, sort.by = NULL,
    select = NULL, ...)

  ## S4 method for signature 'NMFList,missing'
plot(x, y, skip = -1, ...)

  ## S4 method for signature 'NMF.rank'
consensusmap(object, ...)

  ## S4 method for signature 'list'
consensusmap(object, layout,
    Rowv = FALSE, main = names(object), ...)

Arguments

Details

The methods compare enables to compare multiple NMF fits either passed as arguments or as a list of fits. These methods eventually call the method summary,NMFList, so that all its arguments can be passed named in ....

Methods

compare

signature(object = "NMFfit"): Compare multiple NMF fits passed as arguments.

compare

signature(object = "list"): Compares multiple NMF fits passed as a standard list.

consensusmap

signature(object = "NMF.rank"): Draw a single plot with a heatmap of the consensus matrix obtained for each value of the rank, in the range tested with nmfEstimateRank.

consensusmap

signature(object = "list"): Draw a single plot with a heatmap of the consensus matrix of each element in the list object.

plot

signature(x = "NMFList", y = "missing"): plot plot on a single graph the residuals tracks for each fit in x. See function nmf for details on how to enable the tracking of residuals.

summary

signature(object = "NMFList"): summary,NMFList computes summary measures for each NMF result in the list and return them in rows in a data.frame. By default all the measures are included in the result, and NA values are used where no data is available or the measure does not apply to the result object (e.g. the dispersion for single' NMF runs is not meaningful). This method is very useful to compare and evaluate the performance of different algorithms.

Examples

#----------
# compare,NMFfit-method
#----------
x <- rmatrix(20,10)
res <- nmf(x, 3)
res2 <- nmf(x, 2, 'lee')

# compare arguments
compare(res, res2, target=x)

#----------
# compare,list-method
#----------
# compare elements of a list
compare(list(res, res2), target=x)

Description

connectivity is an S4 generic that computes the connectivity matrix based on the clustering of samples obtained from a model's predict method.

The consensus matrix has been proposed by Brunet et al. (2004) to help visualising and measuring the stability of the clusters obtained by NMF approaches. For objects of class NMF (e.g. results of a single NMF run, or NMF models), the consensus matrix reduces to the connectivity matrix.

Usage

connectivity(object, ...)

  ## S4 method for signature 'NMF'
connectivity(object, no.attrib = FALSE)

  consensus(object, ...)

Arguments

Details

The connectivity matrix of a given partition of a set of samples (e.g. given as a cluster membership index) is the matrix $C$ containing only 0 or 1 entries such that:

$C_{ij} = \left\{\begin{array}{l} 1\mbox{ if sample }i\mbox{ belongs to the same cluster as sample }j\\ 0\mbox{ otherwise} \end{array}\right..$

Value

a square matrix of dimension the number of samples in the model, full of 0s or 1s.

Methods

connectivity

signature(object = "ANY"): Default method which computes the connectivity matrix using the result of predict(x, ...) as cluster membership index.

connectivity

signature(object = "factor"): Computes the connectivity matrix using x as cluster membership index.

connectivity

signature(object = "numeric"): Equivalent to connectivity(as.factor(x)).

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 = "NMFfitX"): Pure virtual method defined to ensure consensus is defined for sub-classes of NMFfitX. It throws an error if called.

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.

consensus

signature(object = "NMFfitX1"): The result is the matrix stored in slot ‘consensus’. This method returns NULL if the consensus matrix is empty.

See consensus,NMFfitX1-method for more details.

consensus

signature(object = "NMFfitXn"): This method returns NULL on an empty object. The result is a matrix with several attributes attached, that are used by plotting functions such as consensusmap to annotate the plots.

See consensus,NMFfitXn-method for more details.

References

Brunet J, Tamayo P, Golub TR and Mesirov JP (2004). "Metagenes and molecular pattern discovery using matrix factorization." _Proceedings of the National Academy of Sciences of the United States of America_, *101*(12), pp. 4164-9. ISSN 0027-8424, <URL: http://dx.doi.org/10.1073/pnas.0308531101>, <URL: http://www.ncbi.nlm.nih.gov/pubmed/15016911>.

See Also

predict

Examples

#----------
# connectivity,ANY-method
#----------
# clustering of random data
h <- hclust(dist(rmatrix(10,20)))
connectivity(cutree(h, 2))

#----------
# connectivity,factor-method
#----------
connectivity(gl(2, 4))

Description

The result is the matrix stored in slot ‘consensus’. This method returns NULL if the consensus matrix is empty.

Usage

## S4 method for signature 'NMFfitX1'
consensus(object, no.attrib = FALSE)

Arguments

Description

This method returns NULL on an empty object. The result is a matrix with several attributes attached, that are used by plotting functions such as consensusmap to annotate the plots.

Usage

## S4 method for signature 'NMFfitXn'
consensus(object, ...,
    no.attrib = FALSE)

Arguments

Description

The function consensushc computes the hierarchical clustering of a consensus matrix, using the matrix itself as a similarity matrix and average linkage. It is

Usage

consensushc(object, ...)

  ## S4 method for signature 'matrix'
consensushc(object,
    method = "average", dendrogram = TRUE)

  ## S4 method for signature 'NMFfitX'
consensushc(object,
    what = c("consensus", "fit"), ...)

Arguments

Value

an object of class dendrogram or hclust depending on the value of argument dendrogram.

Methods

consensushc

signature(object = "matrix"): Workhorse method for matrices.

consensushc

signature(object = "NMF"): Compute the hierarchical clustering on the connectivity matrix of object.

consensushc

signature(object = "NMFfitX"): Compute the hierarchical clustering on the consensus matrix of object, or on the connectivity matrix of the best fit in object.

Description

The function cophcor computes the cophenetic correlation coefficient from consensus matrix object, e.g. as obtained from multiple NMF runs.

Usage

cophcor(object, ...)

  ## S4 method for signature 'matrix'
cophcor(object, linkage = "average")

Arguments

Details

The cophenetic correlation coeffificient is based on the consensus matrix (i.e. the average of connectivity matrices) and was proposed by Brunet et al. (2004) to measure the stability of the clusters obtained from NMF.

It is defined as the Pearson correlation between the samples' distances induced by the consensus matrix (seen as a similarity matrix) and their cophenetic distances from a hierachical clustering based on these very distances (by default an average linkage is used). See Brunet et al. (2004).

Methods

cophcor

signature(object = "matrix"): Workhorse method for matrices.

cophcor

signature(object = "NMFfitX"): Computes the cophenetic correlation coefficient on the consensus matrix of object. All arguments in ... are passed to the method cophcor,matrix.

References

Brunet J, Tamayo P, Golub TR and Mesirov JP (2004). "Metagenes and molecular pattern discovery using matrix factorization." _Proceedings of the National Academy of Sciences of the United States of America_, *101*(12), pp. 4164-9. ISSN 0027-8424, <URL: http://dx.doi.org/10.1073/pnas.0308531101>, <URL: http://www.ncbi.nlm.nih.gov/pubmed/15016911>.

See Also

cophenetic

Description

The NMF package defines methods for the generic deviance from the package stats, to compute approximation errors between NMF models and matrices, using a variety of objective functions.

nmfDistance returns a function that computes the distance between an NMF model and a compatible matrix.

Usage

deviance(object, ...)

  ## S4 method for signature 'NMF'
deviance(object, y,
    method = c("", "KL", "euclidean"), ...)

  nmfDistance(method = c("", "KL", "euclidean"))

  ## S4 method for signature 'NMFfit'
deviance(object, y, method, ...)

  ## S4 method for signature 'NMFStrategy'
deviance(object, x, y, ...)

Arguments

Value

deviance returns a nonnegative numerical value

nmfDistance returns a function with least two arguments: an NMF model and a matrix.

Methods

deviance

signature(object = "NMF"): Computes the distance between a matrix and the estimate of an NMF model.

deviance

signature(object = "NMFfit"): Returns the deviance of a fitted NMF model.

This method returns the final residual value if the target matrix y is not supplied, or the approximation error between the fitted NMF model stored in object and y. In this case, the computation is performed using the objective function method if not missing, or the objective of the algorithm that fitted the model (stored in slot 'distance').

If not computed by the NMF algorithm itself, the value is automatically computed at the end of the fitting process by the function nmf, using the objective function associated with the NMF algorithm, so that it should always be available.

deviance

signature(object = "NMFfitX"): Returns the deviance achieved by the best fit object, i.e. the lowest deviance achieved across all NMF runs.

deviance

signature(object = "NMFStrategy"): Computes the value of the objective function between the estimate x and the target y.

See Also

Other stats: deviance,NMF-method, hasTrack, residuals, residuals<-, trackError

Description

Computes the dispersion coefficient of a – consensus – matrix object, generally obtained from multiple NMF runs.

Usage

dispersion(object, ...)

Arguments

Details

The dispersion coefficient is based on the consensus matrix (i.e. the average of connectivity matrices) and was proposed by Kim et al. (2007) to measure the reproducibility of the clusters obtained from NMF.

It is defined as:

$\rho = \sum_{i,j=1}^n 4 (C_{ij} - \frac{1}{2})^2 ,$

where $n$ is the total number of samples.

By construction, $0 \leq \rho \leq 1$ and $\rho = 1$ only for a perfect consensus matrix, where all entries 0 or 1. A perfect consensus matrix is obtained only when all the connectivity matrices are the same, meaning that the algorithm gave the same clusters at each run. See Kim et al. (2007).

Methods

dispersion

signature(object = "matrix"): Workhorse method that computes the dispersion on a given matrix.

dispersion

signature(object = "NMFfitX"): Computes the dispersion on the consensus matrix obtained from multiple NMF runs.

References

Kim H and Park H (2007). "Sparse non-negative matrix factorizations via alternating non-negativity-constrained least squares for microarray data analysis." _Bioinformatics (Oxford, England)_, *23*(12), pp. 1495-502. ISSN 1460-2059, <URL: http://dx.doi.org/10.1093/bioinformatics/btm134>, <URL: http://www.ncbi.nlm.nih.gov/pubmed/17483501>.

Description

This data comes originally from the gene expression data from Golub et al. (1999). The version included in the package is the one used and referenced in Brunet et al. (2004). The samples are from 27 patients with acute lymphoblastic leukemia (ALL) and 11 patients with acute myeloid leukemia (AML).

Format

There are 3 covariates listed.

• Samples: The original sample labels.

• ALL.AML: Whether the patient had AML or ALL. It is a factor with levels c('ALL', 'AML').

• Cell: ALL arises from two different types of lymphocytes (T-cell and B-cell). This specifies which for the ALL patients; There is no such information for the AML samples. It is a factor with levels c('T-cell', 'B-cell', NA).

Details

The samples were assayed using Affymetrix Hgu6800 chips and the original data on the expression of 7129 genes (Affymetrix probes) are available on the Broad Institute web site (see references below).

The data in esGolub were obtained from the web page related to the paper from Brunet et al. (2004), which describes an application of Nonnegative Matrix Factorization to gene expression clustering. (see link in section Source).

They contain the 5,000 most highly varying genes according to their coefficient of variation, and were installed in an object of class ExpressionSet.

Source

Original data from Golub et al.:
http://www-genome.wi.mit.edu/mpr/data_set_ALL_AML.html

References

Golub TR, Slonim DK, Tamayo P, Huard C, Gaasenbeek M, Mesirov JP, Coller H, Loh ML, Downing JR, Caligiuri Ma, Bloomfield CD and Lander ES (1999). "Molecular classification of cancer: class discovery and class prediction by gene expression monitoring." _Science (New York, N.Y.)_, *286*(5439), pp. 531-7. ISSN 0036-8075, <URL: http://www.ncbi.nlm.nih.gov/pubmed/10521349>.

Brunet J, Tamayo P, Golub TR and Mesirov JP (2004). "Metagenes and molecular pattern discovery using matrix factorization." _Proceedings of the National Academy of Sciences of the United States of America_, *101*(12), pp. 4164-9. ISSN 0027-8424, <URL: http://dx.doi.org/10.1073/pnas.0308531101>, <URL: http://www.ncbi.nlm.nih.gov/pubmed/15016911>.

Examples

# requires package Biobase to be installed
if(requireNamespace("Biobase", quietly=TRUE)){

	data(esGolub)
	esGolub
	## Not run: pData(esGolub)

}

Description

This function solves the following nonnegative least square linear problem using normal equations and the fast combinatorial strategy from Van Benthem et al. (2004):

$\begin{array}{l} \min \|Y - X K\|_F\\ \mbox{s.t. } K>=0 \end{array}$

where $Y$ and $X$ are two real matrices of dimension $n \times p$ and $n \times r$ respectively, and $\|.\|_F$ is the Frobenius norm.

The algorithm is very fast compared to other approaches, as it is optimised for handling multiple right-hand sides.

Usage

fcnnls(x, y, ...)

  ## S4 method for signature 'matrix,matrix'
fcnnls(x, y, verbose = FALSE,
    pseudo = TRUE, ...)

Arguments

Details

Within the NMF package, this algorithm is used internally by the SNMF/R(L) algorithm from Kim et al. (2007) to solve general Nonnegative Matrix Factorization (NMF) problems, using alternating nonnegative constrained least-squares. That is by iteratively and alternatively estimate each matrix factor.

The algorithm is an active/passive set method, which rearrange the right-hand side to reduce the number of pseudo-inverse calculations. It uses the unconstrained solution $K_u$ obtained from the unconstrained least squares problem, i.e. $\min \|Y - X K\|_F^2$ , so as to determine the initial passive sets.

The function fcnnls is provided separately so that it can be used to solve other types of nonnegative least squares problem. For faster computation, when multiple nonnegative least square fits are needed, it is recommended to directly use the function .fcnnls.

The code of this function is a port from the original MATLAB code provided by Kim et al. (2007).

Value

A list containing the following components:

Methods

fcnnls

signature(x = "matrix", y = "matrix"): This method wraps a call to the internal function .fcnnls, and formats the results in a similar way as other lest-squares methods such as lm.

fcnnls

signature(x = "numeric", y = "matrix"): Shortcut for fcnnls(as.matrix(x), y, ...).

fcnnls

signature(x = "ANY", y = "numeric"): Shortcut for fcnnls(x, as.matrix(y), ...).

Author(s)

Original MATLAB code : Van Benthem and Keenan

Adaption of MATLAB code for SNMF/R(L): H. Kim

Adaptation to the NMF package framework: Renaud Gaujoux

References

Original MATLAB code from Van Benthem and Keenan, slightly modified by H. Kim:(http://www.cc.gatech.edu/~hpark/software/fcnnls.m)

Van Benthem M and Keenan MR (2004). "Fast algorithm for the solution of large-scale non-negativity-constrained least squares problems." _Journal of Chemometrics_, *18*(10), pp. 441-450. ISSN 0886-9383, <URL: http://dx.doi.org/10.1002/cem.889>, <URL: http://doi.wiley.com/10.1002/cem.889>.

Kim H and Park H (2007). "Sparse non-negative matrix factorizations via alternating non-negativity-constrained least squares for microarray data analysis." _Bioinformatics (Oxford, England)_, *23*(12), pp. 1495-502. ISSN 1460-2059, <URL: http://dx.doi.org/10.1093/bioinformatics/btm134>, <URL: http://www.ncbi.nlm.nih.gov/pubmed/17483501>.

See Also

nmf

Examples

## Define a random nonnegative matrix matrix
n <- 200; p <- 20; r <- 3
V <- rmatrix(n, p)

## Compute the optimal matrix K for a given X matrix
X <- rmatrix(n, r)
res <- fcnnls(X, V)

## Compute the same thing using the Moore-Penrose generalized pseudoinverse
res <- fcnnls(X, V, pseudo=TRUE)

## It also works in the case of single vectors
y <- runif(n)
res <- fcnnls(X, y)
# or
res <- fcnnls(X[,1], y)

Description

The function featureScore implements different methods to computes basis-specificity scores for each feature in the data.

The function extractFeatures implements different methods to select the most basis-specific features of each basis component.

Usage

featureScore(object, ...)

  ## S4 method for signature 'matrix'
featureScore(object,
    method = c("kim", "max"))

  extractFeatures(object, ...)

  ## S4 method for signature 'matrix'
extractFeatures(object,
    method = c("kim", "max"),
    format = c("list", "combine", "subset"), nodups = TRUE)

Arguments

Details

One of the properties of Nonnegative Matrix Factorization is that is tend to produce sparse representation of the observed data, leading to a natural application to bi-clustering, that characterises groups of samples by a small number of features.

In NMF models, samples are grouped according to the basis components that contributes the most to each sample, i.e. the basis components that have the greatest coefficient in each column of the coefficient matrix (see predict,NMF-method). Each group of samples is then characterised by a set of features selected based on basis-specifity scores that are computed on the basis matrix.

Value

featureScore returns a numeric vector of the length the number of rows in object (i.e. one score per feature).

extractFeatures returns the selected features as a list of indexes, a single integer vector or an object of the same class as object that only contains the selected features.

Methods

extractFeatures

signature(object = "matrix"): Select features on a given matrix, that contains the basis component in columns.

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 = "matrix"): Computes feature scores on a given matrix, that contains the basis component in columns.

featureScore

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

Feature scores

The function featureScore can compute basis-specificity scores using the following methods:

‘kim’

Method defined by Kim et al. (2007).

The score for feature $i$ is defined as:

$S_i = 1 + \frac{1}{\log_2 k} \sum_{q=1}^k p(i,q) \log_2 p(i,q)$

,

where $p(i,q)$ is the probability that the $i$-th feature contributes to basis $q$:

$p(i,q) = \frac{W(i,q)}{\sum_{r=1}^k W(i,r)}$

The feature scores are real values within the range [0,1]. The higher the feature score the more basis-specific the corresponding feature.

‘max’

Method defined by Carmona-Saez et al. (2006).

The feature scores are defined as the row maximums.

Feature selection

The function extractFeatures can select features using the following methods:

‘kim’

uses Kim et al. (2007) scoring schema and feature selection method.

The features are first scored using the function featureScore with method ‘kim’. Then only the features that fulfil both following criteria are retained:

• score greater than $\hat{\mu} + 3 \hat{\sigma}$, where $\hat{\mu}$ and $\hat{\sigma}$ are the median and the median absolute deviation (MAD) of the scores respectively;

• the maximum contribution to a basis component is greater than the median of all contributions (i.e. of all elements of W).

‘max’

uses the selection method used in the bioNMF software package and described in Carmona-Saez et al. (2006).

For each basis component, the features are first sorted by decreasing contribution. Then, one selects only the first consecutive features whose highest contribution in the basis matrix is effectively on the considered basis.

References

Kim H and Park H (2007). "Sparse non-negative matrix factorizations via alternating non-negativity-constrained least squares for microarray data analysis." _Bioinformatics (Oxford, England)_, *23*(12), pp. 1495-502. ISSN 1460-2059, <URL: http://dx.doi.org/10.1093/bioinformatics/btm134>, <URL: http://www.ncbi.nlm.nih.gov/pubmed/17483501>.

Carmona-Saez P, Pascual-Marqui RD, Tirado F, Carazo JM and Pascual-Montano A (2006). "Biclustering of gene expression data by Non-smooth Non-negative Matrix Factorization." _BMC bioinformatics_, *7*, pp. 78. ISSN 1471-2105, <URL: http://dx.doi.org/10.1186/1471-2105-7-78>, <URL: http://www.ncbi.nlm.nih.gov/pubmed/16503973>.

Examples

# random NMF model
x <- rnmf(3, 50,20)

# probably no feature is selected
extractFeatures(x)
# extract top 5 for each basis
extractFeatures(x, 5L)
# extract features that have a relative basis contribution above a threshold
extractFeatures(x, 0.5)
# ambiguity?
extractFeatures(x, 1) # means relative contribution above 100%
extractFeatures(x, 1L) # means top contributing feature in each component

Description

The functions fit and minfit are S4 genetics that extract the best model object and the best fit object respectively, from a collection of models or from a wrapper object.

fit<- sets the fitted model in a fit object. It is meant to be called only when developing new NMF algorithms, e.g. to update the value of the model stored in the starting point.

Usage

fit(object, ...)

  fit(object)<-value

  minfit(object, ...)

Arguments

Details

A fit object differs from a model object in that it contains data about the fit, such as the initial RNG settings, the CPU time used, etc..., while a model object only contains the actual modelling data such as regression coefficients, loadings, etc...

That best model is generally defined as the one that achieves the maximum/minimum some quantitative measure, amongst all models in a collection.

In the case of NMF models, the best model is the one that achieves the best approximation error, according to the objective function associated with the algorithm that performed the fit(s).

Methods

fit

signature(object = "NMFfit"): Returns the NMF model object stored in slot 'fit'.

fit

signature(object = "NMFfitX"): Returns the model object that achieves the lowest residual approximation error across all the runs.

It is a pure virtual method defined to ensure fit is defined for sub-classes of NMFfitX, which throws an error if called.

fit

signature(object = "NMFfitX1"): Returns the model object associated with the best fit, amongst all the runs performed when fitting object.

Since NMFfitX1 objects only hold the best fit, this method simply returns the NMF model fitted by object – that is stored in slot ‘fit’.

fit

signature(object = "NMFfitXn"): Returns the best NMF fit object amongst all the fits stored in object, i.e. the fit that achieves the lowest estimation residuals.

fit<-

signature(object = "NMFfit", value = "NMF"): Updates the NMF model object stored in slot 'fit' with a new value.

minfit

signature(object = "NMFfit"): Returns the object its self, since there it is the result of a single NMF run.

minfit

signature(object = "NMFfitX"): Returns the fit object that achieves the lowest residual approximation error across all the runs.

It is a pure virtual method defined to ensure minfit is defined for sub-classes of NMFfitX, which throws an error if called.

minfit

signature(object = "NMFfitX1"): Returns the fit object associated with the best fit, amongst all the runs performed when fitting object.

Since NMFfitX1 objects only hold the best fit, this method simply returns object coerced into an NMFfit object.

minfit

signature(object = "NMFfitXn"): Returns the best NMF model in the list, i.e. the run that achieved the lower estimation residuals.

The model is selected based on its deviance value.

Description

Computes the estimated target matrix based on a given NMF model. The estimation depends on the underlying NMF model. For example in the standard model $V \equiv W H$, the target matrix is estimated by the matrix product $W H$. In other models, the estimate may depend on extra parameters/matrix (cf. Non-smooth NMF in NMFns-class).

Usage

fitted(object, ...)

  ## S4 method for signature 'NMFstd'
fitted(object, W, H, ...)

  ## S4 method for signature 'NMFOffset'
fitted(object, W, H,
    offset = object@offset)

  ## S4 method for signature 'NMFns'
fitted(object, W, H, S, ...)

Arguments

Details

This function is a S4 generic function imported from fitted in the package stats. It is implemented as a pure virtual method for objects of class NMF, meaning that concrete NMF models must provide a definition for their corresponding class (i.e. sub-classes of class NMF). See NMF for more details.

Value

the target matrix estimate as fitted by the model object

Methods

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.

fitted

signature(object = "NMFstd"): Compute the target matrix estimate in standard NMF models.

The estimate matrix is computed as the product of the two matrix slots W and H:

$\hat{V} = W H$

fitted

signature(object = "NMFOffset"): Computes the target matrix estimate for an NMFOffset object.

The estimate is computed as:

$W H + offset$

fitted

signature(object = "NMFns"): Compute estimate for an NMFns object, according to the Nonsmooth NMF model (cf. NMFns-class).

Extra arguments in ... are passed to method smoothing, and are typically used to pass a value for theta, which is used to compute the smoothing matrix instead of the one stored in object.

fitted

signature(object = "NMFfit"): Computes and return the estimated target matrix from an NMF model fitted with function nmf.

It is a shortcut for fitted(fit(object), ...), dispatching the call to the fitted method of the actual NMF model.

Examples

# random standard NMF model
x <- rnmf(3, 10, 5)
all.equal(fitted(x), basis(x) %*% coef(x))

Description

The nmf function returns objects that contain embedded RNG data, that can be used to exactly reproduce any computation. These data can be extracted using dedicated methods for the S4 generics getRNG and getRNG1.

Usage

getRNG1(object, ...)

  .getRNG(object, ...)

Arguments

Methods

.getRNG

signature(object = "NMFfitXn"): Returns the RNG settings used for the best fit.

This method throws an error if the object is empty.

getRNG1

signature(object = "NMFfitX"): Returns the RNG settings used for the first NMF run of multiple NMF runs.

getRNG1

signature(object = "NMFfitX1"): Returns the RNG settings used to compute the first of all NMF runs, amongst which object was selected as the best fit.

getRNG1

signature(object = "NMFfitXn"): Returns the RNG settings used for the first run.

This method throws an error if the object is empty.

Examples

# For multiple NMF runs, the RNG settings used for the first run is also stored
V <- rmatrix(20,10)
res <- nmf(V, 3, nrun=3)
# RNG used for the best fit
getRNG(res)
# RNG used for the first of all fits
getRNG1(res)
# they may differ if the best fit is not the first one
rng.equal(res, getRNG1(res))

Description

The NMF package ships an advanced heatmap engine implemented by the function aheatmap. Some convenience heatmap functions have been implemented for NMF models, which redefine default values for some of the arguments of aheatmap, hence tuning the output specifically for NMF models.

Usage

basismap(object, ...)

  ## S4 method for signature 'NMF'
basismap(object, color = "YlOrRd:50",
    scale = "r1", Rowv = TRUE, Colv = NA,
    subsetRow = FALSE, annRow = NA, annCol = NA,
    tracks = "basis", main = "Basis components",
    info = FALSE, ...)

  coefmap(object, ...)

  ## S4 method for signature 'NMF'
coefmap(object, color = "YlOrRd:50",
    scale = "c1", Rowv = NA, Colv = TRUE, annRow = NA,
    annCol = NA, tracks = "basis",
    main = "Mixture coefficients", info = FALSE, ...)

  consensusmap(object, ...)

  ## S4 method for signature 'NMFfitX'
consensusmap(object, annRow = NA,
    annCol = NA,
    tracks = c("basis:", "consensus:", "silhouette:"),
    main = "Consensus matrix", info = FALSE, ...)

  ## S4 method for signature 'matrix'
consensusmap(object,
    color = "-RdYlBu",
    distfun = function(x) as.dist(1 - x),
    hclustfun = "average", Rowv = TRUE, Colv = "Rowv",
    main = if (is.null(nr) || nr > 1) "Consensus matrix" else "Connectiviy matrix",
    info = FALSE, ...)

  ## S4 method for signature 'NMFfitX'
coefmap(object, Colv = TRUE,
    annRow = NA, annCol = NA,
    tracks = c("basis", "consensus:"), ...)

Arguments

Details

IMPORTANT: although they essentially have the same set of arguments, their order sometimes differ between them, as well as from aheatmap. We therefore strongly recommend to use fully named arguments when calling these functions.

basimap default values for the following arguments of aheatmap:

• the color palette;

• the scaling specification, which by default scales each row separately so that they sum up to one (scale='r1');

• the column ordering which is disabled;

• allowing for passing feature extraction methods in argument subsetRow, that are passed to extractFeatures. See argument description here and therein.

• the addition of a default named annotation track, that shows the dominant basis component for each row (i.e. each feature).

  This track is specified in argument tracks (see its argument description). By default, a matching column annotation track is also displayed, but may be disabled using tracks=':basis'.

• a suitable title and extra information like the fitting algorithm, when object is a fitted NMF model.

coefmap redefines default values for the following arguments of aheatmap:

• the color palette;

• the scaling specification, which by default scales each column separately so that they sum up to one (scale='c1');

• the row ordering which is disabled;

• the addition of a default annotation track, that shows the most contributing basis component for each column (i.e. each sample).

  This track is specified in argument tracks (see its argument description). By default, a matching row annotation track is also displayed, but can be disabled using tracks='basis:'.

• a suitable title and extra information like the fitting algorithm, when object is a fitted NMF model.

consensusmap redefines default values for the following arguments of aheatmap:

• the colour palette;

• the column ordering which is set equal to the row ordering, since a consensus matrix is symmetric;

• the distance and linkage methods used to order the rows (and columns). The default is to use 1 minus the consensus matrix itself as distance, and average linkage.

• the addition of two special named annotation tracks, 'basis:' and 'consensus:', that show, for each column (i.e. each sample), the dominant basis component in the best fit and the hierarchical clustering of the consensus matrix respectively (using 1-consensus as distance and average linkage).

  These tracks are specified in argument tracks, which behaves as in basismap.

• a suitable title and extra information like the type of NMF model or the fitting algorithm, when object is a fitted NMF model.

Methods

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

basismap

signature(object = "NMFfitX"): Plots a heatmap of the basis matrix of the best fit in object.

coefmap

signature(object = "NMF"): The default method for NMF objects has special default values for some arguments of aheatmap (see argument description).

coefmap

signature(object = "NMFfitX"): Plots a heatmap of the coefficient matrix of the best fit in object.

This method adds:

• an extra special column annotation track for multi-run NMF fits, 'consensus:', that shows the consensus cluster associated to each sample.

• a column sorting schema 'consensus' that can be passed to argument Colv and orders the columns using the hierarchical clustering of the consensus matrix with average linkage, as returned by consensushc(object). This is also the ordering that is used by default for the heatmap of the consensus matrix as ploted by consensusmap.

consensusmap

signature(object = "NMFfitX"): Plots a heatmap of the consensus matrix obtained when fitting an NMF model with multiple runs.

consensusmap

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

consensusmap

signature(object = "matrix"): Main method that redefines default values for arguments of aheatmap.

Examples

#----------
# heatmap-NMF
#----------
## More examples are provided in demo `heatmaps`
## Not run: 
demo(heatmaps)

## End(Not run)
##

# random data with underlying NMF model
v <- syntheticNMF(20, 3, 10)
# estimate a model
x <- nmf(v, 3)

#----------
# basismap
#----------
# show basis matrix
basismap(x)
## Not run: 
# without the default annotation tracks
basismap(x, tracks=NA)

## End(Not run)

#----------
# coefmap
#----------
# coefficient matrix
coefmap(x)
## Not run: 
# without the default annotation tracks
coefmap(x, tracks=NA)

## End(Not run)

#----------
# consensusmap
#----------
## Not run: 
res <- nmf(x, 3, nrun=3)
consensusmap(res)

## End(Not run)

Description

Formula-based NMF models may contain fixed basis and/or coefficient terms. The functions documented here provide access to these data, which are read-only and defined when the model object is instantiated (e.g., see nmfModel,formula-method).

ibterms, icterms and iterms respectively return the indexes of the fixed basis terms, the fixed coefficient terms and all fixed terms, within the basis and/or coefficient matrix of an NMF model.

nterms, nbterms, and ncterms return, respectively, the number of all fixed terms, fixed basis terms and fixed coefficient terms in an NMF model. In particular: i.e. nterms(object) = nbterms(object) + ncterms(object).

bterms and cterms return, respectively, the primary data for fixed basis and coefficient terms in an NMF model – as stored in slots bterms and cterms . These are factors or numeric vectors which define fixed basis components, e.g., used for defining separate offsets for different a priori groups of samples, or to incorporate/correct for some known covariate.

ibasis and icoef return, respectively, the indexes of all latent basis vectors and estimated coefficients within the basis or coefficient matrix of an NMF model.

Usage

ibterms(object, ...)

  icterms(object, ...)

  iterms(object, ...)

  nterms(object)

  nbterms(object)

  ncterms(object)

  bterms(object)

  cterms(object)

  ibasis(object, ...)

  icoef(object, ...)

Arguments

Methods

ibterms

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

ibterms

signature(object = "NMFstd"): Method for standard NMF models, which returns the integer vector that is stored in slot ibterms when a formula-based NMF model is instantiated.

ibterms

signature(object = "NMFfit"): Method for single NMF fit objects, which returns the indexes of fixed basis terms from the fitted model.

ibterms

signature(object = "NMFfitX"): Method for multiple NMF fit objects, which returns the indexes of fixed basis terms from the best fitted model.

icterms

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

icterms

signature(object = "NMFstd"): Method for standard NMF models, which returns the integer vector that is stored in slot icterms when a formula-based NMF model is instantiated.

icterms

signature(object = "NMFfit"): Method for single NMF fit objects, which returns the indexes of fixed coefficient terms from the fitted model.

Description

The functions documented here tests different characteristics of NMF objects.

is.nmf tests if an object is an NMF model or a class that extends the class NMF.

hasBasis tests whether an objects contains a basis matrix – returned by a suitable method basis – with at least one row.

hasBasis tests whether an objects contains a coefficient matrix – returned by a suitable method coef – with at least one column.

is.partial.nmf tests whether an NMF model object contains either an empty basis or coefficient matrix. It is a shorcut for !hasCoef(x) || !hasBasis(x).

Usage

is.nmf(x)

  is.empty.nmf(x, ...)

  hasBasis(x)

  hasCoef(x)

  is.partial.nmf(x)

  isNMFfit(object, recursive = TRUE)

Arguments

Details

is.nmf tests if object is the name of a class (if a character string), or inherits from a class, that extends NMF.

is.empty.nmf returns TRUE if the basis and coefficient matrices of x have respectively zero rows and zero columns. It returns FALSE otherwise.

In particular, this means that an empty model can still have a non-zero number of basis components, i.e. a factorization rank that is not null. This happens, for example, in the case of NMF models created calling the factory method nmfModel with a value only for the factorization rank.

isNMFfit checks if object inherits from class NMFfit or NMFfitX, which are the two types of objects returned by the function nmf. If object is a plain list and recursive=TRUE, then the test is performed on each element of the list, and the return value is a logical vector (or a list if object is a list of list) of the same length as object.

Value

isNMFfit returns a logical vector (or a list if object is a list of list) of the same length as object.

Note

The function is.nmf does some extra work with the namespace as this function needs to return correct results even when called in .onLoad. See discussion on r-devel: https://stat.ethz.ch/pipermail/r-devel/2011-June/061357.html

See Also

NMFfit, NMFfitX, NMFfitXn

Examples

#----------
# is.nmf
#----------
# test if an object is an NMF model, i.e. that it implements the NMF interface
is.nmf(1:4)
is.nmf( nmfModel(3) )
is.nmf( nmf(rmatrix(10, 5), 2) )

#----------
# is.empty.nmf
#----------
# empty model
is.empty.nmf( nmfModel(3) )
# non empty models
is.empty.nmf( nmfModel(3, 10, 0) )
is.empty.nmf( rnmf(3, 10, 5) )

#----------
# isNMFfit
#----------
## Testing results of fits
# generate a random
V <- rmatrix(20, 10)

# single run -- using very low value for maxIter to speed up the example
res <- nmf(V, 3, maxIter=3L)
isNMFfit(res)

# multiple runs - keeping single fit
resm <- nmf(V, 3, nrun=2, maxIter=3L)
isNMFfit(resm)

# with a list of results
isNMFfit(list(res, resm, 'not a result'))
isNMFfit(list(res, resm, 'not a result'), recursive=FALSE)

Description

isCRANcheck tries to identify if one is running CRAN-like checks.

Usage

isCRANcheck(...)

isCHECK()

Arguments

Details

Currently isCRANcheck returns TRUE if the check is run with either environment variable _R_CHECK_TIMINGS_ (as set by flag '--timings') or _R_CHECK_CRAN_INCOMINGS_ (as set by flag '--as-cran').

Warning: the checks performed on CRAN check machines are on purpose not always run with such flags, so that users cannot effectively "trick" the checks. As a result, there is no guarantee this function effectively identifies such checks. If really needed for honest reasons, CRAN recommends users rely on custom dedicated environment variables to enable specific tests or examples.

Functions

• isCHECK: tries harder to test if running under R CMD check. It will definitely identifies check runs for:

  • unit tests that use the unified unit test framework defined by pkgmaker (see utest);

  • examples that are run with option R_CHECK_RUNNING_EXAMPLES_ = TRUE, which is automatically set for man pages generated with a fork of roxygen2 (see References).

  Currently, isCHECK checks both CRAN expected flags, the value of environment variable _R_CHECK_RUNNING_UTESTS_, and the value of option R_CHECK_RUNNING_EXAMPLES_. It will return TRUE if any of these environment variables is set to anything not equivalent to FALSE, or if the option is TRUE. For example, the function utest sets it to the name of the package being checked (_R_CHECK_RUNNING_UTESTS_=<pkgname>), but unit tests run as part of unit tests vignettes are run with _R_CHECK_RUNNING_UTESTS_=FALSE, so that all tests are run and reported when generating them.

References

Adapted from the function CRAN in the fda package.

https://github.com/renozao/roxygen

Examples

isCHECK()

Description

latex_preamble outputs/returns command definition LaTeX commands to be put in the preamble of vignettes.

Usage

latex_preamble(
  PACKAGE,
  R = TRUE,
  CRAN = TRUE,
  Bioconductor = TRUE,
  GEO = TRUE,
  ArrayExpress = TRUE,
  biblatex = FALSE,
  only = FALSE,
  file = ""
)

latex_bibliography(PACKAGE, file = "")

Arguments

Details

Argument PACKAGE is not required for latex_preamble, but must be correctly specified to ensure biblatex=TRUE generates the correct bibliography command.

Functions

• latex_bibliography: latex_bibliography prints or return a LaTeX command that includes a package bibliography file if it exists.

Examples

latex_preamble()
latex_preamble(R=TRUE, only=TRUE)
latex_preamble(R=FALSE, CRAN=FALSE, GEO=FALSE)
latex_preamble(GEO=TRUE, only=TRUE)

Description

Extends a vector used as an annotation track to match the number of rows and the row names of a given data.

Usage

match_atrack(x, data = NULL)

Arguments

Value

a vector of the same type as x

Description

Registry for NMF Algorithms

selectNMFMethod tries to select an appropriate NMF algorithm that is able to fit a given the NMF model.

getNMFMethod retrieves NMF algorithm objects from the registry.

existsNMFMethod tells if an NMF algorithm is registered under the

removeNMFMethod removes an NMF algorithm from the registry.

Usage

selectNMFMethod(name, model, load = FALSE, exact = FALSE,
    all = FALSE, quiet = FALSE)

  getNMFMethod(...)

  existsNMFMethod(name, exact = TRUE)

  removeNMFMethod(name, ...)

Arguments

Value

selectNMFMethod returns a character vector or NMFStrategy objects, or NULL if no suitable algorithm was found.

Description

The methods dim, nrow, ncol and nbasis return the different dimensions associated with an NMF model.

dim 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).

nrow, ncol and nbasis provide separate access to each of these dimensions respectively.

Usage

nbasis(x, ...)

  ## S4 method for signature 'NMF'
dim(x)

  ## S4 method for signature 'NMFfitXn'
dim(x)

Arguments

Details

The NMF package does not implement specific functions nrow and ncol, but rather the S4 method dim for objects of class NMF. This allows the base methods nrow and ncol to directly work with such objects, to get the number of rows and columns of the target matrix estimated by an NMF model.

The function nbasis is a new S4 generic defined in the package NMF, that returns the number of basis components of an object. Its default method should work for any object, that has a suitable basis method defined for its class.

Value

a single integer value or, for dim, a length-3 integer vector, e.g. c(2000, 30, 3) for an NMF model that fits a 2000 x 30 matrix using 3 basis components.

Methods

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

dim

signature(x = "NMFfitXn"): Returns the dimension common to all fits.

Since all fits have the same dimensions, it returns the dimension of the first fit. This method returns NULL if the object is empty.

nbasis

signature(x = "ANY"): Default method which returns the number of columns of the basis matrix extracted from x using a suitable method basis, or, if the latter is NULL, the value of attributes 'nbasis'.

For NMF models, this also corresponds to the number of rows in the coefficient matrix.

nbasis

signature(x = "NMFfitXn"): Returns the number of basis components common to all fits.

Since all fits have been computed using the same rank, it returns the factorization rank of the first fit. This method returns NULL if the object is empty.

Description

The function nmf is a S4 generic defines the main interface to run NMF algorithms within the framework defined in package NMF. It has many methods that facilitates applying, developing and testing NMF algorithms.

The package vignette vignette('NMF') contains an introduction to the interface, through a sample data analysis.

Usage

nmf(x, rank, method, ...)

  ## S4 method for signature 'matrix,numeric,NULL'
nmf(x, rank, method,
    seed = NULL, model = NULL, ...)

  ## S4 method for signature 'matrix,numeric,list'
nmf(x, rank, method, ...,
    .parameters = list())

  ## S4 method for signature 'matrix,numeric,function'
nmf(x, rank, method,
    seed, model = "NMFstd", ..., name,
    objective = "euclidean", mixed = FALSE)

  ## S4 method for signature 'matrix,NMF,ANY'
nmf(x, rank, method, seed,
    ...)

  ## S4 method for signature 'matrix,NULL,ANY'
nmf(x, rank, method, seed,
    ...)

  ## S4 method for signature 'matrix,matrix,ANY'
nmf(x, rank, method, seed,
    model = list(), ...)

  ## S4 method for signature 'formula,ANY,ANY'
nmf(x, rank, method, ...,
    model = NULL)

  ## S4 method for signature 'matrix,numeric,NMFStrategy'
nmf(x, rank,
    method, seed = nmf.getOption("default.seed"),
    rng = NULL, nrun = if (length(rank) > 1) 30 else 1,
    model = NULL, .options = list(),
    .pbackend = nmf.getOption("pbackend"),
    .callback = NULL, ...)

Arguments

Details

The nmf function has multiple methods that compose a very flexible interface allowing to:

• combine NMF algorithms with seeding methods and/or stopping/convergence criterion at runtime;

• perform multiple NMF runs, which are computed in parallel whenever the host machine allows it;

• run multiple algorithms with a common set of parameters, ensuring a consistent environment (notably the RNG settings).

The workhorse method is nmf,matrix,numeric,NMFStrategy, which is eventually called by all other methods. The other methods provides convenient ways of specifying the NMF algorithm(s), the factorization rank, or the seed to be used. Some allow to directly run NMF algorithms on different types of objects, such as data.frame or ExpressionSet objects.

Value

The returned value depends on the run mode:

Methods

nmf

signature(x = "data.frame", rank = "ANY", method = "ANY"): Fits an NMF model on a data.frame.

The target data.frame is coerced into a matrix with as.matrix.

nmf

signature(x = "matrix", rank = "numeric", method = "NULL"): Fits an NMF model using an appropriate algorithm when method is not supplied.

This method tries to select an appropriate algorithm amongst the NMF algorithms stored in the internal algorithm registry, which contains the type of NMF models each algorithm can fit. This is possible when the type of NMF model to fit is available from argument seed, i.e. if it is an NMF model itself. Otherwise the algorithm to use is obtained from nmf.getOption('default.algorithm').

This method is provided for internal usage, when called from other nmf methods with argument method missing in the top call (e.g. nmf,matrix,numeric,missing).

nmf

signature(x = "matrix", rank = "numeric", method = "list"): Fits multiple NMF models on a common matrix using a list of algorithms.

The models are fitted sequentially with nmf using the same options and parameters for all algorithms. In particular, irrespective of the way the computation is seeded, this method ensures that all fits are performed using the same initial RNG settings.

This method returns an object of class NMFList, that is essentially a list containing each fit.

nmf

signature(x = "matrix", rank = "numeric", method = "character"): Fits an NMF model on x using an algorithm registered with access key method.

Argument method is partially match against the access keys of all registered algorithms (case insensitive). Available algorithms are listed in section Algorithms below or the introduction vignette. A vector of their names may be retrieved via nmfAlgorithm().

nmf

signature(x = "matrix", rank = "numeric", method = "function"): Fits an NMF model on x using a custom algorithm defined the function method.

The supplied function must have signature (x=matrix, start=NMF, ...) and return an object that inherits from class NMF. It will be called internally by the workhorse nmf method, with an NMF model to be used as a starting point passed in its argument start.

Extra arguments in ... are passed to method from the top nmf call. Extra arguments that have no default value in the definition of the function method are required to run the algorithm (e.g. see argument alpha of myfun in the examples).

If the algorithm requires a specific type of NMF model, this can be specified in argument model that is handled as in the workhorse nmf method (see description for this argument).

nmf

signature(x = "matrix", 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

signature(x = "matrix", rank = "NULL", method = "ANY"): Fits an NMF model using the NMF model supplied in seed, to seed the computation, i.e. as a starting point.

This method is provided for completeness and is equivalent to nmf(x, seed, method, ...).

nmf

signature(x = "matrix", rank = "missing", method = "ANY"): Method defined to ensure the correct dispatch to workhorse methods in case of argument rank is missing.

nmf

signature(x = "matrix", rank = "numeric", method = "missing"): Method defined to ensure the correct dispatch to workhorse methods in case of argument method is missing.

nmf

signature(x = "matrix", rank = "matrix", method = "ANY"): Fits an NMF model partially seeding the computation with a given matrix passed in rank.

The matrix rank is used either as initial value for the basis or mixture coefficient matrix, depending on its dimension.

Currently, such partial NMF model is directly used as a seed, meaning that the remaining part is left uninitialised, which is not accepted by all NMF algorithm. This should change in the future, where the missing part of the model will be drawn from some random distribution.

Amongst built-in algorithms, only ‘snmf/l’ and ‘snmf/r’ support partial seeds, with only the coefficient or basis matrix initialised respectively.

nmf

signature(x = "matrix", rank = "data.frame", method = "ANY"): Shortcut for nmf(x, as.matrix(rank), method, ...).

nmf

signature(x = "formula", rank = "ANY", method = "ANY"): This method implements the interface for fitting formula-based NMF models. See nmfModel.

Argument rank target matrix or formula environment. If not missing, model must be a list, a data.frame or an environment in which formula variables are searched for.

Optimized C++ vs. plain R

Lee and Seung's multiplicative updates are used by several NMF algorithms. To improve speed and memory usage, a C++ implementation of the specific matrix products is used whenever possible. It directly computes the updates for each entry in the updated matrix, instead of using multiple standard matrix multiplication.

The algorithms that benefit from this optimization are: 'brunet', 'lee', 'nsNMF' and 'offset'. However there still exists plain R versions for these methods, which implement the updates as standard matrix products. These are accessible by adding the prefix '.R#' to their name: '.R#brunet', '.R#lee', '.R#nsNMF' and '.R#offset'.

Algorithms

All algorithms are accessible by their respective access key as listed below. The following algorithms are available:

‘brunet’

Standard NMF, based on the Kullback-Leibler divergence, from Brunet et al. (2004). It uses simple multiplicative updates from Lee et al. (2001), enhanced to avoid numerical underflow.

Default stopping criterion: invariance of the connectivity matrix (see nmf.stop.connectivity).

‘lee’

Standard NMF based on the Euclidean distance from Lee et al. (2001). It uses simple multiplicative updates.

Default stopping criterion: invariance of the connectivity matrix (see nmf.stop.connectivity).

ls-nmf

Least-Square NMF from Wang et al. (2006). It uses modified versions of Lee and Seung's multiplicative updates for the Euclidean distance, which incorporates weights on each entry of the target matrix, e.g. to reflect measurement uncertainty.

Default stopping criterion: stationarity of the objective function (see nmf.stop.stationary).

‘nsNMF’

Nonsmooth NMF from Pascual-Montano et al. (2006). It uses a modified version of Lee and Seung's multiplicative updates for the Kullback-Leibler divergence Lee et al. (2001), to fit a extension of the standard NMF model, that includes an intermediate smoothing matrix, meant meant to produce sparser factors.

Default stopping criterion: invariance of the connectivity matrix (see nmf.stop.connectivity).

‘offset’

NMF with offset from Badea (2008). It uses a modified version of Lee and Seung's multiplicative updates for Euclidean distance Lee et al. (2001), to fit an NMF model that includes an intercept, meant to capture a common baseline and shared patterns, in order to produce cleaner basis components.

Default stopping criterion: invariance of the connectivity matrix (see nmf.stop.connectivity).

‘pe-nmf’

Pattern-Expression NMF from Zhang2008. It uses multiplicative updates to minimize an objective function based on the Euclidean distance, that is regularized for effective expression of patterns with basis vectors.

Default stopping criterion: stationarity of the objective function (see nmf.stop.stationary).

‘snmf/r’, ‘snmf/l’

Alternating Least Square (ALS) approach from Kim et al. (2007). It applies the nonnegative least-squares algorithm from Van Benthem et al. (2004) (i.e. fast combinatorial nonnegative least-squares for multiple right-hand), to estimate the basis and coefficient matrices alternatively (see fcnnls). It minimises an Euclidean-based objective function, that is regularized to favour sparse basis matrices (for ‘snmf/l’) or sparse coefficient matrices (for ‘snmf/r’).

Stopping criterion: built-in within the internal workhorse function nmf_snmf, based on the KKT optimality conditions.

Seeding methods

The purpose of seeding methods is to compute initial values for the factor matrices in a given NMF model. This initial guess will be used as a starting point by the chosen NMF algorithm.

The seeding method to use in combination with the algorithm can be passed to interface nmf through argument seed. The seeding seeding methods available in registry are listed by the function nmfSeed (see list therein).

Detailed examples of how to specify the seeding method and its parameters can be found in the Examples section of this man page and in the package's vignette.

References

Brunet J, Tamayo P, Golub TR and Mesirov JP (2004). "Metagenes and molecular pattern discovery using matrix factorization." _Proceedings of the National Academy of Sciences of the United States of America_, *101*(12), pp. 4164-9. ISSN 0027-8424, <URL: http://dx.doi.org/10.1073/pnas.0308531101>, <URL: http://www.ncbi.nlm.nih.gov/pubmed/15016911>.

Lee DD and Seung H (2001). "Algorithms for non-negative matrix factorization." _Advances in neural information processing systems_. <URL: http://scholar.google.com/scholar?q=intitle:Algorithms+for+non-negative+matrix+factorization>.

Wang G, Kossenkov AV and Ochs MF (2006). "LS-NMF: a modified non-negative matrix factorization algorithm utilizing uncertainty estimates." _BMC bioinformatics_, *7*, pp. 175. ISSN 1471-2105, <URL: http://dx.doi.org/10.1186/1471-2105-7-175>, <URL: http://www.ncbi.nlm.nih.gov/pubmed/16569230>.

Pascual-Montano A, Carazo JM, Kochi K, Lehmann D and Pascual-marqui RD (2006). "Nonsmooth nonnegative matrix factorization (nsNMF)." _IEEE Trans. Pattern Anal. Mach. Intell_, *28*, pp. 403-415.

Badea L (2008). "Extracting gene expression profiles common to colon and pancreatic adenocarcinoma using simultaneous nonnegative matrix factorization." _Pacific Symposium on Biocomputing. Pacific Symposium on Biocomputing_, *290*, pp. 267-78. ISSN 1793-5091, <URL: http://www.ncbi.nlm.nih.gov/pubmed/18229692>.

Kim H and Park H (2007). "Sparse non-negative matrix factorizations via alternating non-negativity-constrained least squares for microarray data analysis." _Bioinformatics (Oxford, England)_, *23*(12), pp. 1495-502. ISSN 1460-2059, <URL: http://dx.doi.org/10.1093/bioinformatics/btm134>, <URL: http://www.ncbi.nlm.nih.gov/pubmed/17483501>.

Van Benthem M and Keenan MR (2004). "Fast algorithm for the solution of large-scale non-negativity-constrained least squares problems." _Journal of Chemometrics_, *18*(10), pp. 441-450. ISSN 0886-9383, <URL: http://dx.doi.org/10.1002/cem.889>, <URL: http://doi.wiley.com/10.1002/cem.889>.

See Also

nmfAlgorithm

Examples

# Only basic calls are presented in this manpage.
# Many more examples are provided in the demo file nmf.R
## Not run: 
demo('nmf')

## End(Not run)

# random data
x <- rmatrix(20,10)

# run default algorithm with rank 2
res <- nmf(x, 2)

# specify the algorithm
res <- nmf(x, 2, 'lee')

# get verbose message on what is going on
res <- nmf(x, 2, .options='v')
## Not run: 
# more messages
res <- nmf(x, 2, .options='v2')
# even more
res <- nmf(x, 2, .options='v3')
# and so on ...

## End(Not run)

Description

The built-in NMF algorithms described here minimise the Kullback-Leibler divergence (KL) between an NMF model and a target matrix. They use the updates for the basis and coefficient matrices ($W$ and $H$) defined by Brunet et al. (2004), which are essentially those from Lee et al. (2001), with an stabilisation step that shift up all entries from zero every 10 iterations, to a very small positive value.

nmf_update.brunet implements in C++ an optimised version of the single update step.

Algorithms ‘brunet’ and ‘.R#brunet’ provide the complete NMF algorithm from Brunet et al. (2004), using the C++-optimised and pure R updates nmf_update.brunet and nmf_update.brunet_R respectively.

Algorithm ‘KL’ provides an NMF algorithm based on the C++-optimised version of the updates from Brunet et al. (2004), which uses the stationarity of the objective value as a stopping criterion nmf.stop.stationary, instead of the stationarity of the connectivity matrix nmf.stop.connectivity as used by ‘brunet’.

Usage

nmf_update.brunet_R(i, v, x, eps = .Machine$double.eps,
    ...)

  nmf_update.brunet(i, v, x, copy = FALSE,
    eps = .Machine$double.eps, ...)

  nmfAlgorithm.brunet_R(..., .stop = NULL,
    maxIter = nmf.getOption("maxIter") %||% 2000,
    eps = .Machine$double.eps, stopconv = 40,
    check.interval = 10)

  nmfAlgorithm.brunet(..., .stop = NULL,
    maxIter = nmf.getOption("maxIter") %||% 2000,
    copy = FALSE, eps = .Machine$double.eps, stopconv = 40,
    check.interval = 10)

  nmfAlgorithm.KL(..., .stop = NULL,
    maxIter = nmf.getOption("maxIter") %||% 2000,
    copy = FALSE, eps = .Machine$double.eps,
    stationary.th = .Machine$double.eps,
    check.interval = 5 * check.niter, check.niter = 10L)

Arguments

Details

nmf_update.brunet_R implements in pure R a single update step, i.e. it updates both matrices.

Author(s)

Original implementation in MATLAB: Jean-Philippe Brunet [email protected]

Port to R and optimisation in C++: Renaud Gaujoux

Source

Original license terms:

This software and its documentation are copyright 2004 by the Broad Institute/Massachusetts Institute of Technology. All rights are reserved. This software is supplied without any warranty or guaranteed support whatsoever. Neither the Broad Institute nor MIT can not be responsible for its use, misuse, or functionality.

References

Brunet J, Tamayo P, Golub TR and Mesirov JP (2004). "Metagenes and molecular pattern discovery using matrix factorization." _Proceedings of the National Academy of Sciences of the United States of America_, *101*(12), pp. 4164-9. ISSN 0027-8424, <URL: http://dx.doi.org/10.1073/pnas.0308531101>, <URL: http://www.ncbi.nlm.nih.gov/pubmed/15016911>.

Lee DD and Seung H (2001). "Algorithms for non-negative matrix factorization." _Advances in neural information processing systems_. <URL: http://scholar.google.com/scholar?q=intitle:Algorithms+for+non-negative+matrix+factorization>.

Description

These update rules proposed by Badea (2008) are modified version of the updates from Lee et al. (2001), that include an offset/intercept vector, which models a common baseline for each feature accross all samples:

$V \approx W H + I$

nmf_update.euclidean_offset.h and nmf_update.euclidean_offset.w compute the updated NMFOffset model, using the optimized C++ implementations.

nmf_update.offset_R implements a complete single update step, using plain R updates.

nmf_update.offset implements a complete single update step, using C++-optimised updates.

Algorithms ‘offset’ and ‘.R#offset’ provide the complete NMF-with-offset algorithm from Badea (2008), using the C++-optimised and pure R updates nmf_update.offset and nmf_update.offset_R respectively.

Usage

nmf_update.euclidean_offset.h(v, w, h, offset,
    eps = 10^-9, copy = TRUE)

  nmf_update.euclidean_offset.w(v, w, h, offset,
    eps = 10^-9, copy = TRUE)

  nmf_update.offset_R(i, v, x, eps = 10^-9, ...)

  nmf_update.offset(i, v, x, copy = FALSE, eps = 10^-9,
    ...)

  nmfAlgorithm.offset_R(..., .stop = NULL,
    maxIter = nmf.getOption("maxIter") %||% 2000,
    eps = 10^-9, stopconv = 40, check.interval = 10)

  nmfAlgorithm.offset(..., .stop = NULL,
    maxIter = nmf.getOption("maxIter") %||% 2000,
    copy = FALSE, eps = 10^-9, stopconv = 40,
    check.interval = 10)

Arguments

Details

The associated model is defined as an NMFOffset object. The details of the multiplicative updates can be found in Badea (2008). Note that the updates are the ones defined for a single datasets, not the simultaneous NMF model, which is fit by algorithm ‘siNMF’ from formula-based NMF models.

Value

an NMFOffset model object.

Author(s)

Original update definition: Liviu Badea

Port to R and optimisation in C++: Renaud Gaujoux

References

Badea L (2008). "Extracting gene expression profiles common to colon and pancreatic adenocarcinoma using simultaneous nonnegative matrix factorization." _Pacific Symposium on Biocomputing. Pacific Symposium on Biocomputing_, *290*, pp. 267-78. ISSN 1793-5091, <URL: http://www.ncbi.nlm.nih.gov/pubmed/18229692>.

Lee DD and Seung H (2001). "Algorithms for non-negative matrix factorization." _Advances in neural information processing systems_. <URL: http://scholar.google.com/scholar?q=intitle:Algorithms+for+non-negative+matrix+factorization>.

Description

Multiplicative updates from Lee et al. (2001) for standard Nonnegative Matrix Factorization models $V \approx W H$, where the distance between the target matrix and its NMF estimate is measured by the – euclidean – Frobenius norm.

nmf_update.euclidean.w and nmf_update.euclidean.h compute the updated basis and coefficient matrices respectively. They use a C++ implementation which is optimised for speed and memory usage.

nmf_update.euclidean.w_R and nmf_update.euclidean.h_R implement the same updates in plain R.

Usage

nmf_update.euclidean.h(v, w, h, eps = 10^-9,
    nbterms = 0L, ncterms = 0L, copy = TRUE)

  nmf_update.euclidean.h_R(v, w, h, wh = NULL, eps = 10^-9)

  nmf_update.euclidean.w(v, w, h, eps = 10^-9,
    nbterms = 0L, ncterms = 0L, weight = NULL, copy = TRUE)

  nmf_update.euclidean.w_R(v, w, h, wh = NULL, eps = 10^-9)