In bnicenboim/eeguana: Flexible Manipulation of EEG Data

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

eeguana

Overview

A package for flexible manipulation of EEG data. eeguana provides a data.table powered framework through tidytable for manipulating EEG data with dplyr-like functions (e.g., eeg_mutate, eeg_filter, eeg_summarize) extended to a new class eeg_lst, other EEG-specialized functions, and ggplot wrapper functions. The new class is inspired by tidyverse principles but it's not really "tidy" (due to space considerations), it's a list of (i) a wide data table (signal_tbl) that contains the signal amplitudes at every sample point of the EEG, (ii) an events data table with information about markers (or triggers), blinks and other exported information, and (iii) a long table with experimental information, such as participant number (.recording), conditions, etc.

eeguana can do only basic pre-processing for now, more complete packages exist for Matlab (FieldTrip and EEGLAB) and python (MNE).

See Reference for more information about the functions of eeguana.

NOTE: Changes in dependencies that broke the package are now fixed!

Installation

There is still no released version of eeguana. The package is in the early stages of development, and it will be subject to a lot of changes. To install the latest version from github use:

devtools::install_github("bnicenboim/eeguana")

Example

Here, I exemplify the use of eeguana with (pre-processed) EEG data from BrainVision 2.0. The data belong to a simple experiment where a participant was presented 100 faces and 100 assorted images in random order. The task of the experiment was to mentally count the number of faces.

First we download the data:

# Run the following or just download the files from brain_vision folder in https://osf.io/tbwvz/
library(httr)
GET("https://osf.io/q6b7x//?action=download",
  write_disk("./faces.vhdr", overwrite = TRUE),
  progress()
)
GET("https://osf.io/ft5ge//?action=download",
  write_disk("./faces.vmrk", overwrite = TRUE),
  progress()
)
GET("https://osf.io/85dgj//?action=download",
  write_disk("./faces.dat", overwrite = TRUE),
  progress()
)

BrainVision 2.0 exports three files: faces.vhdr, faces.vmrk, and faces.dat. The file faces.vhdr contains the metadata and links to the other two files, faces.vmrk contains the triggers and other events in the samples, and faces.dat contains the signals at every sample for every channel recorded.

library(eeguana)

We first need to read the data:

faces <- read_vhdr("faces.vhdr")

The function read_vhdr() creates a list with data frames for the signal, events, segments information, and incorporates in its attributes generic EEG information.

faces

Some intervals were marked as "bad" by BrainVision, and so we'll remove them from the data. We'll also segment and baseline the data. In this experiment, the trigger "s70" was used for faces and "s71" for no faces. We'll segment the data using these two triggers.

faces_segs <- faces |>
  eeg_segment(.description %in% c("s70", "s71"),
    .lim = c(-.2, .25)
  ) |>
  eeg_events_to_NA(.type == "Bad Interval") |>
  eeg_baseline()

We can also edit the segmentation information and add more descriptive labels. Once the eeg_lst is segmented, the segments table includes the relevant columns from the events table (but without the leading dots).

eeguana has wrappers for many dplyr commands for the EEG data. These commands always return an entire eeg_lst object so that they can be piped using magrittr's pipe, |>.

## To only see the segments table:
segments_tbl(faces_segs)
## We modify the entire object:
faces_segs_some <- faces_segs |>
  eeg_mutate(
    condition =
      ifelse(description == "s70", "faces", "non-faces")
  ) |>
  eeg_select(-type)

faces_segs_some

With some "regular" ggplot skills, we can create customized plots. ggplot() applied to an eeg_lst object will downsample the signals (when needed), and convert them to a long-format data frame that is feed into ggplot. This object can then be customized.

library(ggplot2)
faces_segs_some |>
  eeg_select(O1, O2, P7, P8) |>
  ggplot(aes(x = .time, y = .value)) +
  geom_line(alpha = .1, aes(group = .id, color = condition)) +
  stat_summary(
    fun = "mean", geom = "line", alpha = 1, size = 1.5,
    aes(color = condition)
  ) +
  facet_wrap(~.key) +
  geom_vline(xintercept = 0, linetype = "dashed") +
  geom_vline(xintercept = .17, linetype = "dotted") +
  theme(legend.position = "bottom")

Another possibility is to create a topographic plot of the two conditions, by first making segments that include only the interval .1-.2 s after the onset of the stimuli, creating a table with interpolated amplitudes and using the ggplot wrapper plot_topo.

#fixes bug?
dev.off()

faces_segs_some |>
  eeg_filter(between(as_time(.sample, .unit = "milliseconds"), 100, 200)) |>
  eeg_group_by(condition) |>
  eeg_summarize(across_ch(mean, na.rm = TRUE)) |>
  plot_topo() +
  annotate_head() +
  geom_contour() +
  annotate_electrodes(colour = "black") +
  facet_grid(~condition)

Articles and dissertations using `eeguana`

nocite: '@*'

Other R packages for EEG/ERP data:

permuco4brain provides functions to compute permutation test in brain imagery data. It is specially designed for M-EEG/ERP data. This a vignette explains how to use it together with eeguana.
eegUtils some helper utilities for plotting and processing EEG data in active development by Matt Craddock.
erpR analysis of event-related potentials (ERPs) by Giorgio Arcara, Anna Petrova. It hasn't been updated since 2014.
mne-r provides fast acccess to MNE-Python from within R.