Simplify a tree of delayed operations

NOTE: The tools documented in this man page are primarily intended for developers or advanced users curious about the internals of the DelayedArray package. End users typically don't need them for their regular use of DelayedArray objects.

In a DelayedArray object, the delayed operations are stored as a tree of DelayedOp objects. See ?DelayedOp for more information about this tree.

simplify can be used to simplify the tree of delayed operations in a DelayedArray object.

isPristine can be used to know whether a DelayedArray object is pristine or not. A DelayedArray object is considered pristine when it carries no delayed operation. Note that an object that carries delayed operations that do nothing (e.g. A + 0) is not considered pristine.

contentIsPristine can be used to know whether the delayed operations in a DelayedArray object touch its array elements or not.

netSubsetAndAperm returns an object that represents the net subsetting and net dimension rearrangement of all the delayed operations in a DelayedArray object.

Usage

simplify(x, incremental=FALSE)

isPristine(x, ignore.dimnames=FALSE)
contentIsPristine(x)
netSubsetAndAperm(x, as.DelayedOp=FALSE)

Arguments

x: Typically a DelayedArray object but can also be a DelayedOp object (except for isPristine).
incremental: For internal use.
ignore.dimnames: TRUE or FALSE. When TRUE, the object is considered pristine even if its dimnames have been modified and no longer match the dimnames of its seed (in which case the object carries a single delayed operations of type DelayedSetDimnames).
as.DelayedOp: TRUE or FALSE. Controls the form of the returned object. See details below.

Details

netSubsetAndAperm is only supported on a DelayedArray object x with a single seed i.e. if nseed(x) == 1.

