MI-EEG Pattern Recognition

Reproducible motor-imagery EEG classification on the MI3 dataset with notebook and script-based training pipelines.

This repository contains multiple model families (CNN, LSTM-CNN, graph neural network, transformer, and CSP+SVM) evaluated under a shared comparison contract for per-subject runs.

Shortcuts Index

1. Quick Setup
2. Models and Entry Points
3. Data Download
4. How to Run Experiments
5. Results (Best Full Runs)
6. Cross-subject comparison charts

Quick Setup (Run Once)

Before running any experiment command, sync the environment from the repository root:

pip install uv
uv sync

Goal	Entry point	Command
Run SVM baseline	Notebooks/MI3_SVM.ipynb	uv run jupyter nbconvert --to notebook --execute --inplace Notebooks/MI3_SVM.ipynb
Run LENet CNN	Notebooks/MI3_CNN.ipynb	uv run jupyter nbconvert --to notebook --execute --inplace Notebooks/MI3_CNN.ipynb
Run LSTM-CNN	Notebooks/MI3_LSTM_CNN.ipynb	uv run jupyter nbconvert --to notebook --execute --inplace Notebooks/MI3_LSTM_CNN.ipynb
Run DDGCNN	Notebooks/MI3_Graph.ipynb	uv run jupyter nbconvert --to notebook --execute --inplace Notebooks/MI3_Graph.ipynb
Run EEG Transformer	Notebooks/FinalTransformer/main.py	uv run python Notebooks/FinalTransformer/main.py --mode all

Notes:

• Edit each notebook config cell before executing long runs.
• For Transformer runs, edit Notebooks/FinalTransformer/.env before execution.

Project Scope

• Dataset: MI3 motor-imagery EEG (3 classes: Rest, Elbow, Hand)
• Problem type: 3-class EEG classification
• Primary benchmark style: per-subject training/evaluation in batch mode (no pooled-subject training)
• Split policy lock: stratified train/val/test with val=0.1, test=0.1, seed=42
• Tuned-run policy: one-time Optuna tuning on a reference subject, then reuse tuned params for all subjects in that run
• Research goal: reduce the cognitive disconnect in prosthetic BCI control by decoding joint-specific imagery within the same limb
• Performance goal: exceed the reported 87.03% benchmark from the Deep Channel-Correlation Network on this same-limb task
• Engineering goal: improve accuracy while maintaining practical computational efficiency

Motivation and Impact

Many BCI prosthetic systems map unrelated imagined movements to prosthetic actions (for example, imagining a foot movement to command a hand action). This creates a cognitive disconnect and increases mental load.

This project targets a more intuitive alternative: decoding fine-grained motor imagery from different joints of the same limb (Elbow vs Hand, plus Rest). If successful, this improves control naturalness for users and advances scientific understanding of how overlapping motor-cortex patterns encode subtle movement intent.

Inference Problem

This repository solves a supervised 3-class EEG time-series classification problem.

• Input per trial: multivariate EEG matrix X in R^(C x T)
  • C = 62 channels
  • T = 800 samples for 4 seconds at 200 Hz
• Output per trial: one label in {0,1,2}
  • 0 = Rest
  • 1 = Elbow
  • 2 = Hand

Formal objective:

• Learn f: R^(62 x 800) -> {0,1,2} from labeled trials.

Practical challenge:

• EEG has low signal-to-noise ratio and high inter-subject variability.
• Elbow-vs-Hand imagery activates partially overlapping cortical regions, making class boundaries subtle.

Repository Layout

.
├── Datasets/
│   └── MI3/
│       ├── code/                 # MATLAB preprocessing scripts and channel dictionaries
│       ├── derivatives/          # Preprocessed .mat files (sub-001 ... sub-025)
│       └── README.md             # Dataset and preprocessing notes
├── Notebooks/
│   ├── MI3_CNN.ipynb
│   ├── MI3_LSTM_CNN.ipynb
│   ├── MI3_Graph.ipynb
│   ├── MI3_SVM.ipynb
│   ├── FinalTransformer/         # Scripted EEG Transformer pipeline
│   └── reports/
│       └── comparison_ready/     # Standardized run artifacts for model comparison
├── pyproject.toml
└── uv.lock

Models and Entry Points

Model Strategy and Rationale

