compareLevels: Compare dimension levels

In tdeenes/eegR: Analyze EEG Signals

Description

compareLevels compares dimension levels based on arbitrary contrast schemes. This is usually not only more convenient but also faster than compare various subsets of the data 'by hand'.

Usage

compareLevels(dat, which_dim = 1L, contr = NULL, ...)

Arguments

dat	an atomic vector, matrix or array
which_dim	numeric indices of dimensions or character vector of dimension identifiers (names of dimnames) whose levels should be contrasted (default: 1L)
contr	either 1) NULL (the default), which means that all levels within each dimension are contrasted in a pairwise fashion, or 2) a matrix or a list of matrices which directly define the contrast schemes (they are recycled if necessary to match the length of which_dim), or 3) a function or a list of functions whose first argument is the number of levels, and they create a contrast matrix accordingly
...	further arguments passed to contr if it is a function

Value

The function returns the same type of object as its input object (a vector, matrix or array). The names (in case of a vector) or the dimension names of the returned object reflect the contrast which resulted the given level (see Examples).

Examples

# load example data
data(erps)

# pairwise comparisons between identical, substituted and transposed pairs
res <- compareLevels(erps, "pairtype")
str(res)

# the same with a contrast matrix
cmat <- matrix(c(-1,-1, 0,
                  1, 0,-1,
                  0, 1, 1), 3, 3, byrow = TRUE)
res_cmat <- compareLevels(erps, "pairtype", cmat)
stopifnot(identical(res, res_cmat))

# the same with a contrast function, which also accepts custom rownames
cfn <- function(n, rowname_base = NULL) {
    contr <- matrix(0L, n, choose(n, 2L))
    combs <- combn(n, 2)
    for (i in 1:ncol(combs)) {
        contr[combs[1L, i], i] <- -1L
        contr[combs[2L, i], i] <- 1L
    }
    if (!is.null(rowname_base)) {
        rownames(contr) <- paste0(rowname_base[1], seq_len(n))
    }
    contr
}
res_cfn <- compareLevels(erps, "pairtype", cfn)
stopifnot(identical(res, res_cfn))

# the same "by hand"
erps_splitted <- splitArray(erps, "pairtype", drop = TRUE)
res_h <- bindArrays(
    `subst-ident` = erps_splitted$subst - erps_splitted$ident,
    `transp-ident` = erps_splitted$transp - erps_splitted$ident,
    `transp-subst` = erps_splitted$transp - erps_splitted$subst,
    along_name = "pairtype"
)
res_h <- aperm(res_h, names(dimnames(res)))
stopifnot(identical(res, res_h))

# a complex example with two manipulated dimensions (stimclass and pairtype);
# compare only level A and level B for stimclass, and all levels for
# pairtype; use custom names ("level1", "level2", etc.) instead of the
# original dimension names
res_complex <- compareLevels(
    erps, c("stimclass", "pairtype"),
    contr = list(as.matrix(c(-1, 1, 0)), cfn),
    rowname_base = "level")
str(res_complex)

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