NMF (version 0.2.2)

rnmf: Generating Random NMF Models

Description

Generates NMF models with random values drawn from a uniform distribution. It returns an NMF model with basis and mixture coefficient matrices filled with random values. The main purpose of the function rnmf is to provide a common interface to generate random seeds used by the nmf function.

Usage

rnmf(x, target, ...)
  ## S3 method for class 'NMF,numeric':
rnmf(x, target, ncol = NULL,
    keep.names = TRUE, dist = runif)
  ## S3 method for class 'ANY,matrix':
rnmf(x, target, ...,
    dist = list(max = max(max(target, na.rm = TRUE), 1)),
    use.dimnames = TRUE)
  ## S3 method for class 'numeric,missing':
rnmf(x, target, ..., W, H,
    dist = runif)
  ## S3 method for class 'missing,missing':
rnmf(x, target, ..., W, H)
  ## S3 method for class 'numeric,numeric':
rnmf(x, target, ncol = NULL,
    ..., dist = runif)
  ## S3 method for class 'formula,ANY':
rnmf(x, target, ...,
    dist = runif)

Arguments

x

an object that determines the rank, dimension and/or class of the generated NMF model, e.g. a numeric value or an object that inherits from class NMF. See the description of the specific methods for more det

target

optional specification of target dimensions. See section Methods for how this parameter is used by the different methods.

...

extra arguments to allow extensions and passed to the next method eventually down to nmfModel, where they are used to initialise slots that are specific to the instantiating NMF model.

ncol

single numeric value that specifies the number of columns of the coefficient matrix. Only used when target is a single numeric value.

keep.names

a logical that indicates if the dimension names of the original NMF object x should be conserved (TRUE) or discarded (FALSE).

dist

specification of the random distribution to use to draw the entries of the basis and coefficient matrices. It may be specified as:

• afunctionwhich must be a distribution function such as e.g.ru

use.dimnames

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

W

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

H

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

Value

• An NMF model, i.e. an object that inherits from class NMF.

Details

If necessary, extensions of the standard NMF model or custom models must define a method "rnmf,,numeric" for initialising their specific slots other than the basis and mixture coefficient matrices. In order to benefit from the complete built-in interface, the overloading methods should call the generic version using function callNextMethod, prior to set the values of the specific slots. See for example the method rnmf defined for NMFOffset models: showMethods(rnmf, class='NMFOffset', include=TRUE)).

For convenience, shortcut methods 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.

See Also

rmatrix

Other NMF-interface: basis, .basis, .basis<-, basis<-, coef, .coef, .coef<-, coef<-, coefficients, .DollarNames,NMF-method, loadings,NMF-method, misc, NMF-class, $<-,NMF-method, $,NMF-method, nmfModel, nmfModels, scoef

Examples

# roxygen generated flag
options(R_CHECK_RUNNING_EXAMPLES_=TRUE)

#----------
# rnmf,NMFOffset,numeric-method
#----------
# random NMF model with offset
x <- rnmf(2, 3, model='NMFOffset')
x
offset(x)
# from a matrix
x <- rnmf(2, rmatrix(5,3, max=10), model='NMFOffset')
offset(x)

#----------
# rnmf,NMF,numeric-method
#----------
## random NMF of same class and rank as another model

x <- nmfModel(3, 10, 5)
x
rnmf(x, 20) # square
rnmf(x, 20, 13)
rnmf(x, c(20, 13))

# using another distribution
rnmf(x, 20, dist=rnorm)

# other than standard model
y <- rnmf(3, 50, 10, model='NMFns')
y
stopifnot( identical(dim(y), c(50L,10L,3L)) )
stopifnot( is(y, 'NMFns') )

#----------
# rnmf,ANY,matrix-method
#----------
# random NMF compatible with a target matrix
x <- nmfModel(3, 10, 5)
y <- rmatrix(20, 13)
rnmf(x, y) # rank of x
rnmf(2, y) # rank 2

#----------
# rnmf,NMF,missing-method
#----------
## random NMF from another model

a <- nmfModel(3, 100, 20)
b <- rnmf(a)
stopifnot( !nmf.equal(a,b) )

#----------
# rnmf,numeric,missing-method
#----------
# random NMF model with known basis matrix
x <- rnmf(5, W=matrix(1:18, 6)) # 6 x 5 model with rank=3
basis(x) # fixed
coef(x) # random

# random NMF model with known coefficient matrix
x <- rnmf(5, H=matrix(1:18, 3)) # 5 x 6 model with rank=3
basis(x) # random
coef(x) # fixed

# random model other than standard NMF
x <- rnmf(5, H=matrix(1:18, 3), model='NMFOffset')
basis(x) # random
coef(x) # fixed
offset(x) # random

#----------
# rnmf,missing,missing-method
#----------
# random model other than standard NMF
x <- rnmf(W=matrix(1:18, 6), H=matrix(21:38, 3), model='NMFOffset')
basis(x) # fixed
coef(x) # fixed
offset(x) # random

#----------
# rnmf,numeric,numeric-method
#----------
## random standard NMF of given dimensions

# generate a random NMF model with rank 3 that fits a 100x20 matrix
rnmf(3, 100, 20)
stopifnot( identical(dim(rnmf(3, 100, 20)), c(100L,20L,3L)) )
# generate a random NMF model with rank 3 that fits a 100x100 matrix
rnmf(3, 100)
stopifnot( identical(dim(rnmf(3, 100)), c(100L,100L,3L)) )