This repository benchmarks several model families, from interpretable classical methods to modern deep learning architectures.

1. Traditional baseline (CSP/FBCSP + SVM)

• Purpose: establish a strong classical baseline and quantify gains from learned deep features.
• Notebook: Notebooks/MI3_SVM.ipynb

2. Multi-scale CNNs (LENet-style / EEG-focused CNN)

• Purpose: capture local temporal and spatial EEG patterns with efficient convolutions.
• Notebook: Notebooks/MI3_CNN.ipynb

3. Hybrid recurrent models (CNN-LSTM)

• Purpose: combine spatial feature extraction with temporal dynamics modeling over the full trial.
• Notebook: Notebooks/MI3_LSTM_CNN.ipynb

4. Transformer/attention models

• Purpose: model long-range dependencies and prioritize informative channels/time segments.
• Entry point: Notebooks/FinalTransformer/main.py

5. Graph models (dynamic channel-connectivity learning)

• Purpose: represent EEG electrodes as a graph and learn connectivity signatures for same-limb discrimination.
• Notebook: Notebooks/MI3_Graph.ipynb

Model family	Entry point	Typical output directory
LENet CNN	Notebooks/MI3_CNN.ipynb	Notebooks/reports/comparison_ready/LENet/{run_tag}/
LSTM-CNN	Notebooks/MI3_LSTM_CNN.ipynb	Notebooks/reports/comparison_ready/lstm_cnn/{run_tag}/
DDGCNN (graph)	Notebooks/MI3_Graph.ipynb	Notebooks/reports/comparison_ready/ddgcnn/{run_tag}/
EEG Transformer	Notebooks/FinalTransformer/main.py	Notebooks/reports/comparison_ready/eeg_transformer/{run_tag}/
CSP + SVM	Notebooks/MI3_SVM.ipynb	Notebooks/reports/comparison_ready/svm/{run_tag}/

Notes:

• Comparison artifacts are organized under Notebooks/reports/comparison_ready/.
• Transformer runs use NotebookConfig defaults from Notebooks/FinalTransformer/eeg_transformer_config.py plus overrides from .env and CLI args.

Data

Included in this repository

• Preprocessed MI3 derivatives in Datasets/MI3/derivatives/:
  • sub-001_eeg200hz.mat ... sub-025_eeg200hz.mat
• BIDS-style metadata files under Datasets/MI3/

Data volume and label quality

• Subjects: 25 healthy participants
• Approximate labeled trials: 22,500 total
• Task labels: Rest / Elbow / Hand motor imagery
• Label quality: original data collection used EMG monitoring to reject physical movement contamination; derivatives include artifact-removal and filtering workflow
• Privacy and access: public, anonymized, EEG-BIDS structured dataset

Preprocessed 200Hz derivatives download

If your local Datasets/MI3/derivatives/ folder is missing files, download the preprocessed 200Hz derivatives (already formatted for the notebook data loaders) from:

• https://drive.google.com/drive/folders/19c4yGRKv47XKby7k4ymT3Ne1zlw_XVQV?usp=sharing

Place all downloaded .mat files under:

• Datasets/MI3/derivatives/

Optional raw data (if you need to reprocess)

Raw CNT files are available from the public MI3 release:

• Scientific Data article: https://www.nature.com/articles/s41597-020-0535-2
• Dataverse DOI: https://doi.org/10.7910/DVN/RBN3XG

For MATLAB preprocessing requirements and plugin setup, see:

• Datasets/MI3/README.md
• Datasets/MI3/code/MI3_process.m

Prior Work

Key related references for this same-limb MI setting:

• FBCSP baseline for MI BCI: https://doi.org/10.1109/IJCNN.2008.4634130
• Same-limb MI classification (hand/elbow/rest): https://doi.org/10.1371/journal.pone.0121896
• Time-domain same-limb MI features: https://doi.org/10.1371/journal.pone.0174161
• The LENet CNN original architecture: Xiaojian Liao, Guang Li, You Wang, Lining Sun, Hongmiao Zhang, "Constructing lightweight and efficient spiking neural networks for EEG-based motor imagery classification," Biomedical Signal Processing and Control, vol. 100, part B, 2025, Art. no. 107000, ISSN 1746-8094. https://doi.org/10.1016/j.bspc.2024.107000
• EEGNet: https://doi.org/10.1088/1741-2552/aace8c
• DeepConvNet EEG decoding: https://doi.org/10.1002/hbm.23730
• CNN-LSTM MI decoding: https://doi.org/10.1016/j.bspc.2021.103342
• Deep channel-correlation network (87.03 benchmark): https://doi.org/10.1109/TNSRE.2019.2953121
• Channel-attention MLP-Mixer for MI: https://doi.org/10.1109/ICASSP43922.2022.9747488
• Dynamic graph CNN for EEG modeling: https://arxiv.org/abs/1809.02660

