arrayTtest: Point-to-point t-tests (potentially with TFCE correction) on...
In tdeenes/eegR: Analyze EEG Signals

Description Usage Arguments Details Value Examples

arrayTtest performs point-to-point t-tests on arrays. Permutation-based p-values and Threshold-free Cluster Enhancement (TFCE) correction can be requested.

arrayTtest(
  .arraydat,
  .arraydat2 = NULL,
  paired = FALSE,
  groups = NULL,
  mu = 0,
  var_equal = FALSE,
  id_dim = "id",
  verbose = TRUE,
  nperm = 0L,
  tfce = NULL,
  parallel = NULL,
  seed = NULL
)

`.arraydat`	a numeric array with named dimnames containing EEG (or other) data. Missing values are not allowed. Must have at least three dimensions with names "chan", "time", and "id" (see also id_dim)
`.arraydat2`	a numeric array with named dimnames containing EEG (or other) data (default: NULL). If provided, see the parameter `paired` for running paired or independent-samples t-tests
`paired`	logical scalar, only used if .arraydat2 is provided. If paired is FALSE (default), the function computes independent samples t-tests, otherwise paired samples t-tests are performed
`groups`	provides an alternative (and more efficient) way to perform independent samples t-tests; a character, factor, or integer vector which defines group membership. Groups is ignored if .arraydat2 is not missing. NA values code subjects to drop.
`mu`	a numeric scalar indicating the true value of the mean (or difference between means, if two-sample tests are performed)
`var_equal`	a logical scalar whether the variances are equal (only relevant for independent-samples t-tests). If TRUE, the pooled variance is used to estimate the variance. If FALSE (default), the Welch (or Satterthwaite) approximation to the degrees of freedom is used.
`id_dim`	name of the dimension which identifies the subjects (default: "id")
`verbose`	logical value indicating if p-values should be computed for the traditional t-test results (default: TRUE)
`nperm`	integer value giving the number of permutations (default: 0L). If `nperm < 2L`, no permutation is performed.
`tfce`	either 1) NULL (the default) or FALSE (the same as NULL), both of which mean no TFCE correction, or 2) TRUE, which means TFCE correction with default parameters, or 3) an object as returned by `tfceParams` with custom TFCE parameters (see Examples and also `tfceParams`). Custom parameters can be also provided by `tfce = .(key = value)` to save typing (this works by calling `tfceParams` with the given parameters).
`parallel`	either 1) FALSE (the default), which results in 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`), or 4) NULL, which means that the registered backend (if there is any) shall be used. Custom parameters can be also provided by `parallel = .(key = value)` to save typing (this works by calling `parallelParams` with the given parameters).
`seed`	an integer value which specifies a seed (default: NULL), or a list of arguments passed to `set.seed`

The function assumes that the input array contains at least three named dimensions: chan (corresponding to the channels [electrodes]) and time (corresponding to time points), and id_dim (corresponding to subjects). All other dimensions are treated in a similar way as chan and time, that is separate t-tests are computed for each level of those dimensions.

A list object with t-values, TFCE-corrected t-values and permutation-based p-values (if requested)

# example dataset
data(erps)
dat_id <- attr(erps, "id") # to get group memberships
chan_pos <- attr(erps, "chan") # needed for TFCE correction

# compare controls and dyslexics with traditional indep. samples t-test;
# comparison is performed for each time sample, channel and experimental 
# condition separately (altogether 81972 tests - note the speed)
system.time(
    result_eegr <- arrayTtest(erps, groups = dat_id$group)
)

# the built-in R function (stats::t.test) provides the same result, but 
# running it on the full dataset would take much more time; 
# here we take a subsample of the data
sub <- list(chan = "F4", time = "200", stimclass = "B", pairtype = "ident")
result_ttest <- t.test(subsetArray(erps, sub) ~ dat_id$group)

# to check that they are equivalent, we have to remove the attributes
eegr_t <- as.vector(subsetArray(extract(result_eegr, "stat"), sub))
eegr_p <- as.vector(subsetArray(extract(result_eegr, "p"), sub))
stopifnot(
    all.equal(as.vector(result_ttest$statistic), eegr_t),
    all.equal(as.vector(result_ttest$p.value), eegr_p)
)

# Now let's use TFCE correction; to do that, one needs a channel neigbourhood
# matrix and has to use randomization. We will simplify a bit the data to 
# decrease the computational burden.
# 1) get channel neighbourhoods (type ?chanNb)
ChN <- chanNb(chan_pos, alpha = 0.7)

# 2) analyze only stimclass "B" and pairtype "ident"
tempdat <- subsetArray(erps, list(stimclass = "B", pairtype = "ident"))

# 3) run computations (now with only 499 permutations, and using 2 CPU-cores)
result_tfce <- arrayTtest(tempdat, groups = dat_id$group, 
                          nperm = 499L, 
                          parallel = .(ncores = 2L),
                          tfce = .(ChN = ChN))

# 4) compare the traditional and TFCE-corrected results
modelplot(result_tfce, type = "unc")
modelplot(result_tfce)

# 5) plot p-values after -log transform for better discriminability
# note how the sporadic effects disappear after TFCE correction
p_trad <- extract(result_tfce, "p")
p_tfce <- extract(result_tfce, "p_corr")
p_all <- bindArrays(trad = p_trad, tfce = p_tfce, along_name = "method")
p_plot <- imageValues(-log(p_all))  # returns a ggplot object
p_plot

# Finally, here is an example for two versions of a paired-samples t-test
# 0) Compare level A nd level B of the "stimclass" dimension
datA <- subsetArray(erps, list(stimclass = "A"))
datB <- subsetArray(erps, list(stimclass = "B"))

# 1) Provide two arrays, and set 'paired' to TRUE
result1 <- arrayTtest(datA, datB, paired = TRUE)

# 2) Compute the difference of the two arrays, and run a one-sample t-test
result2 <- arrayTtest(datA - datB)

# 3) Check the results
stopifnot(identical(as.vector(extract(result1, "stat")), 
                    as.vector(extract(result2, "stat"))))

# 4) Compare to the results of the built-in t.test (stats::t.test);
# here we take a subsample of the data
sub <- list(chan = "F4", time = "200", pairtype = "ident")
result_ttest <- t.test(subsetArray(datA, sub), subsetArray(datB, sub),
                       paired = TRUE)

# to check that they are equivalent, we have to remove the attributes
eegr_t <- as.vector(subsetArray(extract(result1, "stat"), sub))
eegr_p <- as.vector(subsetArray(extract(result1, "p"), sub))
stopifnot(
    all.equal(as.vector(result_ttest$statistic), eegr_t),
    all.equal(as.vector(result_ttest$p.value), eegr_p)
)