extract_array: extract_array

In Bioconductor/S4Arrays: Foundation of array-like containers in Bioconductor

extract_array

Description

extract_array is an internal generic function not intended to be used directly by the end user. It has methods defined for array, data.frame, DataFrame objects, and other array-like objects.

Note that extract_array is part of the seed contract as defined in the Implementing A DelayedArray Backend vignette from the DelayedArray package.

Usage

## The extract_array() S4 generic:

extract_array(x, index)

## extract_array() methods defined in the S4Arrays package:

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

## S4 method for signature 'array'
extract_array(x, index)

## S4 method for signature 'data.frame'
extract_array(x, index)

## S4 method for signature 'DataFrame'
extract_array(x, index)

Arguments

x

An array-like object. This can be an ordinary array, a SparseArray object from the SparseArray package, a dgCMatrix object from the Matrix package, a DelayedArray object from the DelayedArray package, or any object with an array semantic (i.e. an object for which dim(x) is not NULL). Note that data.frame and DataFrame objects are also supported.

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 allowed to contain duplicated indices.

Details

extract_array() methods need to support empty or missing subscripts. For example, if x is an M x N matrix-like object, then extract_array(x, list(NULL, integer(0))) must return an M x 0 ordinary matrix, and extract_array(x, list(integer(0), integer(0))) a 0 x 0 ordinary matrix.

Also subscripts are allowed to contain duplicated indices so things like extract_array(x, list(c(1:3, 3:1), 2L)) need to be supported.

Finally, for maximum efficiency, extract_array() methods should not try to do anything with the dimnames on x.

Value

An ordinary array of the same type() as x. For example, if x is an object representing an M x N matrix of complex numbers (i.e. type(x) == "complex"), then extract_array(x, list(NULL, 2L)) must return the 2nd column in x as an M x 1 ordinary matrix of type() "complex".

See Also

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

• array and data.frame objects in base R.

• SparseArray objects implemented in the SparseArray package.

• DelayedArray objects implemented in the DelayedArray package.

• DataFrame objects implemented in the S4Vectors package.

Examples

extract_array
showMethods("extract_array")

## extract_array() works on array-like objects like SparseArray objects,
## dgCMatrix objects, DataFrame objects, etc...

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

library(SparseArray)
a <- array(0L, 5:3)
a[c(1:2, 8, 10, 15:17, 20, 24, 40, 56:60)] <- (1:15)*10L
svt <- as(a, "SparseArray")
svt

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

## Sanity checks:
stopifnot(
  identical(extract_array(svt, list(NULL, c(4L,2L,4L), 1L)),
            as.array(svt)[ , c(4L,2L,4L), 1L, drop=FALSE]),
  identical(extract_array(svt, list(NULL, c(4L,2L,4L), 2:3)),
            as.array(svt)[ , c(4L,2L,4L), 2:3]),
  identical(extract_array(svt, list(NULL, c(4L,2L,4L), integer(0))),
            as.array(svt)[ , c(4L,2L,4L), integer(0)])
)

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

library(Matrix)
m <- a[ , , 1]
dgcm <- as(m, "dgCMatrix")
dgcm

extract_array(dgcm, list(NULL, c(4L,2L,4L)))

## Sanity check:
stopifnot(
  identical(extract_array(dgcm, list(NULL, c(4L,2L,4L))),
            as.matrix(dgcm)[ , c(4L,2L,4L)])
)

## --- On a data.frame or DataFrame object ---

df <- data.frame(a=44:49, b=letters[1:6], c=c(TRUE, FALSE))
DF <- as(df, "DataFrame")

extract_array(df, list(4:2, c(1L,3L)))
extract_array(DF, list(4:2, c(1L,3L)))

## Sanity check:
target <- as.matrix(df)[4:2, c(1L,3L)]
dimnames(target) <- NULL
stopifnot(
  identical(extract_array(df, list(4:2, c(1L,3L))), target),
  identical(extract_array(DF, list(4:2, c(1L,3L))), target)
)

Bioconductor/S4Arrays documentation built on May 1, 2024, 9:27 p.m.