Algorithms and framework for Nonnegative Matrix Factorization (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 renaud@cbio.uct.ac.za

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)

Annotation Tracks

Description

.atrack is an S4 generic method that converts an object into an annotation track object. It provides a general and flexible annotation framework that is used by aheatmap to annotates heatmap rows and columns.

is.atrack tests if an object is an annotationTrack object.

adata get/sets the annotation parameters on an object

amargin get/sets the annotation margin, i.e. along which dimension of the data the annotations are to be considered.

anames returns the reference margin names for annotation tracks, from their embedded annotation data object.

alength returns the reference length for annotation tracks, from their embedded annotation data object

atrack creates/concatenates annotationTrack objects

annotationTrack is constructor function for annotationTrack object

Usage

  .atrack(object, ...)

  is.atrack(x)

  adata(x, value, ...)

  amargin(x, value)

  anames(x, default.margin)

  alength(x, default.margin)

  ## S4 method for signature 'ANY'
.atrack(object, data = NULL, ...)

  atrack(..., order = NULL, enforceNames = FALSE,
    .SPECIAL = NA, .DATA = NULL, .CACHE = NULL)

  annotationTrack(x = list())

Arguments

Details

Methods for .atrack exist for common type of objects, which should provide enough options for new methods to define how annotation track are extracted from more complex objects, by coercing/filtering them into a supported type.

Value

atrack returns a list, decorated with class 'annotationTrack', where each element contains the description of an annotation track.

Methods

.atrack

signature(object = "ANY"): The default method converts character or integer vectors into factors. Numeric vectors, factors, a single NA or annotationTrack objects are returned unchanged (except from reordering by argument order). Data frames are not changed either, but class 'annotationTrack' is appended to their original class set.

Internal Routine for Fast Combinatorial Nonnegative Least-Squares

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

Generic Interface for Nonnegative Matrix Factorisation Models

Description

The class NMF is a virtual class that defines a common interface to handle Nonnegative Matrix Factorization models (NMF models) in a generic way. Provided a minimum set of generic methods is implemented by concrete model classes, these benefit from a whole set of functions and utilities to perform common computations and tasks in the context of Nonnegative Matrix Factorization.

The function misc provides access to miscellaneous data members stored in slot misc (as a list), which allow extensions of NMF models to be implemented, without defining a new S4 class.

Usage

  misc(object, ...)

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

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

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

Arguments

Details

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

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

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

Slots

misc

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

Methods