Environment and Installation

Requirements

• Python 3.11
• CUDA-compatible PyTorch build (configured to use cu124 index in pyproject.toml)
• uv package manager (recommended)

Setup

git clone https://github.com/AlonResearch/MI-EEG-Pattern-Recog.git
cd MI-EEG-Pattern-Recog
pip install uv
uv sync

Quick verification

uv run python -c "import torch; print(torch.__version__); print('cuda:', torch.cuda.is_available())"

How to Run Experiments

1. Choose a pipeline:
   • Notebook pipelines: open one notebook in Notebooks/.
   • EEG Transformer pipeline: configure Notebooks/FinalTransformer/.env and run Notebooks/FinalTransformer/main.py.
2. Set at minimum:
   • subject range (subject_start, subject_end)
   • run length (epochs or model-specific equivalent)
   • tuning flags (enable_tuning, n_trials, tuning_subject_id)
3. Keep split-lock defaults unchanged:
   • split_strategy = stratified_train_val_test
   • val_size = 0.1, test_size = 0.1, split_seed = 42
4. Run either:
   • all notebook cells top-to-bottom in a fresh kernel, or
   • uv run python Notebooks/FinalTransformer/main.py --mode all
5. Collect outputs from the run directory printed by the notebook/script.
6. Compare runs in the relevant comparison directory.

Reproducibility Contract

The pipelines used here are designed around these rules:

• Per-subject execution in batch mode
• Deterministic split settings across models (0.8/0.1/0.1 train/validation/test split)
• One-time tuning on tuning_subject_id and reuse of tuned params for the rest of subjects
• Standardized run artifacts for cross-model comparison

Expected Run Artifacts

Most comparison-ready runs export a subset of:

• run_manifest.json
• metrics_subject_level.csv
• metrics_subject_level.jsonl
• metrics_summary.json
• confusion_matrix_subject_level.npz
• training_history_subject_level.jsonl
• fig_training_curves.png
• fig_confusion_matrix.png
• run.log
• best_params_sub-XXX.json (when tuning is enabled)
• model checkpoint (*_best.pth) for PyTorch models

Results (Best Full Runs)

Selection rule used for this summary:

• Only full runs were considered (n_subjects_total = 25 and n_subjects_success = 25).
• Per model family, the run with highest overall_accuracy was selected.
• For SVM, both kernels are reported from full run 20260317_202816 using acc_rbf_test and acc_linear_test.

Best full run per model

Rank	Model	Run tag	Overall accuracy	Macro F1
1	EEG Transformer	20260318_164456	85.07%	84.99%
2	DDGCNN	20260319_224819	65.56%	65.55%
3	SVM (Linear kernel)	20260317_202816	58.93%	55.96%
4	CNN-LSTM	20260318_164251	57.91%	57.09%
5	LENet CNN	20260319_215417	54.76%	54.24%
6	SVM (RBF kernel)	20260317_202816	50.36%	50.15%

Average statistics by model

EEG Transformer (20260318_164456)

Average learning curve	Average confusion matrix

DDGCNN (20260319_224819)

Average learning curve	Average confusion matrix

SVM (20260317_202816)

Confusion matrix (Linear)	Confusion matrix (RBF)

CNN-LSTM (20260318_164251_full25_no_optuna_pub)

Learning curves (all subjects overlaid)	Average confusion matrix

LENet CNN (20260319_215417)

Average learning curve	Average confusion matrix

Cross-subject comparison charts

EEG Transformer (best full run)	DDGCNN (best full run)
CNN-LSTM (best full run)	SVM kernel accuracy comparison

Relevant notes:

• All rows above are from full 25-subject runs under the same split lock (val_size=0.1, test_size=0.1, split_seed=42).