simplify: Simplify a tree of delayed operations
In DelayedArray: A unified framework for working transparently with on-disk and in-memory array-like datasets
Description
Usage
Arguments
Details
Value
See Also
Examples
Description
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
1
2
3
4
5
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 DelayedDimnames).
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).
See Also
-
showtree to visualize and access the leaves of
a tree of delayed operations carried by a DelayedArray
object.
-
DelayedOp objects.
-
DelayedArray objects.
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
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
## ---------------------------------------------------------------------
## Simplification of the tree of delayed operations
## ---------------------------------------------------------------------
m1 <- matrix(runif(150), nrow=15, ncol=10)
M1 <- DelayedArray(m1)
showtree(M1)
## 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
## 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
options(DelayedArray.simplify=FALSE)
dimnames(M1) <- list(letters[1:15], LETTERS[1:10])
showtree(M1) # linear tree
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
Z <- t(Y[10:1, ])[1:15, ] + 0.4 * M1
showtree(Z) # non-linear tree
Z@seed@seeds
Z@seed@seeds[[2]]@seed # reaching to M1
Z@seed@seeds[[1]]@seed@seed@seed@seed@seed # reaching to Y
## ---------------------------------------------------------------------
## isPristine()
## ---------------------------------------------------------------------
m <- matrix(1:20, ncol=4, dimnames=list(letters[1:5], NULL))
M <- DelayedArray(m)
isPristine(M) # TRUE
isPristine(log(M)) # FALSE
isPristine(M + 0) # FALSE
isPristine(t(M)) # FALSE
isPristine(t(t(M))) # TRUE
isPristine(cbind(M, M)) # FALSE
isPristine(cbind(M)) # TRUE
dimnames(M) <- NULL
isPristine(M) # FALSE
isPristine(M, ignore.dimnames=TRUE) # TRUE
isPristine(t(t(M)), ignore.dimnames=TRUE) # TRUE
isPristine(cbind(M, M), ignore.dimnames=TRUE) # 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
contentIsPristine(A - 11:14) # FALSE
contentIsPristine(A * A) # FALSE
## ---------------------------------------------------------------------
## netSubsetAndAperm()
## ---------------------------------------------------------------------
a <- array(1:40, c(4, 5, 2))
M <- aperm(DelayedArray(a)[ , -1, ] / 100)[ , , 3] + 99:98
M
showtree(M)
netSubsetAndAperm(M) # 1st dimension was dropped, 2nd and 3rd
# dimension were permuted (transposition)
op2 <- netSubsetAndAperm(M, as.DelayedOp=TRUE)
op2 # 2 nested delayed operations
op1 <- op2@seed
class(op1) # DelayedSubset
class(op2) # DelayedAperm
op1@index
op2@perm
DelayedArray(op2) # same as M from a [, drop(), and aperm() point of
# 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
is_aligned_with_seed(M[4:1, ]) # FALSE
is_aligned_with_seed(M[4:1, ][4:1, ]) # TRUE
is_aligned_with_seed(t(M)) # FALSE
is_aligned_with_seed(t(t(M))) # TRUE
is_aligned_with_seed(t(0.5 * t(M[4:1, ])[ , 4:1])) # TRUE
options(DelayedArray.simplify=TRUE)
DelayedArray documentation built on March 25, 2021, 6:01 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Description Usage Arguments Details Value See Also Examples
Description
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
1 2 3 4 5 | 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 |
incremental |
For internal use. |
ignore.dimnames |
|
as.DelayedOp |
|
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.DelayedOpisFALSE(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 aNULL. ANULLindicates a missing subscript. In addition, ifxcarries 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 adimmapattribute added to the list. This attribute is an integer vector parallel todim(x)that reports how the dimensions ofxare mapped to the dimensions of its seed.If
as.DelayedOpisTRUE, the returned object is a linear tree with 2 DelayedOp nodes and a leaf node. The leaf node is the seed ofx. 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 ofx). 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).
See Also
-
showtreeto visualize and access the leaves of a tree of delayed operations carried by a DelayedArray object. -
DelayedOp objects.
-
DelayedArray objects.
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 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 | ## ---------------------------------------------------------------------
## Simplification of the tree of delayed operations
## ---------------------------------------------------------------------
m1 <- matrix(runif(150), nrow=15, ncol=10)
M1 <- DelayedArray(m1)
showtree(M1)
## 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
## 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
options(DelayedArray.simplify=FALSE)
dimnames(M1) <- list(letters[1:15], LETTERS[1:10])
showtree(M1) # linear tree
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
Z <- t(Y[10:1, ])[1:15, ] + 0.4 * M1
showtree(Z) # non-linear tree
Z@seed@seeds
Z@seed@seeds[[2]]@seed # reaching to M1
Z@seed@seeds[[1]]@seed@seed@seed@seed@seed # reaching to Y
## ---------------------------------------------------------------------
## isPristine()
## ---------------------------------------------------------------------
m <- matrix(1:20, ncol=4, dimnames=list(letters[1:5], NULL))
M <- DelayedArray(m)
isPristine(M) # TRUE
isPristine(log(M)) # FALSE
isPristine(M + 0) # FALSE
isPristine(t(M)) # FALSE
isPristine(t(t(M))) # TRUE
isPristine(cbind(M, M)) # FALSE
isPristine(cbind(M)) # TRUE
dimnames(M) <- NULL
isPristine(M) # FALSE
isPristine(M, ignore.dimnames=TRUE) # TRUE
isPristine(t(t(M)), ignore.dimnames=TRUE) # TRUE
isPristine(cbind(M, M), ignore.dimnames=TRUE) # 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
contentIsPristine(A - 11:14) # FALSE
contentIsPristine(A * A) # FALSE
## ---------------------------------------------------------------------
## netSubsetAndAperm()
## ---------------------------------------------------------------------
a <- array(1:40, c(4, 5, 2))
M <- aperm(DelayedArray(a)[ , -1, ] / 100)[ , , 3] + 99:98
M
showtree(M)
netSubsetAndAperm(M) # 1st dimension was dropped, 2nd and 3rd
# dimension were permuted (transposition)
op2 <- netSubsetAndAperm(M, as.DelayedOp=TRUE)
op2 # 2 nested delayed operations
op1 <- op2@seed
class(op1) # DelayedSubset
class(op2) # DelayedAperm
op1@index
op2@perm
DelayedArray(op2) # same as M from a [, drop(), and aperm() point of
# 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
is_aligned_with_seed(M[4:1, ]) # FALSE
is_aligned_with_seed(M[4:1, ][4:1, ]) # TRUE
is_aligned_with_seed(t(M)) # FALSE
is_aligned_with_seed(t(t(M))) # TRUE
is_aligned_with_seed(t(0.5 * t(M[4:1, ])[ , 4:1])) # TRUE
options(DelayedArray.simplify=TRUE)
|
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.