plotButterfly: Create butterfly plot with extras: highlighting and peak...
In tdeenes/eegR: Analyze EEG Signals

Description Usage Arguments Value Examples

plotButterfly creates a multi-channel (a.k.a butterfly) plot. Additionally, significant time windows can be highlighted, and peak topographies can be displayed above the ERP curves.

plotButterfly(
  dat,
  sig = NULL,
  topo_time = NULL,
  chan_pos = NULL,
  subset = list(),
  pcrit = 0.05,
  aspect_ratio = 0.5,
  scalp_ratio = 0.5,
  ampl_range = NULL,
  caption = TRUE,
  ...
)

`dat`	the array of ERP curves which must have at least 'time' and/or 'chan' dimensions
`sig`	[optional] a corresponding array to `dat` which is used to highlight significant time windows. It must have at least 'time' and measure' dimensions. The 'measure' dimension must have 'p' and 'p_corr' levels indicating the uncorrected ('p') and corrected ('p_corr') p-values.
`topo_time`	[optional] an object which describes the time points at which the scalp topographies should be plotted. Can be a simple atomic vector or a data.frame if the time points are not identical across the faceting dimension(s).
`chan_pos`	a data.frame of channel positions. Obligatory if `topo_time` is not `NULL`.
`subset`	a named list to subset the input arrays; see `subsetArray`
`pcrit`	the level of alpha to highlight significant effects
`aspect_ratio`	the ratio of `y` and `x` axes (default: 0.5) on the figure. If NULL, it is set automatically. If 'topo_time' is provided, user-defined 'aspect_ratio' might be adjusted to avoid overlapping scalp maps.
`scalp_ratio`	the ratio of the diameter of the scalp and the vertical range of the ERP curves on the figure
`ampl_range`	the range of amplitudes to plot. If `NULL` (default), it is computed from the data.
`caption`	logical flag indicating if caption should be also returned (default: TRUE)
`...`	additional arguments passed to `topoCoord`

plotButterfly returns a ggplot object.

# load example data
data(erps)

# extract channel positions
chan_pos <- attr(erps, "chan")

# collapse pairtypes and participants
tempdat <- avgDims(erps, c("pairtype", "id"))

# plot butterfly with topo-maps at specified time points
plotButterfly(tempdat, topo_time = seq(24, 476, by = 50),
              chan_pos = chan_pos)

# plot butterfly with topo-maps at peaks which are selected 
# automatically; let's look for local maxima on the GFP curves between
# 0 and 480 ms
# 1) add GFP to the dataset
tempdat2 <- compGfp(tempdat, keep_channels = TRUE)

# 2) provide the peak definition
peak_def <- isLocalMaximum(
    subset. = list(time = isBetween(0, 480), chan = "GFP"),
    options. = list(along_dim = "time", n = 15))

# 3) find the peaks
peak_data <- selectValues(tempdat2, peak_def)

# 4) create plot
plotButterfly(tempdat2, topo_time = peak_data, chan_pos = chan_pos)

# highlight time windows where the effect of the 'stimclass' factor is
# statistically significant according to TANOVA
# 1) run TANOVA
result_tanova <- tanova(
    avgDims(erps, "pairtype"),
    list(within = "stimclass", w_id = "id"),
    parallel = .(ncores = 2),
    perm = .(n = 499))
    
# 2) extract p-values and bind them to a single array
pvalues <- extract(result_tanova, c("p", "p_corr"))
pvalues <- bindArrays(pvalues, along_name = "measure")

# 3) plot
plotButterfly(tempdat2, sig = pvalues, topo_time = peak_data, 
              chan_pos = chan_pos)