# rmatrix: Generating Random Matrices In NMF: Algorithms and Framework for Nonnegative Matrix Factorization (NMF)

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

 ```1 2 3 4 5``` ``` rmatrix(x, ...) ## S4 method for signature '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` x `x` 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

 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56``` ```#---------- # rmatrix,numeric-method #---------- ## Generate a random matrix of a given size rmatrix(5, 3) ## Generate a random matrix of the same dimension of a template matrix a <- matrix(1, 3, 4) rmatrix(a) ## Specificy the distribution to use # the default is uniform a <- rmatrix(1000, 50) ## Not run: hist(a) # use normal ditribution a <- rmatrix(1000, 50, rnorm) ## Not run: hist(a) # extra arguments can be passed to the random variate generation function a <- rmatrix(1000, 50, rnorm, mean=2, sd=0.5) ## Not run: 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) ## Not run: # show heatmap of the noisy target matrix: block patterns should be clear aheatmap(y) ## End(Not run) # 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) ```

NMF documentation built on Aug. 1, 2020, 9:06 a.m.