BumpyMatrix: The BumpyMatrix class
In LTLA/BumpyMatrix: Bumpy Matrix of Non-Scalar Objects

Description Constructor Basic matrix methods Subsetting by another BumpyMatrix Special CompressedList methods Other methods Author(s) Examples

View source: R/BumpyMatrix.R

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.

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.

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

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.

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

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.

Aaron Lun

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