[

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

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

See [,NMF-method for more details.

$

signature(x = "NMF"): shortcut for x@misc[[name, exact=TRUE]] respectively.

$

signature(x = "NMF"): shortcut for x@misc[[name, exact=TRUE]] respectively.

$<-

signature(x = "NMF"): shortcut for x@misc[[name]] <- value

$<-

signature(x = "NMF"): shortcut for x@misc[[name]] <- value

.basis

signature(object = "NMF"): Pure virtual method for objects of class NMF, that should be overloaded by sub-classes, and throws an error if called.

.basis<-

signature(object = "NMF", value = "matrix"): Pure virtual method for objects of class NMF, that should be overloaded by sub-classes, and throws an error if called.

basis<-

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

basiscor

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

basiscor

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

basiscor

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

basismap

signature(object = "NMF"): Plots a heatmap of the basis matrix of the NMF model object. This method also works for fitted NMF models (i.e. NMFfit objects).

c

signature(x = "NMF"): Binds compatible matrices and NMF models together.

.coef

signature(object = "NMF"): Pure virtual method for objects of class NMF, that should be overloaded by sub-classes, and throws an error if called.

.coef<-

signature(object = "NMF", value = "matrix"): Pure virtual method for objects of class NMF, that should be overloaded by sub-classes, and throws an error if called.

coef<-

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

coefficients

signature(object = "NMF"): Alias to coef,NMF, therefore also pure virtual.

coefmap

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

connectivity

signature(object = "NMF"): Computes the connectivity matrix for an NMF model, for which cluster membership is given by the most contributing basis component in each sample. See predict,NMF-method.

consensus

signature(object = "NMF"): This method is provided for completeness and is identical to connectivity, and returns the connectivity matrix, which, in the case of a single NMF model, is also the consensus matrix.

consensushc

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

consensusmap

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

deviance

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

dim

signature(x = "NMF"): method for NMF objects for the base generic dim. It returns all dimensions in a length-3 integer vector: the number of row and columns of the estimated target matrix, as well as the factorization rank (i.e. the number of basis components).

dimnames

signature(x = "NMF"): Returns the dimension names of the NMF model x.

It returns either NULL if no dimnames are set on the object, or a 3-length list containing the row names of the basis matrix, the column names of the mixture coefficient matrix, and the column names of the basis matrix (i.e. the names of the basis components).

dimnames<-

signature(x = "NMF"): sets the dimension names of the NMF model x.

value can be NULL which resets all dimension names, or a 1, 2 or 3-length list providing names at least for the rows of the basis matrix.

See dimnames for more details.

.DollarNames

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

.DollarNames

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

extractFeatures

signature(object = "NMF"): Select basis-specific features from an NMF model, by applying the method extractFeatures,matrix to its basis matrix.

featureScore

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

fitted

signature(object = "NMF"): Pure virtual method for objects of class NMF, that should be overloaded by sub-classes, and throws an error if called.

ibterms

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

icterms

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

loadings

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

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

See loadings,NMF-method for more details.

metaHeatmap

signature(object = "NMF"): Deprecated method that is substituted by coefmap and basismap.

nmf.equal

signature(x = "NMF", y = "NMF"): Compares two NMF models.

Arguments in ... are used only when identical=FALSE and are passed to all.equal.

nmf.equal

signature(x = "NMF", y = "NMFfit"): Compares two NMF models when at least one comes from a NMFfit object, i.e. an object returned by a single run of nmf.

nmf.equal

signature(x = "NMF", y = "NMFfitX"): Compares two NMF models when at least one comes from multiple NMF runs.

nneg

signature(object = "NMF"): Apply nneg to the basis matrix of an NMF object (i.e. basis(object)). All extra arguments in ... are passed to the method nneg,matrix.

predict

signature(object = "NMF"): Default method for NMF models

profcor

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

profcor

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

profcor

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

rmatrix

signature(x = "NMF"): Returns the target matrix estimate of the NMF model x, perturbated by adding a random matrix generated using the default method of rmatrix: it is a equivalent to fitted(x) + rmatrix(fitted(x), ...).

This method can be used to generate random target matrices that depart from a known NMF model to a controlled extend. This is useful to test the robustness of NMF algorithms to the presence of certain types of noise in the data.

rnmf

signature(x = "NMF", target = "numeric"): Generates a random NMF model of the same class and rank as another NMF model.

This is the workhorse method that is eventually called by all other methods. It generates an NMF model of the same class and rank as x, compatible with the dimensions specified in target, that can be a single or 2-length numeric vector, to specify a square or rectangular target matrix respectively.

See rnmf,NMF,numeric-method for more details.

rnmf

signature(x = "NMF", target = "missing"): Generates a random NMF model of the same dimension as another NMF model.

It is a shortcut for rnmf(x, nrow(x), ncol(x), ...), which returns a random NMF model of the same class and dimensions as x.

rposneg

signature(object = "NMF"): Apply rposneg to the basis matrix of an NMF object.

show

signature(object = "NMF"): Show method for objects of class NMF

sparseness

signature(x = "NMF"): Compute the sparseness of an object of class NMF, as the sparseness of the basis and coefficient matrices computed separately.

It returns the two values in a numeric vector with names ‘basis’ and ‘coef’.

summary

signature(object = "NMF"): Computes summary measures for a single NMF model.

The following measures are computed:

See summary,NMF-method for more details.

Implementing NMF models

The class NMF only defines a basic data/low-level interface for NMF models, as a collection of generic methods, responsible with data handling, upon which relies a comprehensive set of functions, composing a rich higher-level interface.

Actual NMF models are defined as sub-classes that inherits from class NMF, and implement the management of data storage, providing definitions for the interface's pure virtual methods.

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

• Define a class that inherits from class NMF and implements the new model, say class myNMF.

• Implement the following S4 methods for the new class myNMF:

  fitted

  signature(object = "myNMF", value = "matrix"): Must return the estimated target matrix as fitted by the NMF model object.

  basis

  signature(object = "myNMF"): Must return the basis matrix(e.g. the first matrix factor in the standard NMF model).

  basis<-

  signature(object = "myNMF", value = "matrix"): Must return object with the basis matrix set to value.

  coef

  signature(object = "myNMF"): Must return the matrix of mixture coefficients (e.g. the second matrix factor in the standard NMF model).

  coef<-

  signature(object = "myNMF", value = "matrix"): Must return object with the matrix of mixture coefficients set to value.

  The NMF package provides "pure virtual" definitions of these methods for class NMF (i.e. with signatures (object='NMF', ...) and (object='NMF', value='matrix')) that throw an error if called, so as to force their definition for model classes.

• Optionally, implement method rnmf(signature(x="myNMF", target="ANY")). This method should call callNextMethod(x=x, target=target, ...) and fill the returned NMF model with its specific data suitable random values.

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

Creating NMF objects

Strictly speaking, because class NMF is virtual, no object of class NMF can be instantiated, only objects from its sub-classes. However, those objects are sometimes shortly referred in the documentation and vignettes as "NMF objects" instead of "objects that inherits from class NMF".

For built-in models or for models that inherit from the standard model class NMFstd, the factory method nmfModel enables to easily create valid NMF objects in a variety of common situations. See documentation for the the factory method nmfModel for more details.

References

Definition of Nonnegative Matrix Factorization in its modern formulation: Lee et al. (1999)

Historical first definition and algorithms: Paatero et al. (1994)

Lee DD and Seung HS (1999). "Learning the parts of objects by non-negative matrix factorization." _Nature_, *401*(6755), pp. 788-91. ISSN 0028-0836, <URL: http://dx.doi.org/10.1038/44565>, <URL: http://www.ncbi.nlm.nih.gov/pubmed/10548103>.

Paatero P and Tapper U (1994). "Positive matrix factorization: A non-negative factor model with optimal utilization of error estimates of data values." _Environmetrics_, *5*(2), pp. 111-126. <URL: http://dx.doi.org/10.1002/env.3170050203>, <URL: http://www3.interscience.wiley.com/cgi-bin/abstract/113468839/ABSTRACT>.

See Also

Main interface to perform NMF in nmf-methods.

Built-in NMF models and factory method in nmfModel.

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

Other NMF-interface: basis, .basis, .basis<-, basis<-, coef, .coef, .coef<-, coef<-, coefficients, loadings,NMF-method, nmfModel, nmfModels, rnmf, scoef

Examples

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

# class NMF is a virtual class so cannot be instantiated:
try( new('NMF') )

# To instantiate an NMF model, use the factory method nmfModel. see ?nmfModel
nmfModel()
nmfModel(3)
nmfModel(3, model='NMFns')

Defunct Functions and Classes in the NMF Package

Description

Defunct Functions and Classes in the NMF Package

Usage

  metaHeatmap(object, ...)

Arguments

Methods

metaHeatmap

signature(object = "matrix"): Defunct method substituted by aheatmap.

metaHeatmap

signature(object = "NMF"): Deprecated method that is substituted by coefmap and basismap.

metaHeatmap

signature(object = "NMFfitX"): Deprecated method subsituted by consensusmap.

Deprecated Functions in the Package NMF

Description

Deprecated Functions in the Package NMF

Arguments

Class for Storing Heterogeneous NMF fits

Description

This class wraps a list of NMF fit objects, which may come from different runs of the function nmf, using different parameters, methods, etc.. These can be either from a single run (NMFfit) or multiple runs (NMFfitX).

Note that its definition/interface is very likely to change in the future.

Methods

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.

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.

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.

show

signature(object = "NMFList"): Show method for objects of class NMFList

NMF Model - Nonnegative Matrix Factorization with Offset

Description

This class implements the Nonnegative Matrix Factorization with Offset model, required by the NMF with Offset algorithm.

Usage

  ## S4 method for signature 'NMFOffset'
initialize(.Object, ..., offset)

Arguments

Details

The NMF with Offset algorithm is defined by Badea (2008) as a modification of the euclidean based NMF algorithm from Lee2001 (see section Details and references below). It aims at obtaining 'cleaner' factor matrices, by the introduction of an offset matrix, explicitly modelling a feature specific baseline – constant across samples.

Methods

fitted

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

The estimate is computed as:

W H + offset

offset

signature(object = "NMFOffset"): The function offset returns the offset vector from an NMF model that has an offset, e.g. an NMFOffset model.

rnmf

signature(x = "NMFOffset", target = "numeric"): Generates a random NMF model with offset, from class NMFOffset.

The offset values are drawn from a uniform distribution between 0 and the maximum entry of the basis and coefficient matrices, which are drawn by the next suitable rnmf method, which is the workhorse method rnmf,NMF,numeric.

show

signature(object = "NMFOffset"): Show method for objects of class NMFOffset

Creating objects from the Class

Object of class NMFOffset can be created using the standard way with operator new

However, as for all NMF model classes – that extend class NMF, objects of class NMFOffset should be created using factory method nmfModel :

new('NMFOffset')

nmfModel(model='NMFOffset')

nmfModel(model='NMFOffset', W=w, offset=rep(1, nrow(w)))

See nmfModel for more details on how to use the factory method.

Initialize method

The initialize method for NMFOffset objects tries to correct the initial value passed for slot offset, so that it is consistent with the dimensions of the NMF model: it will pad the offset vector with NA values to get the length equal to the number of rows in the basis matrix.

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

See Also

Other NMF-model: NMFns-class, NMFstd-class

Examples

# create a completely empty NMF object
new('NMFOffset')

# create a NMF object based on random (compatible) matrices
n <- 50; r <- 3; p <- 20
w <- rmatrix(n, r)
h <- rmatrix(r, p)
nmfModel(model='NMFOffset', W=w, H=h, offset=rep(0.5, nrow(w)))

# apply Nonsmooth NMF algorithm to a random target matrix
V <- rmatrix(n, p)
## Not run: nmf(V, r, 'offset')

# random NMF model with offset
rnmf(3, 10, 5, model='NMFOffset')

NMFSeed is a constructor method that instantiate NMFSeed objects.

Description

NMFSeed is a constructor method that instantiate NMFSeed objects.

NMF seeding methods are registered via the function setNMFSeed, which stores them as NMFSeed objects in a dedicated registry.

removeNMFSeed removes an NMF seeding method from the registry.

Usage

  NMFSeed(key, method, ...)

  setNMFSeed(..., overwrite = isLoadingNamespace(),
    verbose = TRUE)

  removeNMFSeed(name, ...)

Arguments

Methods

NMFSeed

signature(key = "character"): Default method simply calls new with the same arguments.

NMFSeed

signature(key = "NMFSeed"): Creates an NMFSeed based on a template object (Constructor-Copy), in particular it uses the same name.

Base class that defines the interface for NMF seeding methods.

Description

This class implements a simple wrapper strategy object that defines a unified interface to seeding methods, that are used to initialise NMF models before fitting them with any NMF algorithm.

Slots

name

character string giving the name of the seeding strategy

method

workhorse function that implements the seeding strategy. It must have signature (object="NMF", x="matrix", ...) and initialise the NMF model object with suitable values for fitting the target matrix x.

Methods

algorithm

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

algorithm<-

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

NMFSeed

signature(key = "NMFSeed"): Creates an NMFSeed based on a template object (Constructor-Copy), in particular it uses the same name.

show

signature(object = "NMFSeed"): Show method for objects of class NMFSeed

Stopping Criteria for NMF Iterative Strategies

Description

The function documented here implement stopping/convergence criteria commonly used in NMF algorithms.

NMFStop acts as a factory method that creates stopping criterion functions from different types of values, which are subsequently used by NMFStrategyIterative objects to determine when to stop their iterative process.

nmf.stop.iteration generates a function that implements the stopping criterion that limits the number of iterations to a maximum of n), i.e. that returns TRUE if i>=n, FALSE otherwise.

nmf.stop.threshold generates a function that implements the stopping criterion that stops when a given stationarity threshold is achieved by successive iterations. The returned function is identical to nmf.stop.stationary, but with the default threshold set to threshold.

More precisely, the objective function is computed over n successive iterations (specified in argument check.niter), every check.interval iterations. The criterion stops when the absolute difference between the maximum and the minimum objective values over these iterations is lower than a given threshold \alpha (specified in stationary.th):

nmf.stop.connectivity implements the stopping criterion that is based on the stationarity of the connectivity matrix.

Usage

  NMFStop(s, check = TRUE)

  nmf.stop.iteration(n)

  nmf.stop.threshold(threshold)

  nmf.stop.stationary(object, i, y, x,
    stationary.th = .Machine$double.eps,
    check.interval = 5 * check.niter, check.niter = 10L,
    ...)

  nmf.stop.connectivity(object, i, y, x, stopconv = 40,
    check.interval = 10, ...)

Arguments

Details

NMFStop can take the following values:

function

is returned unchanged, except when it has no arguments, in which case it assumed to be a generator, which is immediately called and should return a function that implements the actual stopping criterion;

integer

the value is used to create a stopping criterion that stops at that exact number of iterations via nmf.stop.iteration;

numeric

the value is used to create a stopping criterion that stops when at that stationary threshold via nmf.stop.threshold;

character

must be a single string which must be an access key for registered criteria (currently available: “connectivity” and “stationary”), or the name of a function in the global environment or the namespace of the loading package.

\left| \frac{\max_{i- N_s + 1 \leq k \leq i} D_k - \min_{i - N_s +1 \leq k \leq i} D_k}{n} \right| \leq \alpha,

Value

a function that can be passed to argument .stop of function nmf, which is typically used when the algorith is implemented as an iterative strategy.

a function that can be used as a stopping criterion for NMF algorithms defined as NMFStrategyIterative objects. That is a function with arguments (strategy, i, target, data, ...) that returns TRUE if the stopping criterion is satisfied – which in turn stops the iterative process, and FALSE otherwise.

Factory Method for NMFStrategy Objects

Description

Creates NMFStrategy objects that wraps implementation of NMF algorithms into a unified interface.

Usage

  NMFStrategy(name, method, ...)

  ## S4 method for signature 'NMFStrategy,matrix,NMFfit'
run(object, y, x,
    ...)

  ## S4 method for signature 'NMFStrategy,matrix,NMF'
run(object, y, x, ...)

  ## S4 method for signature 'NMFStrategyFunction,matrix,NMFfit'
run(object,
    y, x, ...)

  ## S4 method for signature 'NMFStrategyIterative,matrix,NMFfit'
run(object,
    y, x, .stop = NULL,
    maxIter = nmf.getOption("maxIter") %||% 2000, ...)

  ## S4 method for signature 'NMFStrategyIterativeX,matrix,NMFfit'
run(object,
    y, x, maxIter, ...)

  ## S4 method for signature 'NMFStrategyOctave,matrix,NMFfit'
run(object,
    y, x, ...)

Arguments

Methods

NMFStrategy

signature(name = "character", method = "function"): Creates an NMFStrategyFunction object that wraps the function method into a unified interface.

method must be a function with signature (y="matrix", x="NMFfit", ...), and return an object of class NMFfit.

NMFStrategy

signature(name = "character", method = "NMFStrategy"): Creates an NMFStrategy object based on a template object (Constructor-Copy).

NMFStrategy

signature(name = "NMFStrategy", method = "missing"): Creates an NMFStrategy based on a template object (Constructor-Copy), in particular it uses the same name.

NMFStrategy

signature(name = "missing", method = "character"): Creates an NMFStrategy based on a registered NMF algorithm that is used as a template (Constructor-Copy), in particular it uses the same name.

It is a shortcut for NMFStrategy(nmfAlgorithm(method, exact=TRUE), ...).

NMFStrategy

signature(name = "NULL", method = "NMFStrategy"): Creates an NMFStrategy based on a template object (Constructor-Copy) but using a randomly generated name.

NMFStrategy

signature(name = "character", method = "character"): Creates an NMFStrategy based on a registered NMF algorithm that is used as a template.

NMFStrategy

signature(name = "NULL", method = "character"): Creates an NMFStrategy based on a registered NMF algorithm (Constructor-Copy) using a randomly generated name.

It is a shortcut for NMFStrategy(NULL, nmfAlgorithm(method), ...).

NMFStrategy

signature(name = "character", method = "missing"): Creates an NMFStrategy, determining its type from the extra arguments passed in ...: if there is an argument named Update then an NMFStrategyIterative is created, or if there is an argument named algorithm then an NMFStrategyFunction is created. Calls other than these generates an error.

run

signature(object = "NMFStrategy", y = "matrix", x = "NMFfit"): Pure virtual method defined for all NMF algorithms to ensure that a method run is defined by sub-classes of NMFStrategy.

It throws an error if called directly.

run

signature(object = "NMFStrategy", y = "matrix", x = "NMF"): Method to run an NMF algorithm directly starting from a given NMF model.

run

signature(object = "NMFStrategyFunction", y = "matrix", x = "NMFfit"): Runs the NMF algorithms implemented by the single R function – and stored in slot 'algorithm' of object, on the data object y, using x as starting point. It is equivalent to calling object@algorithm(y, x, ...).

This method is usually not called directly, but only via the function nmf, which takes care of many other details such as seeding the computation, handling RNG settings, or setting up parallelisation.

run

signature(object = "NMFStrategyIterative", y = "matrix", x = "NMFfit"): Runs an NMF iterative algorithm on a target matrix y.

run

signature(object = "NMFStrategyOctave", y = "matrix", x = "NMFfit"): Runs the NMF algorithms implemented by the Octave/Matlab function associated with the strategy – and stored in slot 'algorithm' of object.

This method is usually not called directly, but only via the function nmf, which takes care of many other details such as seeding the computation, handling RNG settings, or setting up parallel computations.

Virtual Interface for NMF Algorithms

Description

This class partially implements the generic interface defined for general algorithms defined in the NMF package (see algorithmic-NMF).

is.mixed tells if an NMF algorithm works on mixed-sign data.

Usage

  ## S4 method for signature 'NMFStrategy'
show(object)

  ## S4 method for signature 'NMFStrategy'
objective(object)

  ## S4 replacement method for signature 'NMFStrategy,character'
objective(object)<-value

  ## S4 replacement method for signature 'NMFStrategy,function'
objective(object)<-value

  is.mixed(object)

Arguments

Slots

objective

the objective function associated with the algorithm (Frobenius, Kullback-Leibler, etc...). It is either an access key of a registered objective function or a function definition. In the latter case, the given function must have the following signature (x="NMF", y="matrix") and return a nonnegative real value.

model

a character string giving either the (sub)class name of the NMF-class instance used and returned by the strategy, or a function name.

mixed

a logical that indicates if the algorithm works on mixed-sign data.

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

deviance

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

modelname

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

NMFStrategy

signature(name = "NMFStrategy", method = "missing"): Creates an NMFStrategy based on a template object (Constructor-Copy), in particular it uses the same name.

objective

signature(object = "NMFStrategy"): Gets the objective function associated with an NMF algorithm.

It is used in deviance to compute the objective value for an NMF model with respect to a given target matrix.

objective

signature(object = "NMFStrategy"): Gets the objective function associated with an NMF algorithm.

It is used in deviance to compute the objective value for an NMF model with respect to a given target matrix.

objective<-

signature(object = "NMFStrategy", value = "character"): Sets the objective function associated with an NMF algorithm, with a character string that must be a registered objective function.

objective<-

signature(object = "NMFStrategy", value = "character"): Sets the objective function associated with an NMF algorithm, with a character string that must be a registered objective function.

objective<-

signature(object = "NMFStrategy", value = "function"): Sets the objective function associated with an NMF algorithm, with a function that computes the approximation error between an NMF model and a target matrix.

objective<-

signature(object = "NMFStrategy", value = "function"): Sets the objective function associated with an NMF algorithm, with a function that computes the approximation error between an NMF model and a target matrix.

run

signature(object = "NMFStrategy", y = "matrix", x = "NMFfit"): Pure virtual method defined for all NMF algorithms to ensure that a method run is defined by sub-classes of NMFStrategy.

It throws an error if called directly.

run

signature(object = "NMFStrategy", y = "matrix", x = "NMF"): Method to run an NMF algorithm directly starting from a given NMF model.

Interface for Single Function NMF Strategies

Description

This class implements the virtual interface NMFStrategy for NMF algorithms that are implemented by a single workhorse R function.

Slots

algorithm

a function that implements an NMF algorithm. It must have signature (y='matrix', x='NMFfit'), where y is the target matrix to approximate and x is the NMF model assumed to be seeded with an appropriate initial value – as it is done internally by function nmf.

Note that argument names currently do not matter, but it is recommended to name them as specified above.

Methods

algorithm

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

algorithm<-

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

run

signature(object = "NMFStrategyFunction", y = "matrix", x = "NMFfit"): Runs the NMF algorithms implemented by the single R function – and stored in slot 'algorithm' of object, on the data object y, using x as starting point. It is equivalent to calling object@algorithm(y, x, ...).

This method is usually not called directly, but only via the function nmf, which takes care of many other details such as seeding the computation, handling RNG settings, or setting up parallelisation.

Interface for Algorithms: Implementation for Iterative NMF Algorithms

Description

This class provides a specific implementation for the generic function run – concretising the virtual interface class NMFStrategy, for NMF algorithms that conform to the following iterative schema (starred numbers indicate mandatory steps):

• 1. Initialisation

• 2*. Update the model at each iteration

• 3. Stop if some criterion is satisfied

• 4. Wrap up

This schema could possibly apply to all NMF algorithms, since these are essentially optimisation algorithms, almost all of which use iterative methods to approximate a solution of the optimisation problem. The main advantage is that it allows to implement updates and stopping criterion separately, and combine them in different ways. In particular, many NMF algorithms are based on multiplicative updates, following the approach from Lee et al. (2001), which are specially suitable to be cast into this simple schema.

Slots

onInit

optional function that performs some initialisation or pre-processing on the model, before starting the iteration loop.

Update

mandatory function that implement the update step, which computes new values for the model, based on its previous value. It is called at each iteration, until the stopping criterion is met or the maximum number of iteration is achieved.

Stop

optional function that implements the stopping criterion. It is called before each Update step. If not provided, the iterations are stopped after a fixed number of updates.

onReturn

optional function that wraps up the result into an NMF object. It is called just before returning the

Methods

run

signature(object = "NMFStrategyIterative", y = "matrix", x = "NMFfit"): Runs an NMF iterative algorithm on a target matrix y.

show

signature(object = "NMFStrategyIterative"): Show method for objects of class NMFStrategyIterative

References

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

Base Class for to store Nonnegative Matrix Factorisation results

Description

Base class to handle the results of general Nonnegative Matrix Factorisation algorithms (NMF).

The function NMFfit is a factory method for NMFfit objects, that should not need to be called by the user. It is used internally by the functions nmf and seed to instantiate the starting point of NMF algorithms.

Usage

  NMFfit(fit = nmfModel(), ..., rng = NULL)

Arguments

Details

It provides a general structure and generic functions to manage the results of NMF algorithms. It contains a slot with the fitted NMF model (see slot fit) as well as data about the methods and parameters used to compute the factorization.

The purpose of this class is to handle in a generic way the results of NMF algorithms. Its slot fit contains the fitted NMF model as an object of class NMF.

Other slots contains data about how the factorization has been computed, such as the algorithm and seeding method, the computation time, the final residuals, etc...

Class NMFfit acts as a wrapper class for its slot fit. It inherits from interface class NMF defined for generic NMF models. Therefore, all the methods defined by this interface can be called directly on objects of class NMFfit. The calls are simply dispatched on slot fit, i.e. the results are the same as if calling the methods directly on slot fit.

Slots

fit

An object that inherits from class NMF, and contains the fitted NMF model.

NB: class NMF is a virtual class. The default class for this slot is NMFstd, that implements the standard NMF model.

residuals

A numeric vector that contains the final residuals or the residuals track between the target matrix and its NMF estimate(s). Default value is numeric().

See method residuals for details on accessor methods and main interface nmf for details on how to compute NMF with residuals tracking.

method

a single character string that contains the name of the algorithm used to fit the model. Default value is ''.

seed

a single character string that contains the name of the seeding method used to seed the algorithm that fitted the NMF model. Default value is ''. See nmf for more details.

rng

an object that contains the RNG settings used for the fit. Currently the settings are stored as an integer vector, the value of .Random.seed at the time the object is created. It is initialized by the initialized method. See getRNG for more details.

distance

either a single "character" string that contains the name of the built-in objective function, or a function that measures the residuals between the target matrix and its NMF estimate. See objective and deviance,NMF-method.

parameters

a list that contains the extra parameters – usually specific to the algorithm – that were used to fit the model.

runtime

object of class "proc_time" that contains various measures of the time spent to fit the model. See system.time

options

a list that contains the options used to compute the object.

extra

a list that contains extra miscellaneous data for internal usage only. For example it can be used to store extra parameters or temporary data, without the need to explicitly extend the NMFfit class. Currently built-in algorithms only use this slot to store the number of iterations performed to fit the object.

Data that need to be easily accessible by the end-user should rather be set using the methods $<- that sets elements in the list slot misc – that is inherited from class NMF.

call

stored call to the last nmf method that generated the object.

Methods

algorithm

signature(object = "NMFfit"): Returns the name of the algorithm that fitted the NMF model 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 = "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.

.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 = "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.

compare

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

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

See deviance,NMFfit-method for more details.

fit

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

fit<-

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

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.

ibterms

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

icterms

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

icterms

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

minfit

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

modelname

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

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

nmf.equal

signature(x = "NMFfit", y = "NMF"): Compares two NMF models when at least one comes from a NMFfit object, i.e. an object returned by a single run of nmf.

nmf.equal

signature(x = "NMFfit", y = "NMFfit"): Compares two fitted NMF models, i.e. objects returned by single runs of nmf.

NMFfitX

signature(object = "NMFfit"): Creates an NMFfitX1 object from a single fit. This is used in nmf when only the best fit is kept in memory or on disk.

nrun

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

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.

offset

signature(object = "NMFfit"): Returns the offset from the fitted model.

plot

signature(x = "NMFfit", y = "missing"): Plots the residual track computed at regular interval during the fit of the NMF model x.

residuals

signature(object = "NMFfit"): Returns the residuals – track – between the target matrix and the NMF fit object.

runtime

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

runtime.all

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

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.

show

signature(object = "NMFfit"): Show method for objects of class NMFfit

summary

signature(object = "NMFfit"): Computes summary measures for a single fit from nmf.

This method adds the following measures to the measures computed by the method summary,NMF:

See summary,NMFfit-method for more details.

Examples

# run default NMF algorithm on a random matrix
n <- 50; r <- 3; p <- 20
V <- rmatrix(n, p)
res <- nmf(V, r)

# result class is NMFfit
class(res)
isNMFfit(res)

# show result
res

# compute summary measures
summary(res, target=V)

Factory Method for Multiple NMF Run Objects

Description

Factory Method for Multiple NMF Run Objects

Usage

  NMFfitX(object, ...)

  ## S4 method for signature 'list'
NMFfitX(object, ..., .merge = FALSE)

Arguments

Methods

NMFfitX

signature(object = "list"): Create an NMFfitX object from a list of fits.

NMFfitX

signature(object = "NMFfit"): Creates an NMFfitX1 object from a single fit. This is used in nmf when only the best fit is kept in memory or on disk.

NMFfitX

signature(object = "NMFfitX"): Provides a way to aggregate NMFfitXn objects into an NMFfitX1 object.

Virtual Class to Handle Results from Multiple Runs of NMF Algorithms

Description

This class defines a common interface to handle the results from multiple runs of a single NMF algorithm, performed with the nmf method.

Details

Currently, this interface is implemented by two classes, NMFfitX1 and NMFfitXn, which respectively handle the case where only the best fit is kept, and the case where the list of all the fits is returned.

See nmf for more details on the method arguments.

Slots

runtime.all

Object of class proc_time that contains CPU times required to perform all the runs.

Methods

basismap

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

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.

consensus

signature(object = "NMFfitX"): Pure virtual method defined to ensure consensus is defined for sub-classes of NMFfitX. It throws an error if called.

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.

consensusmap

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

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.

deviance

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

dispersion

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

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.

getRNG1

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

ibterms

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

metaHeatmap

signature(object = "NMFfitX"): Deprecated method subsituted by consensusmap.

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.

nmf.equal

signature(x = "NMFfitX", y = "NMF"): Compares two NMF models when at least one comes from multiple NMF runs.

NMFfitX

signature(object = "NMFfitX"): Provides a way to aggregate NMFfitXn objects into an NMFfitX1 object.

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.

See nrun,NMFfitX-method for more details.

predict

signature(object = "NMFfitX"): Returns the cluster membership index from an NMF model fitted with multiple runs.

Besides the type of clustering available for any NMF models ('columns', 'rows', 'samples', 'features'), this method can return the cluster membership index based on the consensus matrix, computed from the multiple NMF runs.

See predict,NMFfitX-method for more details.

residuals

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

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.

show

signature(object = "NMFfitX"): Show method for objects of class NMFfitX

summary

signature(object = "NMFfitX"): Computes a set of measures to help evaluate the quality of the best fit of the set. The result is similar to the result from the summary method of NMFfit objects. See NMF for details on the computed measures. In addition, the cophenetic correlation (cophcor) and dispersion coefficients of the consensus matrix are returned, as well as the total CPU time (runtime.all).

See Also

Other multipleNMF: NMFfitX1-class, NMFfitXn-class

Examples

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

# perform multiple runs of one algorithm (default is to keep only best fit)
res <- nmf(V, 3, nrun=3)
res

# plot a heatmap of the consensus matrix
## Not run:  consensusmap(res) 

Structure for Storing the Best Fit Amongst Multiple NMF Runs

Description

This class is used to return the result from a multiple run of a single NMF algorithm performed with function nmf with the – default – option keep.all=FALSE (cf. nmf).

Details

It extends both classes NMFfitX and NMFfit, and stores a the result of the best fit in its NMFfit structure.

Beside the best fit, this class allows to hold data about the computation of the multiple runs, such as the number of runs, the CPU time used to perform all the runs, as well as the consensus matrix.

Due to the inheritance from class NMFfit, objects of class NMFfitX1 can be handled exactly as the results of single NMF run – as if only the best run had been performed.

Slots

consensus

object of class matrix used to store the consensus matrix based on all the runs.

nrun

an integer that contains the number of runs performed to compute the object.

rng1

an object that contains RNG settings used for the first run. See getRNG1.

Methods

consensus

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

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

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.

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.

nmf.equal

signature(x = "NMFfitX1", y = "NMFfitX1"): Compares the NMF models fitted by multiple runs, that only kept the best fits.

nrun

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

show

signature(object = "NMFfitX1"): Show method for objects of class NMFfitX1

See Also

Other multipleNMF: NMFfitX-class, NMFfitXn-class

Examples

# generate a synthetic dataset with known classes
n <- 15; counts <- c(5, 2, 3);
V <- syntheticNMF(n, counts, factors = TRUE)

# get the class factor
groups <- V$pData$Group

# perform multiple runs of one algorithm, keeping only the best fit (default)
#i.e.: the implicit nmf options are .options=list(keep.all=FALSE) or .options='-k'
res <- nmf(V[[1]], 3, nrun=2)
res

# compute summary measures
summary(res)
# get more info
summary(res, target=V[[1]], class=groups)

# show computational time
runtime.all(res)

# plot the consensus matrix, as stored (pre-computed) in the object
## Not run:  consensusmap(res, annCol=groups) 

Structure for Storing All Fits from Multiple NMF Runs

Description

This class is used to return the result from a multiple run of a single NMF algorithm performed with function nmf with option keep.all=TRUE (cf. nmf).

Details

It extends both classes NMFfitX and list, and stores the result of each run (i.e. a NMFfit object) in its list structure.

IMPORTANT NOTE: This class is designed to be read-only, even though all the list-methods can be used on its instances. Adding or removing elements would most probably lead to incorrect results in subsequent calls. Capability for concatenating and merging NMF results is for the moment only used internally, and should be included and supported in the next release of the package.

Slots

.Data

standard slot that contains the S3 list object data. See R documentation on S3/S4 classes for more details (e.g., setOldClass).

Methods

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.

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

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

compare

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

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.

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.

entropy

signature(x = "NMFfitXn", y = "ANY"): Computes the best or mean entropy across all NMF fits stored in x.

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.

.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 = "NMFfitXn"): Returns the RNG settings used for the first run.

