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

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

2. 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, ...)`.

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

``````
## Generate a random matrix of a given size
rmatrix(5, 3)
``````
``````##         [,1]   [,2]   [,3]
## [1,] 0.06243 0.1101 0.8997
## [2,] 0.90294 0.5133 0.3080
## [3,] 0.02825 0.8323 0.5569
## [4,] 0.32196 0.4457 0.9992
## [5,] 0.12815 0.7559 0.2021
``````
``````## Don't show:
stopifnot( identical(dim(rmatrix(5, 3)), c(5L,3L)) )
## End Don't show

## Generate a random matrix of the same dimension of a template matrix
a <- matrix(1, 3, 4)
rmatrix(a)
``````
``````##        [,1]   [,2]   [,3]   [,4]
## [1,] 0.5755 0.1902 0.5678 0.3842
## [2,] 0.4891 0.8384 0.3627 0.5724
## [3,] 0.2043 0.8881 0.2311 0.5999
``````
``````## Don't show:
stopifnot( identical(dim(rmatrix(a)), c(3L,4L)) )
## End Don't show

## 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)
# random matrix of the same dimension as another matrix
x <- matrix(3,4)
dim(rmatrix(x))
``````
``````##  4 1
``````
``````# 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:
##D # show heatmap of the noisy target matrix: block patterns should be clear
##D aheatmap(y)
## End(Not run)
## Don't show:
stopifnot( identical(dim(y), dim(x)[1:2]) )
## End Don't show

# 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)
``````
``````## Length  Class   Mode
##      1 NMFfit     S4
``````
``````
# add more noise to the true model (drawn from uniform [0,10])
res <- nmf(rmatrix(x, max=10), 3)
summary(res)
``````
``````## Length  Class   Mode
##      1 NMFfit     S4
``````
``````
``````