makeCompressedMatrix: makeCompressedMatrix
In hiraksarkar/edgeR_fork: Empirical Analysis of Digital Gene Expression Data in R

Description Usage Arguments Details Value Class construction Class methods Author(s) See Also Examples

Construct a CompressedMatrix object from a scalar, vector or matrix.

makeCompressedMatrix(x, dims, byrow=TRUE)

## S3 method for class 'CompressedMatrix'
dim(x)
## S3 method for class 'CompressedMatrix'
length(x)

## S3 method for class 'CompressedMatrix'
x[i, j, drop=TRUE] 
## S3 replacement method for class 'CompressedMatrix'
x[i, j] <- value

## S3 method for class 'CompressedMatrix'
Ops(e1, e2)

## S3 method for class 'CompressedMatrix'
rbind(...)
## S3 method for class 'CompressedMatrix'
cbind(...)

## S3 method for class 'CompressedMatrix'
as.matrix(x, ...)

`x`	For `makeCompressedMatrix`, a scalar, vector, matrix or CompressedMatrix object. For the S3 methods, a CompressedMatrix object.
`dims`	an integer vector indicating the matrix dimensions, ignored if `x` is already a matrix
`byrow`	logical. If `x` is a vector, should it be repeated across rows (default) or across columns?
`i, j`	subset indices to apply to `x`, which behave the same as indices for `matrix` subsetting
`drop`	logical, indicating whether or not to drop dimensions when subsetting to a single row/column
`value`	an array-like object or vector to be used to replace values in `x`
`e1, e2`	a CompressedMatrix object
`...`	multiple CompressedMatrix objects for `rbind` and `cbind`. Otherwise additional arguments that are ignored in `as.matrix`.

The CompressedMatrix is used throughout edgeR to save space in storing offsets and (to a lesser extent) weights. This is because, for routine analyses, offsets are the same for all genes so it makes little sense to expand it to the full dimensions of the count matrix. Most functions will accept a CompressedMatrix as input to offset or weights arguments.

A object of class CompressedMatrix, containing x and the additional attributes repeat.row and repeat.col.

The makeCompressedMatrix function creates a CompressedMatrix object from x. The CompressedMatrix class inherits from a matrix and holds two logical scalar attributes repeat.row and repeat.col. Each attribute specifies whether the values are to be repeated across rows and/or across columns. This avoids the need to store redundant values in a full-sized matrix of dimensions dim, as would be done with expandAsMatrix.

To illustrate, consider that rows usually correspond to genes while columns usually correspond to libraries. If we have a vector of library sizes, this will hold one unique value per library that is the same for all genes. Thus, we should use byrow=TRUE, which will construct a CompressedMatrix object storing one row containing this vector. Here, repeat.row=TRUE and repeat.col=FALSE, indicating that the row is to be repeated for all genes.

On the other hand, we may have a vector of gene-specific values that is the same for all libraries (e.g., dispersions). In this case, we should use byrow=FALSE to construct the CompressedMatrix object. This will store one column with repeat.row=FALSE and repeat.col=TRUE, indicating that the column should be repeated across libraries.

In cases where x is a scalar, byrow is ignored and both repeat.row and repeat.col will be TRUE by default. If x is a matrix, both attributes will be FALSE. If x is a CompressedMatrix, it will be returned without modification.

Subsetting of a CompressedMatrix object depends on the values of repeat.row and repeat.col. If the rows are repeated, any subsetting by row will be effectively ignored, only altering the stored dimensions of x without changing the values. Similarly, if the columns are repeated, any subsetting by column will be ignored. If neither are repeated, subsetting behaves as it would for a normal matrix.

Combining of a CompressedMatrix object will also make use of the repeat structure. If rows are repeated in all objects to be combined, the output of cbind will also have repeated rows. Similarly, if columns are repeated, the output of rbind will also have repeated columns. Otherwise, all objects are expanded to their full size prior to combining.

Binary operators work on pairs of CompressedMatrix objects, again preserving the repeat structure whenever possible. Extracting dimensions uses a second Dims field in the attributes, bypassing the dim for a base matrix. Calling as.matrix on a CompressedMatrix object will return the ordinary (uncompressed) matrix.

Aaron Lun

as.matrix, expandAsMatrix

# Repeated rows:
library.sizes <- runif(4, 1e6, 2e6)
lib.mat <- makeCompressedMatrix(library.sizes, c(10, 4), byrow=TRUE)
lib.mat

lib.mat[,1:2] # subset by column works as expected
lib.mat[1:10,] # subset by row has no effect (see Details)
as.matrix(lib.mat)

# Repeated columns:
gene.disp <- runif(10, 0.01, 0.1)
disp.mat <- makeCompressedMatrix(gene.disp, c(10, 4), byrow=FALSE)
disp.mat

disp.mat[,1:2] # subset by column has no effect
disp.mat[1:5,] # subset by row works as expected
as.matrix(disp.mat)

# Scalar:
weights <- makeCompressedMatrix(1, c(10, 4))
weights[1:10,] # subsetting has no effect
weights[,1:10]
as.matrix(weights)

# Matrix:
offsets <- makeCompressedMatrix(matrix(runif(40), 10, 4))
offsets[1:5,]
offsets[,1:2]
as.matrix(offsets)