This method throws an error if the object is empty.

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.

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.

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.

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

purity

signature(x = "NMFfitXn", y = "ANY"): Computes the best or mean purity across all NMF fits stored in x.

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.

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 = "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.

show

signature(object = "NMFfitXn"): Show method for objects of class NMFfitXn

See Also

Other multipleNMF: NMFfitX1-class, NMFfitX-class

Examples

# generate a synthetic dataset with known classes
n <- 15; counts <- c(5, 2, 3);
V <- syntheticNMF(n, counts, factors = TRUE)

# get the class factor
groups <- V$pData$Group

# perform multiple runs of one algorithm, keeping all the fits
res <- nmf(V[[1]], 3, nrun=2, .options='k') # .options=list(keep.all=TRUE) also works
res

summary(res)
# get more info
summary(res, target=V[[1]], class=groups)

# compute/show computational times
runtime.all(res)
seqtime(res)

# plot the consensus matrix, computed on the fly
## Not run:  consensusmap(res, annCol=groups) 

NMF Model - Nonsmooth Nonnegative Matrix Factorization

Description

This class implements the Nonsmooth Nonnegative Matrix Factorization (nsNMF) model, required by the Nonsmooth NMF algorithm.

The Nonsmooth NMF algorithm is defined by Pascual-Montano et al. (2006) as a modification of the standard divergence based NMF algorithm (see section Details and references below). It aims at obtaining sparser factor matrices, by the introduction of a smoothing matrix.

