Learnable Wavelets with GREEN for EEG Classification#

This tutorial demonstrates how to use the GREEN (Gabor Riemann EEGNet) model for EEG classification. GREEN combines learnable Gabor wavelets with Riemannian geometry for biomarker exploration.

Introduction#

GREEN [Paillard et al., 2025] is a lightweight architecture that learns optimal time-frequency representations directly from EEG data. Unlike traditional approaches that use fixed filter banks, GREEN employs parametrized Gabor wavelets with learnable center frequencies and bandwidths.

Key features of GREEN:

  • Learnable wavelets: Center frequencies and FWHM are optimized during training

  • Riemannian geometry: SPD covariance matrices with BiMap and LogEig layers

  • Lightweight: Efficient architecture suitable for clinical applications

Setup and Imports#

First, we import the necessary libraries.

import warnings

import matplotlib.pyplot as plt
import numpy as np
import torch

from braindecode import EEGClassifier
from moabb.datasets import BNCI2014_001
from moabb.paradigms import MotorImagery
from sklearn.metrics import accuracy_score, balanced_accuracy_score
from sklearn.preprocessing import LabelEncoder
from skorch.callbacks import EpochScoring
from skorch.dataset import ValidSplit

from spd_learn.models import Green


warnings.filterwarnings("ignore")

Loading the Dataset#

We use the BCI Competition IV Dataset 2a (BNCI2014_001), which contains motor imagery EEG recordings from 9 subjects.

dataset = BNCI2014_001()
paradigm = MotorImagery(n_classes=4)

print(f"Dataset: {dataset.code}")
print(f"Subjects: {dataset.subject_list}")
Choosing from all possible events
Dataset: BNCI2014-001
Subjects: [1, 2, 3, 4, 5, 6, 7, 8, 9]

Creating the GREEN Model#

GREEN processes EEG through the following stages:

  1. Wavelet Convolution: Learnable Gabor wavelets extract time-frequency features

  2. Covariance Pooling: Compute SPD covariance matrices

  3. Shrinkage: Ledoit-Wolf regularization for stable covariance estimation

  4. BiMap Layers: Optional spatial filtering on the SPD manifold

  5. LogEig + BatchReNorm: Project to tangent space with normalization

  6. MLP Head: Classification with dropout

Key parameters:

  • n_freqs_init: Number of wavelet center frequencies (default: 10)

  • kernel_width_s: Wavelet kernel width in seconds

  • oct_min/oct_max: Frequency range in octaves (relative to 1 Hz)

  • shrinkage_init: Initial shrinkage coefficient (sigmoid input)

# Model hyperparameters
n_chans = 22
n_outputs = 4
sfreq = 250  # Sampling frequency of BNCI2014_001

# Create GREEN model
model = Green(
    n_outputs=n_outputs,
    n_chans=n_chans,
    sfreq=sfreq,
    n_freqs_init=10,  # Number of learnable wavelets
    kernel_width_s=0.5,  # 500ms wavelet width
    oct_min=0,  # ~1 Hz minimum
    oct_max=5,  # ~32 Hz maximum (2^5)
    shrinkage_init=-3.0,  # Initial shrinkage (sigmoid(-3) ≈ 0.05)
    hidden_dim=(16,),  # Hidden layer in MLP head
    dropout=0.5,
)

print("\nGREEN Model Architecture:")
print(model)
GREEN Model Architecture:
Green(
  (conv_layers): Sequential(
    (0): WaveletConv()
  )
  (cov_layer): CovLayer()
  (spd_layers): Sequential(
    (0): Shrinkage()
  )
  (proj): Sequential(
    (0): LogEig()
    (1): BatchReNorm()
  )
  (head): Sequential(
    (0): BatchNorm1d(2530, eps=1e-05, momentum=0.1, affine=True, bias=True, track_running_stats=True)
    (1): Dropout(p=0.5, inplace=False)
    (2): Linear(in_features=2530, out_features=16, bias=True)
    (3): GELU(approximate='none')
    (4): BatchNorm1d(16, eps=1e-05, momentum=0.1, affine=True, bias=True, track_running_stats=True)
    (5): Dropout(p=0.5, inplace=False)
    (6): Linear(in_features=16, out_features=4, bias=True)
  )
)

