expandInto: Expand array
In tdeenes/eegR: Analyze EEG Signals

expandInto expands an array to a larger array (either to an array with more dimensions or an array with longer dimensions or both).

1	expandInto(dat, new_dat, expand_levels = NULL, safe_mode = TRUE, fill = TRUE)

`dat`	an array
`new_dat`	an array to expand 'dat' into
`expand_levels`	a list of vectors which define the expanding scheme for each dimension of 'dat' or a named list of vectors where the names refer to selected dimensions in 'dat' (in this case 'dat' must have named dimnames). The length of each vector in 'expand_levels' must match the corresponding dimension size in 'new_dat'. The vectors must contain either numeric or character indices of the levels of the given dimension in 'dat'.
`safe_mode`	a logical value whether the expansion of non-singleton dimensions is not allowed if the corresponding vectors in 'expand_levels' are not provided (default: TRUE). If 'safe_mode' is TRUE, and both 'dat' and 'new_dat' has dimension names, non-expanded dimensions are checked if the order of levels should be adjusted for the given dimension. See Examples.
`fill`	a logical value if the 'new_dat' should be filled with the corresponding values in 'dat' (TRUE, the default). In this case the values of 'dat' are coerced to match the type of 'new_dat' and the returned array inherits all attributes of 'new_dat'. Otherwise, only the dimensions and dimension names are preserved.

# load example data
data(erps)

# -----
# solve the following task: find all data points for which the amplitudes
# in the "Fz" channel are negative, and return TRUE for all corresponding
# data points in the other channels as well
# -----

# subset the data and return TRUE if the values are negative
x_Fz <- subsetArray(erps, chan = "Fz") < 0
str(x_Fz)

# expand this array into the original array
result <- expandInto(x_Fz, erps)
str(result)

# check on a random channel that the results are really fine
x_Cz <- subsetArray(result, chan = "Cz")
# -->
# all TRUEs in x_Fz are also TRUE in x_Cz, and vica versa
( tab <- table(x_Fz, x_Cz) )
stopifnot(identical(sum(diag(tab)), length(x_Fz)))

# -----
# the function is clever enough to reorder the levels for those
# dimensions as well, which should not be expanded, but the order
# of levels is different in 'new_dat'
# -----
# reorder the 'stimclass' dimension in the original ERP array
erps2 <- subsetArray(erps, stimclass = c("C", "B", "A"))

# expand x_Fz again
result2 <- expandInto(x_Fz, erps2)

# turn 'safe_mode' off
result2_notsafe <- expandInto(x_Fz, erps2, safe_mode = FALSE)

# check the results -> result2 is fine
x_Cz_2 <- subsetArray(result2,
                      chan = "Cz",
                      stimclass = c("A", "B", "C"))
( tab <- table(x_Fz, x_Cz_2) )
stopifnot(identical(sum(diag(tab)), length(x_Fz)))

# check the results -> result2_notsafe is wrong
x_Cz_2w <- subsetArray(result2_notsafe,
                       chan = "Cz",
                       stimclass = c("A", "B", "C"))
( tab <- table(x_Fz, x_Cz_2w) )
stopifnot(!identical(sum(diag(tab)), length(x_Fz)))

# -----
# the safest way is to provide 'expand_levels' explicitly for all
# dimensions where the order or number of levels do not match;
# using this argument it is also possible to copy the values of a given
# level to an other one
# -----
# suppose we want stimclass C to be copied from stimclass B while expanding
# to all channels (on the original ERP array)
result <- expandInto(x_Fz, erps,
                     expand_levels = list(stimclass = c("A", "B", "B")))

# check the results
x_Cz_B <- subsetArray(result,
                      chan = "Cz",
                      stimclass = "B")
x_Cz_C <- subsetArray(result,
                      chan = "Cz",
                      stimclass = "C")
# --> they are identical:
stopifnot(identical(x_Cz_B, x_Cz_C))
# --> compared to the results on Fz, stimclass B remained the same:
x_Fz_B <- subsetArray(x_Fz, stimclass = "B")
( tab <- table(x_Fz_B, x_Cz_B) )
stopifnot(identical(sum(diag(tab)), length(x_Fz_B)))

# -----
# it is possible that we want to expand an array into a larger array,
# but the types do not match; consider the 'fill' argument depending on
# your needs
# -----
# create a logical matrix
( from_logical <- matrix(c(TRUE, FALSE), 2, 1,
                         dimnames = list(observation = c("a", "b"),
                                         measure = "width")) )

# it should be expanded to a larger, integer matrix with a special class
( to_integer <- matrix(1:4, 2, 2,
                       dimnames = list(observation = c("a", "b"),
                                       measure = c("height", "width"))) )
class(to_integer) <- "mySpecialClass"

# perform to expansions
( res_int <- expandInto(from_logical, to_integer) )
( res_log <- expandInto(from_logical, to_integer, fill = FALSE) )

# res_int is integer, and preserves the class, res_log not
stopifnot(is.integer(res_int))
stopifnot(inherits(res_int, "mySpecialClass"))
stopifnot(is.logical(res_log))
stopifnot(!inherits(res_log, "mySpecialClass"))

# however, the dimnames are preserved
stopifnot(identical(
    dimnames(res_log),
    dimnames(to_integer)
))