Details

The Nonsmooth NMF algorithm is a modification of the standard divergence based NMF algorithm (see NMF). Given a non-negative n \times p matrix V and a factorization rank r, it fits the following model:

V \equiv W S(\theta) H,

where:

• W and H are such as in the standard model, i.e. non-negative matrices of dimension n \times r and r \times p respectively;

• S is a r \times r square matrix whose entries depends on an extra parameter 0\leq \theta \leq 1 in the following way:

  S = (1-\theta)I + \frac{\theta}{r} 11^T ,

  where I is the identity matrix and 1 is a vector of ones.

The interpretation of S as a smoothing matrix can be explained as follows: Let X be a positive, nonzero, vector. Consider the transformed vector Y = S X. If \theta = 0, then Y = X and no smoothing on X has occurred. However, as \theta \to 1, the vector Y tends to the constant vector with all elements almost equal to the average of the elements of X. This is the smoothest possible vector in the sense of non-sparseness because all entries are equal to the same nonzero value, instead of having some values close to zero and others clearly nonzero.

Methods

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.

show

signature(object = "NMFns"): Show method for objects of class NMFns

Creating objects from the Class

Object of class NMFns can be created using the standard way with operator new

However, as for all NMF model classes – that extend class NMF, objects of class NMFns should be created using factory method nmfModel :

