Importing and visualising EEG data
In this vignette, we illustrate how to analyse one-dimensional EEG time series using Bayesian generalised additive multilevel models (BGAMMs). We use an example dataset from the eegkit package, containing event-related potentials (ERPs) recorded from multiple participants, channels, and experimental groups. First, we import the data and visualise the average ERP waveforms across groups for a selection of channels.
library(neurogam)
library(ggplot2)
library(eegkit)
library(dplyr)
# Change default brms backend
options(brms.backend = "cmdstanr")
# Use the ggplot2 neurogam theme
theme_set(theme_neurogam() )
# Import eegdata
data("eegdata", package = "eegkitdata")
# plotting the average ERP per group and some channels
eegdata |>
summarise(voltage = mean(voltage), .by = c(group, channel, time) ) |>
filter(channel %in% sample(x = unique(levels(eegdata$channel) ), size = 9) ) |>
ggplot(aes(x = time, y = voltage, colour = group) ) +
geom_hline(yintercept = 0, linetype = "dashed") +
geom_line() +
facet_wrap(~channel)
For simplicity, we focus on a single channel (P6), convert time to seconds, round numerical values, and remove missing observations.
# reshape the data
eeg_data <- eegdata |>
# keeping only one channel
dplyr::filter(channel == "P6") |>
# converting timesteps to seconds
mutate(time = (time + 1) / 256) |>
# rounding numeric variables
mutate(across(where(is.numeric), ~ round(.x, 4) ) ) |>
# removing NAs
na.omit()
# show a few rows
head(eeg_data)
#> subject group condition trial channel time voltage
#> 1 co2a0000364 a S1 0 P6 0.0039 -2.909
#> 2 co2a0000364 a S1 0 P6 0.0078 -4.862
#> 3 co2a0000364 a S1 0 P6 0.0117 -5.351
#> 4 co2a0000364 a S1 0 P6 0.0156 -4.374
#> 5 co2a0000364 a S1 0 P6 0.0195 -1.933
#> 6 co2a0000364 a S1 0 P6 0.0234 0.997Fitting the model
We first fit a BGAMM to assess differences between experimental groups over time. The model estimates smooth temporal trajectories while accounting for participant-level variability. Statistical evidence is assessed using posterior odds, with a threshold of 10.
# fitting the BGAMM to identify clusters (around 30 min on 4 parallel apple M4 cores)
results <- testing_through_time(
# EEG data
data = eeg_data,
# participant column
participant_id = "subject",
# EEG column
outcome_id = "voltage",
# name of predictor in data
predictor_id = "group",
# basis dimension
kvalue = 20,
# baseline period
baseline_window = c(0, 0.1),
# we recommend fitting the GAMM on summary statistics (mean and SD)
multilevel = "summary",
# threshold on posterior odds
threshold = 10,
# participant-specific smooth?
varying_smooth = TRUE,
# number of MCMCs
chains = 4,
# number of parallel cores
cores = 4,
# save the model
file = "cache/temporal_model"
)Visualising the results
The print() method summarises the identified temporal clusters, whereas plot() displays the observed data, posterior predictions, and clusters supported by the specified posterior odds threshold.
# displaying the identified clusters
print(results)
#>
#> ==== Time-resolved GAM results ================================
#> Analysis: Temporal (1D)
#> Model coordinates: time
#> Cluster coordinates: time
#> Contrast: condition_difference
#> Posterior odds mode: directional_rope
#> Odds threshold: 10
#> Clusters found: 1
#>
#> Cluster table:
#>
#> sign id onset offset duration n_points time_min time_max
#> positive 1 0.305 0.367 0.062 17 0.305 0.367
#> =================================================================
# plotting the data, model's predictions, and clusters
plot(results)
Computing clusters at the participant-level
We can also identify temporal clusters separately for each participant. Here, we omit the group predictor (predictor_id = NA) and set participant_clusters = TRUE to assess when EEG amplitude differs from zero, at both the group and participant levels. Because group membership is constant within participants, the group contrast is not included in this analysis.
# fitting the BGAMM to identify clusters
results_ppt <- testing_through_time(
# EEG data
data = eeg_data,
# participant column
participant_id = "subject",
# EEG column
outcome_id = "voltage",
# baseline period
baseline_window = c(0, 0.1),
# here we use no predictor (because group varies across participants)
predictor_id = NA,
# group basis dimension
kvalue = 20,
# we recommend fitting the GAMM with summary statistics (mean and SD)
multilevel = "summary",
# return clusters at both the group and participant levels
participant_clusters = TRUE,
# threshold on posterior odds
threshold = 10,
# number of MCMCs
chains = 4,
# number of parallel cores
cores = 4
)Visualising participant-level results
As before, we can inspect the identified clusters using the dedicated print() and plot() methods.
# displaying the identified clusters
print(results_ppt)
#>
#> ==== Time-resolved GAM results ================================
#> Analysis: Temporal (1D)
#> Model coordinates: time
#> Cluster coordinates: time
#> Contrast: one_sample
#> Posterior odds mode: directional_rope
#> Odds threshold: 10
#> Clusters found: 40
#>
#> Cluster table:
#>
#> participant sign id onset offset duration n_points time_min time_max
#> co2a0000364 negative 1 0.106 0.312 0.207 54 0.106 0.312
#> co2a0000364 negative 2 0.484 0.668 0.184 48 0.484 0.668
#> co2a0000364 negative 3 0.727 0.984 0.258 67 0.727 0.984
#> co2a0000365 negative 1 0.144 0.223 0.078 21 0.144 0.223
#> co2a0000365 negative 2 0.273 0.984 0.711 183 0.273 0.984
#> co2a0000368 negative 1 0.148 1.000 0.852 219 0.148 1.000
#> co2a0000369 positive 1 0.207 0.410 0.203 53 0.207 0.410
#> co2a0000369 negative 2 0.727 0.785 0.059 16 0.727 0.785
#> co2a0000369 negative 3 0.930 0.992 0.062 17 0.930 0.992
#> co2a0000371 negative 1 0.141 0.320 0.180 47 0.141 0.320
#> co2a0000371 negative 2 0.496 0.664 0.168 44 0.496 0.664
#> co2a0000372 positive 1 0.973 1.000 0.027 8 0.973 1.000
#> ... 28 additional cluster(s) not shown.
#> =================================================================
# plotting the data, model's predictions, and clusters
plot(results_ppt)
Posterior predictive checks
Posterior predictive checks (PPCs) help assess how well the model reproduces key features of the observed data. We recommend inspecting model predictions at both the group and participant levels. The neurogam::ppc() function provides convenient visualisations, whereas brms::pp_check() offers additional diagnostics (see the bayesplot PPC overview).
# posterior predictive checks (PPCs) at the group level
ppc(object = results, ppc_type = "group")
# posterior predictive checks (PPCs) at the participant level
ppc(object = results, ppc_type = "participant")
