nmfModel: Factory Methods NMF Models

Description

nmfModel is a S4 generic function which provides a convenient way to build NMF models. It implements a unified interface for creating NMF objects from any NMF models, which is designed to resolve potential dimensions inconsistencies.

nmfModels lists all available NMF models currently defined that can be used to create NMF objects, i.e. -- more or less -- all S4 classes that inherit from class NMF.

Usage

nmfModel(rank, target = 0L, ...)
  ## S3 method for class 'numeric,numeric':
nmfModel(rank, target,
    ncol = NULL, model = "NMFstd", W, H, ...,
    force.dim = TRUE, order.basis = TRUE)
  ## S3 method for class 'numeric,matrix':
nmfModel(rank, target, ...,
    use.names = TRUE)
  ## S3 method for class 'formula,ANY':
nmfModel(rank, target, ...,
    data = NULL, no.attrib = FALSE)
  nmfModels(builtin.only = FALSE)

Arguments

rank

specification of the target factorization rank (i.e. the number of components).

target

an object that specifies the dimension of the estimated target matrix.

...

extra arguments to allow extension, that are passed down to the workhorse method nmfModel,numeric.numeric, where they are used to initialise slots specific to the instantiating NMF model class.

ncol

a numeric value that specifies the number of columns of the target matrix, fitted the NMF model. It is used only if not missing and when argument target is a single numeric value.

model

the class of the object to be created. It must be a valid class name that inherits from class NMF. Default is the standard NMF model NMFstd.

value for the basis matrix. data.frame objects are converted into matrices with as.matrix.

value for the mixture coefficient matrix data.frame objects are converted into matrices with as.matrix.

force.dim

logical that indicates whether the method should try lowering the rank or shrinking dimensions of the input matrices to make them compatible

order.basis

logical that indicates whether the basis components should reorder the rows of the mixture coefficient matrix to match the order of the basis components, based on their respective names. It is only used if the basis and coefficient matrices have c

use.names

a logical that indicates whether the dimension names of the target matrix should be set on the returned NMF model.

data

Optional argument where to look for the variables used in the formula.

no.attrib

logical that indicate if attributes containing data related to the formula should be attached as attributes. If FALSE attributes 'target' and 'formula' contain the target matrix, and a list describing each fo

builtin.only

logical that indicates whether only built-in NMF models, i.e. defined within the NMF package, should be listed.

Value

an object that inherits from class NMF.
a list

Main factory method

The main factory engine of NMF models is implemented by the method with signature numeric, numeric. Other factory methods provide convenient ways of creating NMF models from e.g. a given target matrix or known basis/coef matrices (see section Other Factory Methods).

This method creates an object of class model, using the extra arguments in ... to initialise slots that are specific to the given model.

All NMF models implement get/set methods to access the matrix factors (see basis), which are called to initialise them from arguments W and H. These argument names derive from the definition of all built-in models that inherit derive from class NMFstd, which has two slots, W and H, to hold the two factors -- following the notations used in Lee et al. (1999).

If argument target is missing, the method creates a standard NMF model of dimension 0xrankx0. That is that the basis and mixture coefficient matrices, W and H, have dimension 0xrank and rankx0 respectively.

If target dimensions are also provided in argument target as a 2-length vector, then the method creates an NMF object compatible to fit a target matrix of dimension target[1]xtarget[2]. That is that the basis and mixture coefficient matrices, W and H, have dimension target[1]xrank and rankxtarget[2] respectively. The target dimensions can also be specified using both arguments target and ncol to define the number of rows and the number of columns of the target matrix respectively. If no other argument is provided, these matrices are filled with NAs.

If arguments W and/or H are provided, the method creates a NMF model where the basis and mixture coefficient matrices, W and H, are initialised using the values of W and/or H.

The dimensions given by target, W and H, must be compatible. However if force.dim=TRUE, the method will reduce the dimensions to the achieve dimension compatibility whenever possible.

When W and H are both provided, the NMF object created is suitable to seed a NMF algorithm in a call to the nmf method. Note that in this case the factorisation rank is implicitly set by the number of basis components in the seed.

Details

All nmfModel methods return an object that inherits from class NMF, that is suitable for seeding NMF algorithms via arguments rank or seed of the nmf method, in which case the factorisation rank is implicitly set by the number of basis components in the seeding model (see nmf).

For convenience, shortcut methods and internal conversions for working on data.frame objects directly are implemented. However, note that conversion of a data.frame into a matrix object may take some non-negligible time, for large datasets. If using this method or other NMF-related methods several times, consider converting your data data.frame object into a matrix once for good, when first loaded.

References

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

Examples

Run this code

# data
n <- 20; r <- 3; p <- 10
V <- rmatrix(n, p) # some target matrix

# create a r-ranked NMF model with a given target dimensions n x p as a 2-length vector
nmfModel(r, c(n,p)) # directly
nmfModel(r, dim(V)) # or from an existing matrix <=> nmfModel(r, V)
# or alternatively passing each dimension separately
nmfModel(r, n, p)

# trying to create a NMF object based on incompatible matrices generates an error
w <- rmatrix(n, r)
h <- rmatrix(r+1, p)
try( new('NMFstd', W=w, H=h) )
try( nmfModel(w, h) )
try( nmfModel(r+1, W=w, H=h) )
# The factory method can be force the model to match some target dimensions
# but warnings are thrown
nmfModel(r, W=w, H=h)
nmfModel(r, n-1, W=w, H=h)
## Empty model of given rank
nmfModel(3)
nmfModel(target=10) #square
nmfModel(target=c(10, 5))
# Build an empty NMF model
nmfModel()

# 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(H=h)

# specifies two compatible matrices
nmfModel(W=w, H=h)
# error if not compatible
try( nmfModel(W=w, H=h[-1,]) )
# create a r-ranked NMF model compatible with a given target matrix
obj <- nmfModel(r, V)
all(is.na(basis(obj)))
## From two existing factors

# allows a convenient call without argument names
w <- rmatrix(n, 3); h <- rmatrix(3, p)
nmfModel(w, h)

# Specify the type of NMF model (e.g. 'NMFns' for non-smooth NMF)
mod <- nmfModel(w, h, model='NMFns')
mod

# One can use such an NMF model as a seed when fitting a target matrix with nmf()
V <- rmatrix(mod)
res <- nmf(V, mod)
nmf.equal(res, nmf(V, mod))

# NB: when called only with such a seed, the rank and the NMF algorithm
# are selected based on the input NMF model.
# e.g. here rank was 3 and the algorithm "nsNMF" is used, because it is the default
# algorithm to fit "NMFns" models (See ?nmf).
## swapped arguments `rank` and `target`
V <- rmatrix(20, 10)
nmfModel(V) # equivalent to nmfModel(target=V)
nmfModel(V, 3) # equivalent to nmfModel(3, V)
# empty 3-rank model
nmfModel(~ 3)

# 3-rank model that fits a given data matrix
x <- rmatrix(20,10)
nmfModel(x ~ 3)

# add fixed coefficient term defined by a factor
gr <- gl(2, 5)
nmfModel(x ~ 3 + gr)

# add fixed coefficient term defined by a numeric covariate
nmfModel(x ~ 3 + gr + b, data=list(b=runif(10)))

# 3-rank model that fits a given ExpressionSet (with fixed coef terms)
e <- ExpressionSet(x)
pData(e) <- data.frame(a=runif(10))
nmfModel(e ~ 3 + gr + a) # `a` is looked up in the phenotypic data of x pData(x)
# 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)

Run the code above in your browser using DataCamp Workspace