new('NMFns')

nmfModel(model='NMFns')

nmfModel(model='NMFns', W=w, theta=0.3

See nmfModel for more details on how to use the factory method.

Algorithm

The Nonsmooth NMF algorithm uses a modified version of the multiplicative update equations in Lee & Seung's method for Kullback-Leibler divergence minimization. The update equations are modified to take into account the – constant – smoothing matrix. The modification reduces to using matrix W S instead of matrix W in the update of matrix H, and similarly using matrix S H instead of matrix H in the update of matrix W.

After the matrix W has been updated, each of its columns is scaled so that it sums up to 1.

References

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.

See Also

Other NMF-model: initialize,NMFOffset-method, NMFOffset-class, NMFstd-class

Examples

# create a completely empty NMFns object
new('NMFns')

# create a NMF object based on random (compatible) matrices
n <- 50; r <- 3; p <- 20
w <- rmatrix(n, r)
h <- rmatrix(r, p)
nmfModel(model='NMFns', W=w, H=h)

# apply Nonsmooth NMF algorithm to a random target matrix
V <- rmatrix(n, p)
## Not run: nmf(V, r, 'ns')

# random nonsmooth NMF model
rnmf(3, 10, 5, model='NMFns', theta=0.3)

NMF Model - Standard model

Description

This class implements the standard model of Nonnegative Matrix Factorization. It provides a general structure and generic functions to manage factorizations that follow the standard NMF model, as defined by Lee et al. (2001).

Details

Let V be a n \times m non-negative matrix and r a positive integer. In its standard form (see references below), a NMF of V is commonly defined as a pair of matrices (W, H) such that:

V \equiv W H,

where:

• W and H are n \times r and r \times m matrices respectively with non-negative entries;

• \equiv is to be understood with respect to some loss function. Common choices of loss functions are based on Frobenius norm or Kullback-Leibler divergence.

Integer r is called the factorization rank. Depending on the context of application of NMF, the columns of W and H are given different names:

columns of W

basis vector, metagenes, factors, source, image basis

columns of H

mixture coefficients, metagene sample expression profiles, weights

rows of H

basis profiles, metagene expression profiles

NMF approaches have been successfully applied to several fields. The package NMF was implemented trying to use names as generic as possible for objects and methods.

The following terminology is used:

samples

the columns of the target matrix V

features

the rows of the target matrix V

basis matrix

the first matrix factor W

basis vectors

the columns of first matrix factor W

mixture matrix

the second matrix factor H

mixtures coefficients

the columns of second matrix factor H

However, because the package NMF was primarily implemented to work with gene expression microarray data, it also provides a layer to easily and intuitively work with objects from the Bioconductor base framework. See bioc-NMF for more details.

Slots

W

A matrix that contains the basis matrix, i.e. the first matrix factor of the factorisation

H

A matrix that contains the coefficient matrix, i.e. the second matrix factor of the factorisation

bterms

a data.frame that contains the primary data that define fixed basis terms. See bterms.

ibterms

integer vector that contains the indexes of the basis components that are fixed, i.e. for which only the coefficient are estimated.

IMPORTANT: This slot is set on construction of an NMF model via nmfModel and is not recommended to not be subsequently changed by the end-user.

cterms

a data.frame that contains the primary data that define fixed coefficient terms. See cterms.

icterms

integer vector that contains the indexes of the basis components that have fixed coefficients, i.e. for which only the basis vectors are estimated.

IMPORTANT: This slot is set on construction of an NMF model via nmfModel and is not recommended to not be subsequently changed by the end-user.

Methods

.basis

signature(object = "NMFstd"): Get the basis matrix in standard NMF models

This function returns slot W of object.

.basis<-

signature(object = "NMFstd", value = "matrix"): Set the basis matrix in standard NMF models

This function sets slot W of object.

bterms<-

signature(object = "NMFstd"): Default method tries to coerce value into a data.frame with as.data.frame.

.coef

signature(object = "NMFstd"): Get the mixture coefficient matrix in standard NMF models

This function returns slot H of object.

.coef<-

signature(object = "NMFstd", value = "matrix"): Set the mixture coefficient matrix in standard NMF models

This function sets slot H of object.

cterms<-

signature(object = "NMFstd"): Default method tries to coerce value into a data.frame with as.data.frame.

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

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.

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.

References

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

See Also

Other NMF-model: initialize,NMFOffset-method, NMFns-class, NMFOffset-class

Examples

# create a completely empty NMFstd object
new('NMFstd')

# create a NMF object based on one random matrix: the missing matrix is deduced
# Note this only works when using factory method NMF
n <- 50; r <- 3;
w <- rmatrix(n, r)
nmfModel(W=w)

# create a NMF object based on random (compatible) matrices
p <- 20
h <- rmatrix(r, p)
nmfModel(W=w, H=h)

# create a NMF object based on incompatible matrices: generate an error
h <- rmatrix(r+1, p)
try( new('NMFstd', W=w, H=h) )
try( nmfModel(w, h) )

# Giving target dimensions to the factory method allow for coping with dimension
# incompatibilty (a warning is thrown in such case)
nmfModel(r, W=w, H=h)

Generic Strategy Class

Description

This class defines a common interface for generic algorithm strategies (e.g., NMFStrategy).

name and name<- gets and sets the name associated with an object. In the case of Strategy objects it is the the name of the algorithm.

Usage

  name(object, ...)

  ## S4 method for signature 'Strategy'
name(object, all = FALSE)

  name(object, ...)<-value

Arguments

Slots

name

character string giving the name of the algorithm

package

name of the package that defined the strategy.

defaults

default values for some of the algorithm's arguments.

Methods

name

signature(object = "Strategy"): Returns the name of an algorithm

name

signature(object = "Strategy"): Returns the name of an algorithm

name<-

signature(object = "Strategy", value = "character"): Sets the name(s) of an NMF algorithm

name<-

signature(object = "Strategy", value = "character"): Sets the name(s) of an NMF algorithm

Sub-setting NMF Objects

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]

