BumpyMatrix {BumpyMatrix} | R Documentation

## The BumpyMatrix class

### Description

The BumpyMatrix provides a two-dimensional object where each entry is a Vector object. This is useful for storing data that has a variable number of observations per sample/feature combination, e.g., for inclusion as another assay in a SummarizedExperiment object.

### Constructor

`BumpyMatrix(x, dims, dimnames=list(NULL, NULL), proxy=NULL, reorder=TRUE)` will produce a BumpyMatrix object, given:

- `x`, a CompressedList object containing one or more DFrames or atomic vectors.

- `dim`, an integer vector of length 2 specifying the dimensions of the returned object.

- `dimnames`, a list of length 2 containing the row and column names.

- `proxy`, an integer or numeric matrix-like object specifying the location of each entry of `x` in the output matrix.

- `reorder`, a logical scalar indicating whether `proxy` (if specified) should be reordered.

The type of the returned BumpyMatrix object is determined from the type of `x`.

If `proxy=NULL`, `x` should have length equal to the product of `dim`. The entries of the returned BumpyMatrix are filled with `x` in a column-major manner.

If `proxy` is specified, it should contain indices in `1:length(x)` with all other entries filled with zeros. If `reorder=FALSE`, all non-zero values should be in increasing order when encountered in column-major format; otherwise, the indices are resorted to enforce this expectation. Note that `dims` and `dimnames` are ignored.

If `x` is missing, a BumpyIntegerMatrix is returned with zero rows and columns. If `dim` is also specified, a BumpyIntegerMatrix with the specified number of rows and columns is returned, where each entry is an empty integer vector.

### Basic matrix methods

In the following code snippets, `x` is an instance of a BumpyMatrix subclass.

`dim(x)` will yield a length-2 integer vector containing the number of rows and columns in `x`. `length(x)` will yield the product of the number of columns and rows.

`dimnames(x)` will yield a list of two character vectors with the row and column names of `x`. Either or both elements of the list may be `NULL` if no names are present.

`x[i, j, ..., drop=TRUE]` will yield the specified submatrix of the same type as `x`, given integer, character or logical subsetting vectors in `i` and `j`. If the resulting submatrix has any dimension of length 1 and `drop=TRUE`, a CompressedList of the appropriate type is instead returned.

`x[i,j] <- value` will replace the specified entries in `x` with the values in another BumpyMatrix `value`. It is expected that `value` is of the same subclass as `x`. `value` can also be a CompressedList of the same class as `undim(x)`, in which case it is recycled to fill the specified entries.

`t(x)` will transpose the BumpyMatrix, returning an object of the same type.

`rbind(..., deparse.level=1)` and `cbind(..., deparse.level=1)` will combine all BumpyMatrix objects in `...`, yielding a single BumpyMatrix object containing all the rows and columns, respectively. All objects should have the same number of columns (for `rbind`) or rows (for `cbind`).

### Subsetting by another BumpyMatrix

Given a BumpyMatrix `x` and an appropriate BumpyMatrix `i`, `x[i]` will return another BumpyMatrix where each entry of `x` is subsetted by the corresponding entry of `i`. This usually requires `i` to be a BumpyIntegerMatrix or a BumpyLogicalMatrix, though it is also possible to use a BumpyCharacterMatrix if each entry of `x` is named.

### Special CompressedList methods

`undim(x)` will return the underlying CompressedList object.

`redim(flesh, skeleton)` will create a BumpyMatrix object, given a CompressedList `flesh` and an existing BumpyMatrix object `skeleton`. `flesh` is assumed to be of the same length as `undim(skeleton)` where each entry in the former replaces the corresponding entry in the latter. The class of the output is determined based on the class of `flesh`. This method is analogous to the `relist` function for lists.

`unlist(x, ...)` will return the underlying Vector used to create the CompressedList object. This is the same as `unlist(undim(x), ...)`.

### Other methods

`lengths(x)` will return a numeric matrix-like object with the same dimensions and dimnames as `x`, where each entry contains the length of the corresponding entry in `x`. The output class can be anything used in the `proxy` of the constructor, e.g., a sparse matrix from the Matrix package.

### Author(s)

Aaron Lun

### Examples

    # Mocking up a BumpyNumericList:
    library(IRanges)
    x <- NumericList(split(runif(1000), factor(sample(50, 1000, replace=TRUE), 1:50)))
    length(x)

    # Creating a BumpyNumericMatrix:
    mat <- BumpyMatrix(x, c(10, 5))
    mat

    # Standard subsetting works correctly:
    mat[1:10,1:2]
    mat[,1]
    mat[1,]

    # Subsetting by another BumpyMatrix.
    is.big <- x > 0.9
    i <- BumpyMatrix(is.big, dim(mat))
    out <- mat[i]
    out # same dimensions as mat...
    out[,1] # but the entries are subsetted.
    out[1,]

    # Subset replacement works correctly:
    mat[,2]
    alt <- mat
    alt[,2] <- mat[,1,drop=FALSE]
    alt[,2]

    # Combining works correctly:
    rbind(mat, mat)
    cbind(mat, mat)

    # Transposition works correctly:
    mat[1,2]
    tmat <- t(mat)
    tmat
    tmat[1,2]

    # Get the underlying objects:
    undim(mat)
    summary(unlist(mat))

[Package BumpyMatrix version 1.2.0 Index]