Setting up the Classifier#

We use Braindecode’s EEGClassifier wrapper for scikit-learn compatibility.

# Training hyperparameters
batch_size = 32
max_epochs = 50
learning_rate = 1e-3

device = "cuda" if torch.cuda.is_available() else "cpu"
print(f"\nUsing device: {device}")

clf = EEGClassifier(
    model,
    criterion=torch.nn.CrossEntropyLoss,
    optimizer=torch.optim.AdamW,
    optimizer__lr=learning_rate,
    optimizer__weight_decay=1e-4,
    train_split=ValidSplit(0.1, stratified=True, random_state=42),
    batch_size=batch_size,
    max_epochs=max_epochs,
    callbacks=[
        (
            "train_acc",
            EpochScoring(
                "accuracy", lower_is_better=False, on_train=True, name="train_acc"
            ),
        ),
        (
            "bal_acc",
            EpochScoring(
                "balanced_accuracy",
                lower_is_better=False,
                on_train=False,
                name="bal_acc",
            ),
        ),
    ],
    device=device,
    verbose=1,
)
Using device: cpu

Training and Evaluation#

We train on a single subject for demonstration.

subject_id = 1

# Cache configuration
cache_config = dict(
    save_raw=True,
    save_epochs=True,
    save_array=True,
    use=True,
    overwrite_raw=False,
    overwrite_epochs=False,
    overwrite_array=False,
)

# Load data
X, labels, meta = paradigm.get_data(
    dataset=dataset, subjects=[subject_id], cache_config=cache_config
)

# Encode labels
le = LabelEncoder()
y = le.fit_transform(labels)

print(f"\nData shape: {X.shape}")
print(f"Classes: {le.classes_}")

# Split by session
train_idx = meta.query("session == '0train'").index.to_numpy()
test_idx = meta.query("session == '1test'").index.to_numpy()

print(f"Training samples: {len(train_idx)}")
print(f"Test samples: {len(test_idx)}")

# Train
clf.fit(X[train_idx], y[train_idx])

# Evaluate
y_pred_train = clf.predict(X[train_idx])
y_pred_test = clf.predict(X[test_idx])

train_acc = accuracy_score(y[train_idx], y_pred_train)
test_acc = accuracy_score(y[test_idx], y_pred_test)
test_bal_acc = balanced_accuracy_score(y[test_idx], y_pred_test)

print(f"\n{'=' * 50}")
print(f"Results for Subject {subject_id}")
print(f"{'=' * 50}")
print(f"Train Accuracy:    {train_acc * 100:.2f}%")
print(f"Test Accuracy:     {test_acc * 100:.2f}%")
print(f"Test Balanced Acc: {test_bal_acc * 100:.2f}%")
Data shape: (528, 22, 1001)
Classes: ['feet' 'left_hand' 'right_hand' 'tongue']
Training samples: 240
Test samples: 288
  epoch    bal_acc    train_acc    train_loss    valid_acc    valid_loss     dur