Advanced Usage of the Package NMF

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

Utility function to aggregate numerical quality measures from NMFfitXn objects.

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

Annotated Heatmaps

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)

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

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

Generic Interface for Algorithms

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

Accessing NMF Factors

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

Correlations in NMF Models

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

Dimension names for NMF objects

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)

Specific NMF Layer for Bioconductor

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

Fixed Terms in NMF Models

Description

These functions are for internal use and should not be called by the end-user.

cterms<- sets fixed coefficient terms or indexes and should only be called on a newly created NMF object, i.e. in the constructor/factory generic nmfModel.

Usage

  bterms(object)<-value

  cterms(object)<-value

Arguments

Details

They use model.matrix(~ -1 + ., data=value) to generate suitable term matrices.

Methods

bterms<-

signature(object = "NMFstd"): Default method tries to coerce value into a data.frame with as.data.frame.

cterms<-

signature(object = "NMFstd"): Default method tries to coerce value into a data.frame with as.data.frame.

Concatenating NMF Models

Description

Binds compatible matrices and NMF models together.

Usage

  ## S4 method for signature 'NMF'
c(x, ..., margin = 3, recursive = FALSE)

Arguments

Testing Compatibility of Algorithm and Models

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

Generate Break Intervals from Numeric Variables

Description