The mapping between the array elements of x and the array elements of its seed is affected by the following delayed operations carried by x: [, drop(), and aperm(). x can carry any number of each of these operations in any order but their net result can always be described by a net subsetting followed by a net dimension rearrangement.

netSubsetAndAperm(x) returns an object that represents the net subsetting and net dimension rearrangement. The as.DelayedOp argument controls in what form this object should be returned:

If as.DelayedOp is FALSE (the default), the returned object is a list of subscripts that describes the net subsetting. The list contains one subscript per dimension in the seed. Each subscript can be either a vector of positive integers or a NULL. A NULL indicates a missing subscript. In addition, if x carries delayed operations that rearrange its dimensions (i.e. operations that drop and/or permute some of the original dimensions), the net dimension rearrangement is described in a dimmap attribute added to the list. This attribute is an integer vector parallel to dim(x) that reports how the dimensions of x are mapped to the dimensions of its seed.
If as.DelayedOp is TRUE, the returned object is a linear tree with 2 DelayedOp nodes and a leaf node. The leaf node is the seed of x. Walking the tree from the seed, the 2 DelayedOp nodes are of type DelayedSubset and DelayedAperm, in that order (this reflects the order in which the operations apply). More precisely, the returned object is a DelayedAperm object with one child (the DelayedSubset object), and one grandchid (the seed of x). The DelayedSubset and DelayedAperm nodes represent the net subsetting and net dimension rearrangement, respectively. Either or both of them can be a no-op.

Note that the returned object describes how the array elements of x map to their corresponding array element in seed(x).

Value

The simplified object for simplify.

TRUE or FALSE for contentIsPristine.

An ordinary list (possibly with the dimmap attribute on it) for netSubsetAndAperm. Unless as.DelayedOp is set to TRUE, in which case a DelayedAperm object is returned (see Details section above for more information).

Examples

## ---------------------------------------------------------------------
## Simplification of the tree of delayed operations
## ---------------------------------------------------------------------
m1 <- matrix(runif(150), nrow=15, ncol=10)
M1 <- DelayedArray(m1)
showtree(M1)
#> 15x10 double: DelayedMatrix object
#> └─ 15x10 double: [seed] matrix object

## By default, the tree of delayed operations carried by a DelayedArray
## object gets simplified each time a delayed operation is added to it.
## This can be disabled via a global option:
options(DelayedArray.simplify=FALSE)
M2 <- log(t(M1[5:1, c(TRUE, FALSE)] + 10))[-1, ]
showtree(M2)  # linear tree
#> 4x5 double: DelayedMatrix object
#> └─ 4x5 double: Aperm (perm=c(1,2))
#>    └─ 4x5 double: Subset
#>       └─ 5x5 double: Stack of 1 unary iso op(s)
#>          └─ 5x5 double: Aperm (perm=c(2,1))
#>             └─ 5x5 double: Stack of 1 unary iso op(s)
#>                └─ 5x5 double: Aperm (perm=c(1,2))
#>                   └─ 5x5 double: Subset
#>                      └─ 15x10 double: [seed] matrix object

## Note that as part of the simplification process, some operations
## can be reordered:
options(DelayedArray.simplify=TRUE)
M2 <- log(t(M1[5:1, c(TRUE, FALSE)] + 10))[-1, ]
showtree(M2)  # linear tree
#> 4x5 double: DelayedMatrix object
#> └─ 4x5 double: Stack of 2 unary iso op(s)
#>    └─ 4x5 double: Aperm (perm=c(2,1))
#>       └─ 5x4 double: Subset
#>          └─ 15x10 double: [seed] matrix object

options(DelayedArray.simplify=FALSE)

dimnames(M1) <- list(letters[1:15], LETTERS[1:10])
showtree(M1)  # linear tree
#> 15x10 double: DelayedMatrix object
#> └─ 15x10 double: Set dimnames
#>    └─ 15x10 double: [seed] matrix object

m2 <- matrix(1:20, nrow=10)
Y <- cbind(t(M1[ , 10:1]), DelayedArray(m2), M1[6:15, "A", drop=FALSE])
showtree(Y)   # non-linear tree
#> 10x18 double: DelayedMatrix object
#> └─ 10x18 double: Abind (along=2)
#>    ├─ 10x15 double: Aperm (perm=c(2,1))
#>    │  └─ 15x10 double: Aperm (perm=c(1,2))
#>    │     └─ 15x10 double: Subset
#>    │        └─ 15x10 double: Set dimnames
#>    │           └─ 15x10 double: [seed] matrix object
#>    ├─ 10x2 integer: [seed] matrix object
#>    └─ 10x1 double: Subset
#>       └─ 15x10 double: Set dimnames
#>          └─ 15x10 double: [seed] matrix object

Z <- t(Y[10:1, ])[1:15, ] + 0.4 * M1
showtree(Z)   # non-linear tree
#> 15x10 double: DelayedMatrix object
#> └─ 15x10 double: N-ary iso op
#>    ├─ 15x10 double: Aperm (perm=c(1,2))
#>    │  └─ 15x10 double: Subset
#>    │     └─ 18x10 double: Aperm (perm=c(2,1))
#>    │        └─ 10x18 double: Aperm (perm=c(1,2))
#>    │           └─ 10x18 double: Subset
#>    │              └─ 10x18 double: Abind (along=2)
#>    │                 ├─ 10x15 double: Aperm (perm=c(2,1))
#>    │                 │  └─ 15x10 double: Aperm (perm=c(1,2))
#>    │                 │     └─ 15x10 double: Subset
#>    │                 │        └─ 15x10 double: Set dimnames
#>    │                 │           └─ 15x10 double: [seed] matrix object
#>    │                 ├─ 10x2 integer: [seed] matrix object
#>    │                 └─ 10x1 double: Subset
#>    │                    └─ 15x10 double: Set dimnames
#>    │                       └─ 15x10 double: [seed] matrix object
#>    └─ 15x10 double: Stack of 1 unary iso op(s)
#>       └─ 15x10 double: Set dimnames
#>          └─ 15x10 double: [seed] matrix object

Z@seed@seeds
#> [[1]]
#> 15x10 double: Aperm (perm=c(1,2))
#> └─ 15x10 double: Subset
#>    └─ 18x10 double: Aperm (perm=c(2,1))
#>       └─ 10x18 double: Aperm (perm=c(1,2))
#>          └─ 10x18 double: Subset
#>             └─ 10x18 double: Abind (along=2)
#>                ├─ 10x15 double: Aperm (perm=c(2,1))
#>                │  └─ 15x10 double: Aperm (perm=c(1,2))
#>                │     └─ 15x10 double: Subset
#>                │        └─ 15x10 double: Set dimnames
#>                │           └─ 15x10 double: [seed] matrix object
#>                ├─ 10x2 integer: [seed] matrix object
#>                └─ 10x1 double: Subset
#>                   └─ 15x10 double: Set dimnames
#>                      └─ 15x10 double: [seed] matrix object
#> 
#> [[2]]
#> 15x10 double: Stack of 1 unary iso op(s)
#> └─ 15x10 double: Set dimnames
#>    └─ 15x10 double: [seed] matrix object
#> 
Z@seed@seeds[[2]]@seed                      # reaching to M1
#> 15x10 double: Set dimnames
#> └─ 15x10 double: [seed] matrix object
Z@seed@seeds[[1]]@seed@seed@seed@seed@seed  # reaching to Y
#> 10x18 double: Abind (along=2)
#> ├─ 10x15 double: Aperm (perm=c(2,1))
#> │  └─ 15x10 double: Aperm (perm=c(1,2))
#> │     └─ 15x10 double: Subset
#> │        └─ 15x10 double: Set dimnames
#> │           └─ 15x10 double: [seed] matrix object
#> ├─ 10x2 integer: [seed] matrix object
#> └─ 10x1 double: Subset
#>    └─ 15x10 double: Set dimnames
#>       └─ 15x10 double: [seed] matrix object

## ---------------------------------------------------------------------
## isPristine()
## ---------------------------------------------------------------------
m <- matrix(1:20, ncol=4, dimnames=list(letters[1:5], NULL))
M <- DelayedArray(m)

isPristine(M)                 # TRUE
#> [1] TRUE
isPristine(log(M))            # FALSE
#> [1] FALSE
isPristine(M + 0)             # FALSE
#> [1] FALSE
isPristine(t(M))              # FALSE
#> [1] FALSE
isPristine(t(t(M)))           # TRUE
#> [1] FALSE
isPristine(cbind(M, M))       # FALSE
#> [1] FALSE
isPristine(cbind(M))          # TRUE
#> [1] FALSE

dimnames(M) <- NULL
isPristine(M)                 # FALSE
#> [1] FALSE
isPristine(M, ignore.dimnames=TRUE)  # TRUE
#> [1] TRUE
isPristine(t(t(M)), ignore.dimnames=TRUE)  # TRUE
#> [1] FALSE
isPristine(cbind(M, M), ignore.dimnames=TRUE)  # FALSE
#> [1] FALSE

## ---------------------------------------------------------------------
## contentIsPristine()
## ---------------------------------------------------------------------
a <- array(1:40, c(4, 5, 2))
A <- DelayedArray(a)

stopifnot(contentIsPristine(A))
stopifnot(contentIsPristine(A[1, , ]))
stopifnot(contentIsPristine(t(A[1, , ])))
stopifnot(contentIsPristine(cbind(A[1, , ], A[2, , ])))
dimnames(A) <- list(LETTERS[1:4], letters[1:5], NULL)
stopifnot(contentIsPristine(A))

contentIsPristine(log(A))     # FALSE
#> [1] FALSE
contentIsPristine(A - 11:14)  # FALSE
#> [1] FALSE
contentIsPristine(A * A)      # FALSE
#> [1] FALSE

## ---------------------------------------------------------------------
## netSubsetAndAperm()
## ---------------------------------------------------------------------
a <- array(1:40, c(4, 5, 2))
M <- aperm(DelayedArray(a)[ , -1, ] / 100)[ , , 3] + 99:98
M
#> <2 x 4> DelayedMatrix object of type "double":
#>       [,1]  [,2]  [,3]  [,4]
#> [1,] 99.07 99.11 99.15 99.19
#> [2,] 98.27 98.31 98.35 98.39
showtree(M)
#> 2x4 double: DelayedMatrix object
#> └─ 2x4 double: Unary iso op with args
#>    └─ 2x4 double: Aperm (perm=c(1,2))
#>       └─ 2x4x1 double: Subset
#>          └─ 2x4x4 double: Aperm (perm=c(3,2,1))
#>             └─ 4x4x2 double: Stack of 1 unary iso op(s)
#>                └─ 4x4x2 integer: Aperm (perm=c(1,2,3))
#>                   └─ 4x4x2 integer: Subset
#>                      └─ 4x5x2 integer: [seed] array object

netSubsetAndAperm(M)  # 1st dimension was dropped, 2nd and 3rd
#> [[1]]
#> [1] 3
#> 
#> [[2]]
#> [1] 2 3 4 5
#> 
#> [[3]]
#> NULL
#> 
#> attr(,"dimmap")
#> [1] 3 2
                      # dimension were permuted (transposition)

op2 <- netSubsetAndAperm(M, as.DelayedOp=TRUE)
op2                   # 2 nested delayed operations
#> 2x4 integer: Aperm (perm=c(3,2))
#> └─ 1x4x2 integer: Subset
#>    └─ 4x5x2 integer: [seed] array object
op1 <- op2@seed
class(op1)            # DelayedSubset
#> [1] "DelayedSubset"
#> attr(,"package")
#> [1] "DelayedArray"
class(op2)            # DelayedAperm
#> [1] "DelayedAperm"
#> attr(,"package")
#> [1] "DelayedArray"
op1@index
#> [[1]]
#> [1] 3
#> 
#> [[2]]
#> [1] 2 3 4 5
#> 
#> [[3]]
#> NULL
#> 
op2@perm
#> [1] 3 2

DelayedArray(op2)     # same as M from a [, drop(), and aperm() point of
#> <2 x 4> DelayedMatrix object of type "integer":
#>      [,1] [,2] [,3] [,4]
#> [1,]    7   11   15   19
#> [2,]   27   31   35   39
                      # view but the individual array elements are now
                      # reset to their original values i.e. to the values
                      # they have in the seed
stopifnot(contentIsPristine(DelayedArray(op2)))

## A simple function that returns TRUE if a DelayedArray object carries
## no "net subsetting" and no "net dimension rearrangement":
is_aligned_with_seed <- function(x)
{
    if (nseed(x) != 1L)
        return(FALSE)
    op2 <- netSubsetAndAperm(x, as.DelayedOp=TRUE)
    op1 <- op2@seed
    is_noop(op1) && is_noop(op2)
}

M <- DelayedArray(a[ , , 1])
is_aligned_with_seed(log(M + 11:14) > 3)            # TRUE
#> [1] TRUE
is_aligned_with_seed(M[4:1, ])                      # FALSE
#> [1] FALSE
is_aligned_with_seed(M[4:1, ][4:1, ])               # TRUE
#> [1] TRUE
is_aligned_with_seed(t(M))                          # FALSE
#> [1] FALSE
is_aligned_with_seed(t(t(M)))                       # TRUE
#> [1] TRUE
is_aligned_with_seed(t(0.5 * t(M[4:1, ])[ , 4:1]))  # TRUE
#> [1] TRUE

options(DelayedArray.simplify=TRUE)

Usage

Arguments

Details

Value

See also

Examples