-------  ---------  -----------  ------------  -----------  ------------  ------
      1     0.3750       0.4531        1.2664       0.3750        1.2707  5.4728
      2     0.4583       0.5885        0.9787       0.4583        1.2018  5.4488
      3     0.4583       0.6250        0.8768       0.4583        1.1577  5.4180
      4     0.5000       0.6719        0.8302       0.5000        1.1083  5.5317
      5     0.6250       0.6927        0.8465       0.6250        1.0610  5.4152
      6     0.5000       0.8177        0.6963       0.5000        1.0128  5.3803
      7     0.6667       0.7865        0.6504       0.6667        0.9688  5.4430
      8     0.6667       0.8229        0.6277       0.6667        0.9421  5.4703
      9     0.6250       0.7865        0.6347       0.6250        0.9475  5.4423
     10     0.6667       0.8802        0.5478       0.6667        0.9236  5.5647
     11     0.5000       0.8490        0.5479       0.5000        0.8943  5.6365
     12     0.5000       0.8906        0.5100       0.5000        0.9110  5.6146
     13     0.6250       0.8958        0.4496       0.6250        0.8860  5.7168
     14     0.5833       0.9010        0.4217       0.5833        0.9122  5.8327
     15     0.5833       0.8906        0.4358       0.5833        0.9301  5.7224
     16     0.5417       0.9115        0.4109       0.5417        0.8715  6.0156
     17     0.5417       0.9323        0.3716       0.5417        0.8944  5.3738
     18     0.4583       0.9323        0.3860       0.4583        0.9041  6.0454
     19     0.5833       0.9583        0.3505       0.5833        0.8146  5.8330
     20     0.6250       0.9115        0.3482       0.6250        0.7743  6.3218
     21     0.6667       0.9323        0.3339       0.6667        0.7925  5.3050
     22     0.6250       0.9271        0.3307       0.6250        0.8202  5.7904
     23     0.6250       0.9375        0.2894       0.6250        0.8061  5.5947
     24     0.5417       0.9375        0.3091       0.5417        0.9527  5.6135
     25     0.7500       0.9531        0.2881       0.7500        0.7537  5.5884
     26     0.6667       0.9531        0.3038       0.6667        0.7881  5.7357
     27     0.6667       0.9479        0.2822       0.6667        0.7990  5.8977
     28     0.6667       0.9635        0.2336       0.6667        0.7583  5.6106
     29     0.7083       0.9427        0.2755       0.7083        0.6901  5.5682
     30     0.7500       0.9479        0.2676       0.7500        0.7085  5.6253
     31     0.7500       0.9844        0.2396       0.7500        0.6524  5.6167
     32     0.6667       0.9531        0.2631       0.6667        0.6556  5.6130
     33     0.7500       0.9479        0.2312       0.7500        0.6762  5.5884
     34     0.6667       0.9844        0.2177       0.6667        0.8325  5.3362
     35     0.6667       0.9583        0.1958       0.6667        0.7182  5.7579
     36     0.5833       0.9479        0.2440       0.5833        0.7873  5.8010
     37     0.6250       0.9740        0.1894       0.6250        0.7576  5.6881
     38     0.6667       0.9688        0.1975       0.6667        0.7654  5.7819
     39     0.7083       0.9688        0.1819       0.7083        0.6668  5.6351
     40     0.7083       0.9740        0.1746       0.7083        0.6281  4.3544
     41     0.7083       0.9688        0.1659       0.7083        0.7341  4.0252
     42     0.7083       0.9792        0.1494       0.7083        0.7023  4.0071
     43     0.7083       0.9896        0.1494       0.7083        0.6859  3.9800
     44     0.7500       0.9792        0.1453       0.7500        0.6911  3.9024
     45     0.7500       0.9792        0.1662       0.7500        0.6559  3.9115
     46     0.7083       0.9948        0.1499       0.7083        0.6821  3.9257
     47     0.6250       0.9896        0.1640       0.6250        0.7535  3.9513
     48     0.6667       0.9635        0.1727       0.6667        0.7281  3.9631
     49     0.7917       0.9688        0.1615       0.7917        0.6070  3.9974
     50     0.7500       0.9583        0.1857       0.7500        0.6439  4.0104

==================================================
Results for Subject 1
==================================================
Train Accuracy:    97.50%
Test Accuracy:     74.31%
Test Balanced Acc: 74.31%

Visualizing Learned Wavelets#

One advantage of GREEN is that we can inspect the learned wavelet parameters to understand which frequencies are most discriminative.

# Extract learned wavelet parameters
wavelet_conv = model.conv_layers[0]
foi_learned = wavelet_conv.foi.detach().cpu().numpy()  # Center frequencies (octaves)
fwhm_learned = wavelet_conv.fwhm.detach().cpu().numpy()  # Bandwidth (octaves)

# Convert from octaves to Hz
foi_hz = 2**foi_learned
bandwidth_hz = 2 ** np.abs(fwhm_learned)

print("\nLearned Wavelet Parameters:")
print("-" * 40)
for i, (f, bw) in enumerate(zip(foi_hz, bandwidth_hz)):
    print(f"Wavelet {i + 1}: Center = {f:.1f} Hz, Bandwidth = {bw:.1f} Hz")