Implementation is borrowed from the R core function cut.default.

Usage

  ccBreaks(x, breaks)

Builds a Color Palette from Compact Color Specification

Description

Builds a Color Palette from Compact Color Specification

Usage

  ccPalette(x, n = NA, verbose = FALSE)

Builds a Color Ramp from Compact Color Specification

Description

Builds a Color Ramp from Compact Color Specification

Usage

  ccRamp(x, n = NA, ...)

Extract Colour Palette Specification

Description

Extract Colour Palette Specification

Usage

  ccSpec(x)

Arguments

Value

a list with elements: palette, n and rev

Error Checks in NMF Runs

Description

Auxiliary function for internal error checks in nmf results.

Usage

  checkErrors(object, element = NULL)

Arguments

Cluster Matrix Rows in Annotated Heatmaps

Description

Cluster Matrix Rows in Annotated Heatmaps

Usage

  cluster_mat(mat, param, distfun, hclustfun, reorderfun,
    na.rm = TRUE, subset = NULL, verbose = FALSE)

Arguments

Comparing Results from Different NMF Runs

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)

Clustering Connectivity and Consensus Matrices

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

Returns the consensus matrix computed while performing all NMF runs, amongst which object was selected as the best fit.

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

Computes the consensus matrix of the set of fits stored in object, as the mean connectivity matrix across runs.

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

Hierarchical Clustering of a Consensus Matrix

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.

Cophenetic Correlation Coefficient

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

Fade Out the Upper Branches from a Dendrogram

Description

Fade Out the Upper Branches from a Dendrogram

Usage

  cutdendro(x, n)

Arguments

Distances and Objective Functions

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

Dispersion of a Matrix

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

Golub ExpressionSet

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)

}

Fast Combinatorial Nonnegative Least-Square

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)

Feature Selection in NMF Models

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

Extracting Fitted Models

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.

Fitted Matrix in NMF Models

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

Extracting RNG Data from NMF Objects

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

Open a File Graphic Device

Description

Opens a graphic device depending on the file extension

Usage

  gfile(filename, width, height, ...)

Heatmaps of NMF Factors

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)

Fixed Terms in NMF Models

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.

Testing NMF Objects

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)

Package Check Utils

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

LaTeX Utilities for Vignettes

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)

Internal verbosity option

Description

Internal verbosity option

Usage

  lverbose(val)

Arguments

Value

the old verbose level

Extending Annotation Vectors

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

Registry for NMF Algorithms

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.

Dimension of NMF Objects

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.

Running NMF algorithms

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)

Testing Equality of NMF Models

Description

The function nmf.equal tests if two NMF models are the same, i.e. they contain – almost – identical data: same basis and coefficient matrices, as well as same extra parameters.

Usage

  nmf.equal(x, y, ...)

  ## S4 method for signature 'NMF,NMF'
nmf.equal(x, y, identical = TRUE,
    ...)

  ## S4 method for signature 'list,list'
nmf.equal(x, y, ..., all = FALSE,
    vector = FALSE)

Arguments

Details

nmf.equal compares two NMF models, and return TRUE iff they are identical acording to the function identical when identical=TRUE, or equal up to some tolerance acording to the function all.equal. This means that all data contained in the objects are compared, which includes at least the basis and coefficient matrices, as well as the extra parameters stored in slot ‘misc’.

If extra arguments are specified in ..., then the comparison is performed using all.equal, irrespective of the value of argument identical.

Methods

nmf.equal

signature(x = "NMF", y = "NMF"): Compares two NMF models.

