Animate EEG average topographic map with confidence bounds

An animation of the average signal time course as a topographic map along with the lower and upper bounds of the confidence interval. In the output, three facets are plotted per frame: CI lower, average, CI upper.

Usage

animate_topo_mean(
  data,
  t_lim,
  FS = 250,
  t0 = 1,
  mesh,
  coords = NULL,
  template = NULL,
  col_range = NULL,
  col_scale = NULL,
  show_legend = TRUE,
  contour = FALSE,
  output_path = NULL,
  ...
)

Arguments

data: A data frame, tibble or a database table with input data to plot. It should be an output from compute_mean function or an object with the same structure. Required columns: sensor - sensor labels, time - numbers of time points, average - average signal values, ci_low and ci_up - lower and upper CI bounds.
t_lim: Limits of time points (i.e., the length of the timeline displayed below the animation).
FS: The sampling frequency. Default value is 250 Hz.
t0: Index of the zero time point, i.e. point, where 0 ms should be marked (most often time of the stimulus or time of the response).
mesh: A "mesh" object (or a named list with the same structure) containing at least a D2 element with x and y coordinates of a point mesh used for computing the IM model, and a template element specifying the sensor montage. If not defined, the point mesh with default settings from point_mesh function is used.
coords: Sensor coordinates as a tibble or data frame with named x, y and sensor columns. The sensor labels must match the labels in sensor column in data. If not defined, the template specified in mesh$template (or the default "HCGSN256") is used.
template: The kind of sensor template montage used. Available options are "HCGSN256", "biosemi128", "biosemi256", and "system1005". Default setting is "HCGSN256".
col_range: A vector with minimum and maximum value of the amplitude used in the colour palette for plotting. If not defined, the range of the input signal is used.
col_scale: Optionally, a colour scale to be utilised for plotting. If not defined, it is computed from col_range.
show_legend: Logical. Indicates, whether legend should be displayed below the graph. Default value is TRUE.
contour: Logical. Indicates, whether contours should be plotted in the graph. Default value is FALSE.
output_path: File path where the animation will be saved using gifski renderer (optional). If not defined, the animation is plotted in the RStudio Viewer.
...: Additional parameters for animation according to gganimate::animate.

Value

If output_path is NULL, the function returns a magick-image object containing the animated frames and prints it to the RStudio Viewer. If output_path is specified, the animation is saved as a GIF to the given file path and the function invisibly returns NULL. The gifski and magick packages are required for animation export.

Additionally, the returned object carries a "diegr_metadata" attribute with metadata such as details about the mesh used for plotting.

Details

Notes: If a mesh object is provided, its internal template name (mesh$template) overrides the template argument to ensure spatial consistency. When custom coords are provided, they are always used for plotting the sensor locations. The template parameter (or mesh$template) is then used only for generating the background mesh if it is not provided.

Examples

# \donttest{
# This example may take a few seconds to render.
# Run only if you want to generate the full animation.

# a) prepare data: compute the mean from baseline corrected signal for subject 2,
# first 10 points and only 13 epochs (epochs 14 and 15 are outliers)
edata <- pick_data(epochdata, subject_rg = 2, epoch_rg = 1:13, time_rg = 1:10)
data_base <- baseline_correction(edata, baseline_range = 1:9) # baseline correction
data_mean <- compute_mean(data_base, amplitude = "signal_base",
 type = "jack", domain = "space") # compute mean
# b) render the animation
# (t0 = 10 because the time of the stimulus in epochdata is in time point 10)
animate_topo_mean(data_mean, t_lim = c(1,50), t0 = 10)
#> `nframes` and `fps` adjusted to match transition
#> `nframes` and `fps` adjusted to match transition
#> # A tibble: 10 × 7
#>    format width height colorspace matte filesize density
#>    <chr>  <int>  <int> <chr>      <lgl>    <int> <chr>  
#>  1 GIF      480    360 sRGB       TRUE         0 72x72  
#>  2 GIF      480    360 sRGB       FALSE        0 72x72  
#>  3 GIF      480    360 sRGB       FALSE        0 72x72  
#>  4 GIF      480    360 sRGB       FALSE        0 72x72  
#>  5 GIF      480    360 sRGB       FALSE        0 72x72  
#>  6 GIF      480    360 sRGB       FALSE        0 72x72  
#>  7 GIF      480    360 sRGB       FALSE        0 72x72  
#>  8 GIF      480    360 sRGB       FALSE        0 72x72  
#>  9 GIF      480    360 sRGB       FALSE        0 72x72  
#> 10 GIF      480    360 sRGB       FALSE        0 72x72  
# }