# Plot wavelet frequencies
fig, ax = plt.subplots(figsize=(10, 4))

# Sort by center frequency for visualization
sort_idx = np.argsort(foi_hz)
foi_sorted = foi_hz[sort_idx]
bw_sorted = bandwidth_hz[sort_idx]

x_pos = np.arange(len(foi_sorted))
ax.bar(x_pos, foi_sorted, yerr=bw_sorted / 2, capsize=5, color="steelblue", alpha=0.7)
ax.set_xlabel("Wavelet Index (sorted by frequency)", fontsize=12)
ax.set_ylabel("Center Frequency (Hz)", fontsize=12)
ax.set_title("Learned Gabor Wavelet Center Frequencies", fontsize=14)
ax.set_xticks(x_pos)
ax.grid(True, alpha=0.3, axis="y")

# Add frequency band annotations
ax.axhline(y=8, color="green", linestyle="--", alpha=0.5, label="Mu band (8-12 Hz)")
ax.axhline(y=12, color="green", linestyle="--", alpha=0.5)
ax.axhline(
    y=13, color="orange", linestyle="--", alpha=0.5, label="Beta band (13-30 Hz)"
)
ax.axhline(y=30, color="orange", linestyle="--", alpha=0.5)
ax.legend(loc="upper left")

plt.tight_layout()
plt.show()
Learned Gabor Wavelet Center Frequencies
Learned Wavelet Parameters:
----------------------------------------
Wavelet 1: Center = 1.0 Hz, Bandwidth = 2.0 Hz
Wavelet 2: Center = 1.5 Hz, Bandwidth = 1.3 Hz
Wavelet 3: Center = 2.1 Hz, Bandwidth = 1.1 Hz
Wavelet 4: Center = 3.2 Hz, Bandwidth = 1.6 Hz
Wavelet 5: Center = 4.6 Hz, Bandwidth = 2.3 Hz
Wavelet 6: Center = 6.7 Hz, Bandwidth = 3.4 Hz
Wavelet 7: Center = 10.3 Hz, Bandwidth = 4.9 Hz
Wavelet 8: Center = 14.8 Hz, Bandwidth = 7.3 Hz
Wavelet 9: Center = 22.5 Hz, Bandwidth = 11.1 Hz
Wavelet 10: Center = 31.7 Hz, Bandwidth = 16.0 Hz

Training History#

Let’s visualize the training progress.

fig, axes = plt.subplots(1, 2, figsize=(12, 4))

history = clf.history
epochs = range(1, len(history) + 1)

# Loss
ax1 = axes[0]
ax1.plot(epochs, history[:, "train_loss"], "b-", label="Train Loss", linewidth=2)
ax1.plot(epochs, history[:, "valid_loss"], "r--", label="Valid Loss", linewidth=2)
ax1.set_xlabel("Epoch", fontsize=12)
ax1.set_ylabel("Loss", fontsize=12)
ax1.set_title("Training and Validation Loss", fontsize=14)
ax1.legend(fontsize=10)
ax1.grid(True, alpha=0.3)

# Accuracy
ax2 = axes[1]
ax2.plot(epochs, history[:, "train_acc"], "b-", label="Train Acc", linewidth=2)
ax2.plot(epochs, history[:, "bal_acc"], "r--", label="Valid Balanced Acc", linewidth=2)
ax2.set_xlabel("Epoch", fontsize=12)
ax2.set_ylabel("Accuracy", fontsize=12)
ax2.set_title("Training and Validation Accuracy", fontsize=14)
ax2.legend(fontsize=10)
ax2.grid(True, alpha=0.3)
ax2.set_ylim([0, 1])

plt.tight_layout()
plt.show()
Training and Validation Loss, Training and Validation Accuracy

Summary#

In this tutorial, we demonstrated how to:

  1. Create a GREEN model with learnable Gabor wavelets

  2. Train and evaluate on motor imagery EEG data

  3. Visualize the learned wavelet parameters

GREEN’s learnable wavelets allow the model to discover optimal time-frequency representations for the classification task, often focusing on the mu (8-12 Hz) and beta (13-30 Hz) rhythms known to be modulated during motor imagery.

Total running time of the script: (4 minutes 28.527 seconds)