Arguments in ... are used only when identical=FALSE and are passed to all.equal.

nmf.equal

signature(x = "NMFfit", y = "NMF"): Compares two NMF models when at least one comes from a NMFfit object, i.e. an object returned by a single run of nmf.

nmf.equal

signature(x = "NMF", y = "NMFfit"): Compares two NMF models when at least one comes from a NMFfit object, i.e. an object returned by a single run of nmf.

nmf.equal

signature(x = "NMFfit", y = "NMFfit"): Compares two fitted NMF models, i.e. objects returned by single runs of nmf.

nmf.equal

signature(x = "NMFfitX", y = "NMF"): Compares two NMF models when at least one comes from multiple NMF runs.

nmf.equal

signature(x = "NMF", y = "NMFfitX"): Compares two NMF models when at least one comes from multiple NMF runs.

nmf.equal

signature(x = "NMFfitX1", y = "NMFfitX1"): Compares the NMF models fitted by multiple runs, that only kept the best fits.

nmf.equal

signature(x = "list", y = "list"): Compares the results of multiple NMF runs.

This method either compare the two best fit, or all fits separately. All extra arguments in ... are passed to each internal call to nmf.equal.

nmf.equal

signature(x = "list", y = "missing"): Compare all elements in x to x[[1]].

Listing and Retrieving NMF Algorithms

Description

nmfAlgorithm lists access keys or retrieves NMF algorithms that are stored in registry. It allows to list

Usage

  nmfAlgorithm(name = NULL, version = NULL, all = FALSE,
    ...)

Arguments

Value

an NMFStrategy object if name is not NULL and all=FALSE, or a named character vector that contains the access keys of the matching algorithms. The names correspond to the access key of the primary algorithm: e.g. algorithm ‘lee’ has two registered versions, one plain R (‘.R#lee’) and the other uses optimised C updates (‘lee’), which will all get named ‘lee’.

See Also

Other regalgo: canFit

Examples

# list all main algorithms
nmfAlgorithm()
# list all versions of algorithms
nmfAlgorithm(all=TRUE)
# list all plain R versions
nmfAlgorithm(version='R')

NMF Algorithm - Sparse NMF via Alternating NNLS

Description

NMF algorithms proposed by Kim et al. (2007) that enforces sparsity constraint on the basis matrix (algorithm ‘SNMF/L’) or the mixture coefficient matrix (algorithm ‘SNMF/R’).

Usage

  nmfAlgorithm.SNMF_R(..., maxIter = 20000L, eta = -1,
    beta = 0.01, bi_conv = c(0, 10), eps_conv = 1e-04)

  nmfAlgorithm.SNMF_L(..., maxIter = 20000L, eta = -1,
    beta = 0.01, bi_conv = c(0, 10), eps_conv = 1e-04)

Arguments

Details

The algorithm ‘SNMF/R’ solves the following NMF optimization problem on a given target matrix A of dimension n \times p:

\begin{array}{ll} & \min_{W,H} \frac{1}{2} \left(|| A - WH ||_F^2 + \eta ||W||_F^2 + \beta (\sum_{j=1}^p ||H_{.j}||_1^2)\right)\\ s.t. & W\geq 0, H\geq 0 \end{array}

The algorithm ‘SNMF/L’ solves a similar problem on the transposed target matrix A, where H and W swap roles, i.e. with sparsity constraints applied to W.

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

Apply Function for NMF Objects

Description

The function nmfApply provides exteneded apply-like functionality for objects of class NMF. It enables to easily apply a function over different margins of NMF models.

Usage

  nmfApply(X, MARGIN, FUN, ..., simplify = TRUE,
    USE.NAMES = TRUE)

Arguments

Details

The function FUN is applied via a call to apply or sapply according to the value of argument MARGIN as follows:

MARGIN=1

apply FUN to each row of the basis matrix: apply(basis(X), 1L, FUN, ...).

MARGIN=2

apply FUN to each column of the coefficient matrix: apply(coef(X), 2L, FUN, ...).

MARGIN=3

apply FUN to each pair of associated basis component and basis profile: more or less sapply(seq(nbasis(X)), function(i, ...) FUN(basis(X)[,i], coef(X)[i, ], ...), ...).

In this case FUN must be have at least two arguments, to which are passed each basis components and basis profiles respectively – as numeric vectors.

MARGIN=4

apply FUN to each column of the basis matrix, i.e. to each basis component: apply(basis(X), 2L, FUN, ...).

MARGIN=5

apply FUN to each row of the coefficient matrix: apply(coef(X), 1L, FUN, ...).

Value

a vector or a list. See apply and sapply for more details on the output format.

Checking NMF Algorithm

Description

nmfCheck enables to quickly check that a given NMF algorithm runs properly, by applying it to some small random data.

Usage

  nmfCheck(method = NULL, rank = max(ncol(x)/5, 3),
    x = NULL, seed = 1234, ...)

Arguments

Value

the result of the NMF fit invisibly.

Examples

# test default algorithm
nmfCheck()

# test 'lee' algorithm
nmfCheck('lee')

Estimate Rank for NMF Models

Description

A critical parameter in NMF algorithms is the factorization rank r. It defines the number of basis effects used to approximate the target matrix. Function nmfEstimateRank helps in choosing an optimal rank by implementing simple approaches proposed in the literature.

Note that from version 0.7, one can equivalently call the function nmf with a range of ranks.

In the plot generated by plot.NMF.rank, each curve represents a summary measure over the range of ranks in the survey. The colours correspond to the type of data to which the measure is related: coefficient matrix, basis component matrix, best fit, or consensus matrix.

Usage

  nmfEstimateRank(x, range,
    method = nmf.getOption("default.algorithm"), nrun = 30,
    model = NULL, ..., verbose = FALSE, stop = FALSE)

  ## S3 method for class 'NMF.rank'
 plot(x, y = NULL,
    what = c("all", "cophenetic", "rss", "residuals", "dispersion", "evar", 
        "sparseness", "sparseness.basis", "sparseness.coef", "silhouette", 
        "silhouette.coef", "silhouette.basis", "silhouette.consensus"),
    na.rm = FALSE, xname = "x", yname = "y",
    xlab = "Factorization rank", ylab = "",
    main = "NMF rank survey", ...)

Arguments

Details

Given a NMF algorithm and the target matrix, a common way of estimating r is to try different values, compute some quality measures of the results, and choose the best value according to this quality criteria. See Brunet et al. (2004) and Hutchins et al. (2008).

The function nmfEstimateRank allows to perform this estimation procedure. It performs multiple NMF runs for a range of rank of factorization and, for each, returns a set of quality measures together with the associated consensus matrix.

In order to avoid overfitting, it is recommended to run the same procedure on randomized data. The results on the original and the randomised data may be plotted on the same plots, using argument y.

Value

nmfEstimateRank returns a S3 object (i.e. a list) of class NMF.rank with the following elements:

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

Hutchins LN, Murphy SM, Singh P and Graber JH (2008). "Position-dependent motif characterization using non-negative matrix factorization." _Bioinformatics (Oxford, England)_, *24*(23), pp. 2684-90. ISSN 1367-4811, <URL: http://dx.doi.org/10.1093/bioinformatics/btn526>, <URL: http://www.ncbi.nlm.nih.gov/pubmed/18852176>.

Examples