fnDims: Call a user-specified function on whatever dimension(s) of an...
In tdeenes/eegR: Analyze EEG Signals

Description Usage Arguments Details Value See Also Examples

fnDims calls a user-specified function on whatever dimension(s) of a matrix or array. Function can be a vectorized function in which case fnDims is very fast.

fnDims(
  dat,
  target_dim,
  target_fn,
  arg_list = NULL,
  newdims = list(),
  vectorized = FALSE,
  columnwise = TRUE,
  keep_dimorder = FALSE,
  parallel = NULL,
  arg_check = TRUE
)

`dat`	matrix or array on which function should be called
`target_dim`	The dimension(s) of dat on which the function should be performed. Can be an integer or numeric vector of dimension index(es) or a character vector if dat has named dimension names.
`target_fn`	function definition
`arg_list`	a list of arguments in addition to dat for target_fn (default: NULL)
`newdims`	a named list of character vector(s) defining the dimension names of the output of target_fn (see Details)
`vectorized`	logical value; should be set to TRUE if target_fn expects two-dimensional input (e.g. colSums)
`columnwise`	logical value; if vectorized is TRUE, columnwise indicates if target_fn operates column-wise (TRUE, default) or row-wise (FALSE)
`keep_dimorder`	logical value; if TRUE, and the returned matrix or array has the same dimension identifiers as dat, the order of dimensions in the returned object will be the same as in dat (default = FALSE)
`parallel`	either 1) NULL (the default) or FALSE (the same as NULL), both of which mean single-core computation, or 2) TRUE, which means parallelization with default parameters, or 3) an object as returned by `parallelParams` with custom parameters (see Examples and also `parallelParams`). Custom parameters can be also provided by `parallel = .(key = value)` to save typing (this works by calling `parallelParams` with the given parameters).
`arg_check`	logical value if arguments should be checked (default: TRUE)

This function works by transforming dat to a matrix with a row dimension corresponding to target_dim and calling target_fn on each column of the matrix repeatedly, or if vectorized is TRUE, by feeding the transformed matrix directly to target_fn. After calling target_fn, the results are back-transformed to the original array format. If target_fn produces one value per input vector, target_dim is dropped from the resulting array. If target_fn produces an equal-length vector as the input, and newdims parameter is not provided, fnDims assumes that dimensions correspond to the original input. If target_fn outputs a list, no back-transformation is done.

see Details

avgDims migth be a better choice if target_fn is one of mean, colMeans, or rowMeans.

# example dataset
data(erps)

# find the range of amplitudes in each channel X time slice of the array
# (that is, separately for each condition and subject)
newdimn <- list(stat = c("min", "max"))
system.time(max_simple <- fnDims(erps, c("chan", "time"), range,
                                 newdims = newdimn))

# the resulting array has appropriate shape
str(max_simple)

# apply is less handy in such cases
system.time({
    max_apply <- apply(erps,
                       setdiff(names(dimnames(erps)), c("chan", "time")),
                       range)
    dimnames(max_apply)[1] <- newdimn
    names(dimnames(max_apply))[1] <- names(newdimn)
})

# the same using parallelization (only faster if the computation time is much
# higher than the overhead of starting the clusters, which is not the case here)
system.time(max_parallel <- fnDims(erps, c("chan", "time"), range,
                                   parallel = .(ncores = 2L),
                                   newdims = newdimn))

# usually it is much faster to use a vectorized function;
# note that matrixStats::colRanges returns an Nx2 matrix, but we need 2xN
fastRange <- function(x) t(matrixStats::colRanges(x))
system.time(max_vectorized <- fnDims(erps, c("chan", "time"),
                                     fastRange,
                                     vectorized = TRUE,
                                     newdims = newdimn))

# the results are the same
stopifnot(all.equal(max_simple, max_apply, check.attributes = FALSE))
stopifnot(all.equal(max_simple, max_parallel))
stopifnot(all.equal(max_simple, max_vectorized))