NMF (version 0.28)

rmatrix: Generating Random Matrices

Description

The S4 generic rmatrix generates a random matrix from a given object. Methods are provided to generate matrices with entries drawn from any given random distribution function, e.g. runif or rnorm.

Usage

rmatrix(x, ...)
  # S4 method for numeric
rmatrix(x, y = NULL, dist = runif,
    byrow = FALSE, dimnames = NULL, ...)

Arguments

x

object from which to generate a random matrix

y

optional specification of number of columns

dist

a random distribution function or a numeric seed (see details of method rmatrix,numeric)

byrow

a logical passed in the internal call to the function matrix

dimnames

NULL or a list passed in the internal call to the function matrix

...

extra arguments passed to the distribution function dist.

Methods

rmatrix

signature(x = "numeric"): Generates a random matrix of given dimensions, whose entries are drawn using the distribution function dist.

This is the workhorse method that is eventually called by all other methods. It returns a matrix with:

• x rows and y columns if y is not missing and not NULL;

• dimension x[1] x x[2] if x has at least two elements;

• dimension x (i.e. a square matrix) otherwise.

The default is to draw its entries from the standard uniform distribution using the base function runif, but any other function that generates random numeric vectors of a given length may be specified in argument dist. All arguments in ... are passed to the function specified in dist.

The only requirement is that the function in dist is of the following form:

function(n, ...){ # return vector of length n ... }

This is the case of all base random draw function such as rnorm, rgamma, etc...

rmatrix

signature(x = "ANY"): Default method which calls rmatrix,vector on the dimensions of x that is assumed to be returned by a suitable dim method: it is equivalent to rmatrix(dim(x), y=NULL, ...).

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.

Examples

# roxygen generated flag
options(R_CHECK_RUNNING_EXAMPLES_=TRUE)


#----------
# rmatrix,numeric-method
#----------
## Generate a random matrix of a given size
rmatrix(5, 3)
 stopifnot( identical(dim(rmatrix(5, 3)), c(5L,3L)) ) 

## Generate a random matrix of the same dimension of a template matrix
a <- matrix(1, 3, 4)
rmatrix(a)
 stopifnot( identical(dim(rmatrix(a)), c(3L,4L)) ) 

## Specificy the distribution to use

# the default is uniform
a <- rmatrix(1000, 50)
if (FALSE)  hist(a) 

# use normal ditribution
a <- rmatrix(1000, 50, rnorm)
if (FALSE)  hist(a) 

# extra arguments can be passed to the random variate generation function
a <- rmatrix(1000, 50, rnorm, mean=2, sd=0.5)
if (FALSE)  hist(a) 

#----------
# rmatrix,ANY-method
#----------
# random matrix of the same dimension as another matrix
x <- matrix(3,4)
dim(rmatrix(x))

#----------
# rmatrix,NMF-method
#----------
# generate noisy fitted target from an NMF model (the true model)
gr <- as.numeric(mapply(rep, 1:3, 3))
h <- outer(1:3, gr, '==') + 0
x <- rnmf(10, H=h)
y <- rmatrix(x)
if (FALSE) {
# show heatmap of the noisy target matrix: block patterns should be clear
aheatmap(y)
}
 stopifnot( identical(dim(y), dim(x)[1:2]) ) 

# test NMF algorithm on noisy data
# add some noise to the true model (drawn from uniform [0,1])
res <- nmf(rmatrix(x), 3)
summary(res)

# add more noise to the true model (drawn from uniform [0,10])
res <- nmf(rmatrix(x, max=10), 3)
summary(res)