apermArray: Array transposition

Description Usage Arguments Value Note Examples

View source: R/array_transform.R

Description

Transpose an array by permuting its dimensions and optionally resizing it. This function is a simple wrapper around aperm.default with two minimal enhancements: 1) It checks if the permutation order is the same as the original order of the dimensions. In this case it simply returns a copy of the input array without any unnecessary time-consuming manipulation. See also NOTE. 2) It allows for partial definition of the permutation order. See argument 'first'.

Usage

1
2
3
4
5
6
7
apermArray(
  a,
  perm = NULL,
  resize = TRUE,
  first = perm,
  keep_attributes. = FALSE
)

Arguments

a

the array to be transposed

perm

the subscript permutation vector, usually a permutation of the integers 1:n, where n is the number of dimensions of a. When a has named dimnames, it can be a character vector of length n giving a permutation of those names. The default (used whenever perm has zero length) is to reverse the order of the dimensions.

resize

a flag indicating whether the vector should be resized as well as having its elements reordered (default: TRUE)

first

dimension(s) which should come first; either numeric index(es), or if the array has named dimensions, 'first' can be a character vector. Ignored if 'perm' is not NULL.

keep_attributes.

see NOTE (default: FALSE)

Value

A transposed version of array a, with subscripts permuted as indicated by the array perm. If resize is TRUE, the array is reshaped as well as having its elements permuted, the dimnames are also permuted; if resize = FALSE then the returned object has the same dimensions as a, and the dimnames are dropped. In each case other attributes are dropped unless keep_attributes. = TRUE. See NOTE!

Note

The documentation of aperm wrongly states that "other attributes are copied from a". Instead, aperm drops all attributes other than dim and dimnames. To make apermArray a replacement function of aperm, this unexpected behaviour is also reproduced unless explicitly required by the user not to do so.

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
# example data
data(erps)
str(erps) # five dimensions

# a use case where argument 'first' is helpful: suppose we need 'time'
# as the first dimension
time_first <- apermArray(erps, first = "time")

# compare to the more cumbersome perm = setdiff(...) solution
time_first_aperm <- aperm(erps,
                          perm = c("time",
                                   setdiff(names(dimnames(erps)), "time")))
stopifnot(identical(time_first, time_first_aperm))

# create permutation order by simply replicating the original order;
# note that in this special case it is more efficient to request
# keep_attributes. = TRUE
perm <- seq_along(dim(erps))

# timing
if (require(microbenchmark)) {
    microbenchmark(
        aperm(erps, perm),
        apermArray(erps, perm),
        apermArray(erps, names(dimnames(erps))),
        apermArray(erps, perm, keep_attributes. = TRUE),
        times = 200L
    )
}

# check if identical
aperm_orig <- aperm(erps, perm)
stopifnot(identical(aperm_orig,
                    apermArray(erps, perm)))
stopifnot(identical(aperm_orig,
                    apermArray(erps, names(dimnames(erps)))))
stopifnot(all.equal(aperm_orig,
                    apermArray(erps, perm, keep_attributes. = TRUE),
                    check.attributes = FALSE))
stopifnot(identical(erps,
                    apermArray(erps, perm, keep_attributes. = TRUE)))

# if resize = FALSE, dimension names are dropped
noresize <- apermArray(erps, perm, resize = FALSE)
stopifnot(is.null(dimnames(noresize)))
stopifnot(identical(unname(aperm_orig),
                    noresize))

tdeenes/eegR documentation built on April 19, 2021, 4:17 p.m.