rmatrix {NMF} | R Documentation

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

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

[Package NMF version 0.20.6 Index]