read_block: Read array blocks

Description Usage Arguments Value See Also Examples

Description

Use read_block to read a block from an array-like object. The function is typically used in the context of block processing of array-like objects (typically DelayedArray objects but not necessarily).

Usage

1
read_block(x, viewport, as.sparse=FALSE)

Arguments

x

An array-like object, typically a DelayedArray object or derivative.

viewport

An ArrayViewport object compatible with x, that is, such that refdim(viewport) is identical to dim(x).

as.sparse

Can be FALSE, TRUE, or NA.

If FALSE (the default), the block is returned as an ordinary array (a.k.a. dense array). If TRUE, it's returned as a SparseArraySeed object. Using as.sparse=NA is equivalent to using as.sparse=is_sparse(x) and is the most efficient way to read a block. (This might become the default in the future.)

Note that when returned as a 2D SparseArraySeed object with numeric or logical data, a block can easily and efficiently be coerced to a sparseMatrix derivative from the Matrix package with as(block, "sparseMatrix"). This will return a dgCMatrix object if type(block) is "double" or "integer", or a lgCMatrix object if it's "logical".

Value

The data from x that belongs to the block delimited by the specified viewport. The data is returned as an ordinary (dense) array or as a SparseArraySeed object. In both cases it has the same dimensions as the viewport.

See Also

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
## ---------------------------------------------------------------------
## TYPICAL USE
## ---------------------------------------------------------------------
## read_block() is typically used in combination with write_block().
## See '?write_block' for typical uses of the read_block/write_block
## combo.

## ---------------------------------------------------------------------
## VERY BASIC (BUT ALSO VERY ARTIFICIAL) EXAMPLE 1:
## Read a block from an ordinary matrix
## ---------------------------------------------------------------------
m1 <- matrix(1:30, ncol=5)
m1

## Define the viewport on 'm1' to read the data from:
block1_dim <- c(4, 3)
viewport1 <- ArrayViewport(dim(m1), IRanges(c(3, 2), width=block1_dim))
viewport1

## Read the block:
block1 <- read_block(m1, viewport1)  # same as m1[3:6, 2:4, drop=FALSE]
block1

## Sanity checks:
stopifnot(identical(dim(viewport1), dim(block1)))
stopifnot(identical(m1[3:6, 2:4, drop=FALSE], block1))

## ---------------------------------------------------------------------
## VERY BASIC (BUT ALSO VERY ARTIFICIAL) EXAMPLE 2:
## Read a block from a sparse matrix
## ---------------------------------------------------------------------
m2 <- rsparsematrix(12, 20, density=0.2,
                    rand.x=function(n) sample(25, n, replace=TRUE))
m2

## Define the viewport on 'm2' to read the data from:
block2_dim <- c(2, 20)
viewport2 <- ArrayViewport(dim(m2), IRanges(c(1, 1), width=block2_dim))
viewport2

## By default, read_block() always returns an ordinary matrix or array:
block2 <- read_block(m2, viewport2)
block2

## It is recommended to use 'as.sparse=NA' rather than 'as.sparse=TRUE'
## or 'as.sparse=FALSE' to let read_block() pick up the optimal
## representation:
block2b <- read_block(m2, viewport2, as.sparse=NA)
class(block2b)  # a SparseArraySeed object
as(block2b, "sparseMatrix")

## For comparison, using 'as.sparse=NA' on 'm1' still returns the
## block as an ordinary matrix (a.k.a. dense matrix):
read_block(m1, viewport1, as.sparse=NA)

## Sanity checks:
stopifnot(identical(dim(viewport2), dim(block2)))
stopifnot(identical(dim(viewport2), dim(block2b)))
stopifnot(identical(block2, as.array(block2b)))

## ---------------------------------------------------------------------
## VERY BASIC (BUT ALSO VERY ARTIFICIAL) EXAMPLE 3:
## Read a block from a 3D array
## ---------------------------------------------------------------------
a3 <- array(1:60, 5:3)

## Define the viewport on 'a3' to read the data from:
block3_dim <- c(2, 4, 1)
viewport3 <- ArrayViewport(dim(a3), IRanges(c(1, 1, 3), width=block3_dim))
viewport3

## Read the block:
block3 <- read_block(a3, viewport3)  # same as a3[1:2, 1:4, 3, drop=FALSE]
block3

## Note that unlike [, read_block() never drops dimensions.

## Sanity checks:
stopifnot(identical(dim(viewport3), dim(block3)))
stopifnot(identical(a3[1:2, 1:4, 3, drop=FALSE], block3))

DelayedArray documentation built on March 25, 2021, 6:01 p.m.