extract_sparse_array: extract_sparse_array

In Bioconductor/SparseArray: High-performance sparse data representation and manipulation in R

extract_sparse_array

Description

extract_sparse_array() is an internal generic function that is the workhorse behind the default read_block_as_sparse() method. It is not intended to be used directly by the end user.

It is similar to the extract_array() internal generic function defined in the S4Arrays package, with the major difference that, in the case of extract_sparse_array(), the extracted array data is returned as a SparseArray object instead of an ordinay array.

Usage

extract_sparse_array(x, index)

## S4 method for signature 'ANY'
extract_sparse_array(x, index)

Arguments

x

An array-like object for which is_sparse(x) is TRUE.

index

An unnamed list of integer vectors, one per dimension in x. Each vector is called a subscript and can only contain positive integers that are valid 1-based indices along the corresponding dimension in x. Empty or missing subscripts are allowed. They must be represented by list elements set to integer(0) or NULL, respectively. The subscripts cannot contain NAs or non-positive values. Individual subscripts are NOT allowed to contain duplicated indices. This is an important difference with extract_array.

Details

extract_sparse_array() should always be called on an array-like object x for which is_sparse(x) is TRUE. Also it should never be called with duplicated indices in the individual list elements of the index argument.

For maximum efficiency, extract_sparse_array() methods should:

1. NOT check that is_sparse(x) is TRUE.

2. NOT check that the individual list elements in index contain no duplicated indices.

3. NOT try to do anything with the dimnames on x.

4. always operate natively on the sparse representation of the data in x, that is, they should never expand it into a dense representation (e.g. with as.array()).

Like for extract_array(), extract_sparse_array() methods need to support empty or missing subscripts. For example, if x is an M x N matrix-like object for which is_sparse(x) is TRUE, then extract_sparse_array(x, list(NULL, integer(0))) must return an M x 0 SparseArray derivative, and extract_sparse_array(x, list(integer(0), integer(0))) a 0 x 0 SparseArray derivative.

Value

A SparseArray derivative (COO_SparseArray or SVT_SparseArray) of the same type() as x. For example, if x is an object representing an M x N sparse matrix of complex numbers (i.e. type(x) == "complex"), then extract_sparse_array(x, list(NULL, 2L)) must return the 2nd column in x as an M x 1 SparseArray derivative of type() "complex".

See Also

• is_sparse in the S4Arrays package to check whether an object uses a sparse representation of the data or not.

• SparseArray objects.

• S4Arrays::type in the S4Arrays package to get the type of the elements of an array-like object.

• read_block_as_sparse to read array blocks as SparseArray objects.

• extract_array in the S4Arrays package.

• dgCMatrix objects implemented in the Matrix package.

Examples

extract_sparse_array
showMethods("extract_sparse_array")

## --- On a dgCMatrix object ---

m <- matrix(0L, nrow=6, ncol=4)
m[c(1:2, 8, 10, 15:17, 24)] <- (1:8)*10L
dgcm <- as(m, "dgCMatrix")
dgcm

extract_sparse_array(dgcm, list(3:6, NULL))
extract_sparse_array(dgcm, list(3:6, 2L))
extract_sparse_array(dgcm, list(3:6, integer(0)))

## --- On a SparseArray object ---

a <- array(0L, dim=5:3, dimnames=list(letters[1:5], NULL, LETTERS[1:3]))
a[c(1:2, 8, 10, 15:17, 20, 24, 40, 56:60)] <- (1:15)*10L
svt <- as(a, "SparseArray")
svt

extract_sparse_array(svt, list(NULL, 4:2, 1L))
extract_sparse_array(svt, list(NULL, 4:2, 2:3))
extract_sparse_array(svt, list(NULL, 4:2, integer(0)))

Bioconductor/SparseArray documentation built on Nov. 14, 2024, 6:22 p.m.