SparseArraySeed-class: SparseArraySeed objects

In Bioconductor/DelayedArray: A unified framework for working transparently with on-disk and in-memory array-like datasets

SparseArraySeed objects

Description

SparseArraySeed objects are used internally to support block processing of array-like objects.

Usage

## Constructor function:
SparseArraySeed(dim, nzindex=NULL, nzdata=NULL, dimnames=NULL, check=TRUE)

## Getters (in addition to dim(), length(), and dimnames()):
nzindex(x)
nzdata(x)
sparsity(x)

## Two low-level utilities:
dense2sparse(x)
sparse2dense(sas)

Arguments

dim	The dimensions (specified as an integer vector) of the SparseArraySeed object to create.
nzindex	A matrix containing the array indices of the nonzero data. This must be an integer matrix like one returned by base::arrayInd, that is, with length(dim) columns and where each row is an n-uplet representing an array index.
nzdata	A vector (atomic or list) of length nrow(nzindex) containing the nonzero data.
dimnames	The dimnames of the object to be created. Must be NULL or a list of length the number of dimensions. Each list element must be either NULL or a character vector along the corresponding dimension.
check	Should the object be validated upon construction?
x	A SparseArraySeed object for the nzindex, nzdata, and sparsity getters. An array-like object for dense2sparse.
sas	A SparseArraySeed object.

Value

• For SparseArraySeed(): A SparseArraySeed instance.

• For nzindex(): The matrix containing the array indices of the nonzero data.

• For nzdata(): The vector of nonzero data.

• For sparsity(): The number of zero-valued elements in the implicit array divided by the total number of array elements (a.k.a. the length of the array).

• For dense2sparse(): A SparseArraySeed instance.

• For sparse2dense(): An ordinary array.

See Also

• SparseArraySeed-utils for native operations on SparseArraySeed objects.

• S4 classes dgCMatrix, dgRMatrix, and lsparseMatrix, defined in the Matrix package, for the de facto standard of sparse matrix representations in R.

• The read_block function in the S4Arrays package.

• blockApply and family for convenient block processing of an array-like object.

• extract_array in the S4Arrays package.

• DelayedArray objects.

• arrayInd in the base package.

• array objects in base R.

Examples

## ---------------------------------------------------------------------
## EXAMPLE 1
## ---------------------------------------------------------------------
dim1 <- 5:3
nzindex1 <- Lindex2Mindex(sample(60, 8), 5:3)
nzdata1 <- 11.11 * seq_len(nrow(nzindex1))
sas1 <- SparseArraySeed(dim1, nzindex1, nzdata1)

dim(sas1)        # the dimensions of the implicit array
length(sas1)     # the length of the implicit array
nzindex(sas1)
nzdata(sas1)
type(sas1)
sparsity(sas1)

sparse2dense(sas1)
as.array(sas1)   # same as sparse2dense(sas1)

## Not run: 
as.matrix(sas1)  # error!

## End(Not run)
## ---------------------------------------------------------------------
## EXAMPLE 2
## ---------------------------------------------------------------------
m2 <- matrix(c(5:-2, rep.int(c(0L, 99L), 11)), ncol=6)
sas2 <- dense2sparse(m2)
class(sas2)
dim(sas2)
length(sas2)
nzindex(sas2)
nzdata(sas2)
type(sas2)
sparsity(sas2)

stopifnot(identical(sparse2dense(sas2), m2))

as.matrix(sas2)  # same as sparse2dense(sas2)

t(sas2)
stopifnot(identical(as.matrix(t(sas2)), t(as.matrix(sas2))))

## ---------------------------------------------------------------------
## COERCION FROM/TO dg[C|R]Matrix OR lg[C|R]Matrix OBJECTS
## ---------------------------------------------------------------------
## dg[C|R]Matrix and lg[C|R]Matrix objects are defined in the Matrix
## package.

## dgCMatrix/dgRMatrix:

M2C <- as(sas2, "dgCMatrix")
stopifnot(identical(M2C, as(m2, "dgCMatrix")))

sas2C <- as(M2C, "SparseArraySeed")
## 'sas2C' is the same as 'sas2' except that 'nzdata(sas2C)' has
## type "double" instead of "integer":
stopifnot(all.equal(sas2, sas2C))
typeof(nzdata(sas2C))  # double
typeof(nzdata(sas2))   # integer

M2R <- as(sas2, "dgRMatrix")
stopifnot(identical(M2R, as(m2, "dgRMatrix")))
sas2R <- as(M2R, "SparseArraySeed")
stopifnot(all.equal(as.matrix(sas2), as.matrix(sas2R)))

## lgCMatrix/lgRMatrix:

m3 <- m2 == 99  # logical matrix
sas3 <- dense2sparse(m3)
class(sas3)
type(sas3)

M3C <- as(sas3, "lgCMatrix")
stopifnot(identical(M3C, as(m3, "lgCMatrix")))
sas3C <- as(M3C, "SparseArraySeed")
identical(as.matrix(sas3), as.matrix(sas3C))

M3R <- as(sas3, "lgRMatrix")
#stopifnot(identical(M3R, as(m3, "lgRMatrix")))
sas3R <- as(M3R, "SparseArraySeed")
identical(as.matrix(sas3), as.matrix(sas3R))

## ---------------------------------------------------------------------
## SEED CONTRACT
## ---------------------------------------------------------------------
## SparseArraySeed objects comply with the "seed contract".
## In particular they support extract_array():
extract_array(sas1, list(c(5, 3:2, 5), NULL, 3))

## See '?extract_array' in the S4Arrays package for more information
## about the "seed contract".

## This means that they can be wrapped in a DelayedArray object:
A1 <- DelayedArray(sas1)
A1

## A big very sparse DelayedMatrix object:
nzindex4 <- cbind(sample(25000, 600000, replace=TRUE),
                  sample(195000, 600000, replace=TRUE))
nzdata4 <- runif(600000)
sas4 <- SparseArraySeed(c(25000, 195000), nzindex4, nzdata4)
sparsity(sas4)

M4 <- DelayedArray(sas4)
M4
colSums(M4[ , 1:20])

Bioconductor/DelayedArray documentation built on March 4, 2024, 9:12 p.m.