EEG-BCI-Pipeline

End-to-end motor-imagery decoding using the BCI Competition IV-2a dataset.
Clean, modular, industry-aligned baseline suitable for BCI, neurotechnology, health-tech, and ML engineering roles.

Companion inference API (inference-only, Dockerized): EEG-MI-API

---

What This Project Demonstrates

• Ability to build a clean, modular EEG motor-imagery decoding pipeline.
• Solid understanding of CSP, LDA, and MNE preprocessing workflows.
• Defensible offline evaluation using Cohen’s kappa across multiple subjects.
• Professional software-engineering structure suitable for production teams.

---

Overview

This project implements a fully reproducible EEG motor-imagery pipeline using standard methods used in real BCI teams:

• Standard 10–20 montage
• 8–30 Hz band-pass filtering
• Epoching (0–4 s)
• Common Spatial Patterns (log-variance features)
• Linear Discriminant Analysis
• Multi-subject evaluation (A01–A09)
• CSP spatial patterns, confusion matrices, MI-epoch visualisations
• ICA artefact-removal demonstrated separately

A single polished notebook demonstrates the entire workflow.
All implementation logic lives in clean, modular src/ files.

---

Project Structure

EEG-BCI-Pipeline/
├── run_pipeline.py
├── train_final_model.py
├── data/
│   └── README.md
├── notebooks/
│   ├── 01_eeg_pipeline_demo.ipynb
│   └── 02_ica_artifact_removal.ipynb
├── models/
│   └── README.md
├── src/
│   ├── load_data.py
│   ├── preprocess.py
│   ├── train_csp_lda.py
│   └── evaluate.py
├── results/
│   └── kappa_scores.csv
└── requirements.txt

---

Aggregated Model Training (For Deployment Artefacts)

train_final_model.py trains a single CSP + LDA model across all nine subjects (1–9) and exports two separate artefacts:

• models/csp_transformer.joblib → used client-side at inference time (feature extraction)
• models/lda_classifier.joblib → used server-side by the FastAPI inference API

Run:

python train_final_model.py

Artefact Policy

Do not commit these .joblib artefacts to Git.
They are reproducible by re-running train_final_model.py.

---

Key Features

• Reproducible CSP → LDA motor-imagery pipeline
• Clean preprocessing and event extraction
• Per-subject decoding across A01–A09
• Kappa-based evaluation metric
• CSP patterns and confusion matrices
• ICA artefact-removal notebook
• Real engineering structure via modular src/ code

---

Environment

Tested with:

• Python 3.9
• MNE 1.8
• NumPy / SciPy / scikit-learn
• Matplotlib

Install dependencies:

pip install -r requirements.txt

---

Dataset Setup

Download BCI Competition IV-2a separately and place the .gdf files in:

EEG-BCI-Pipeline/data/
A01T.gdf
A01E.gdf
...
A09T.gdf
A09E.gdf

Place the evaluation .mat files here:

EEG-BCI-Pipeline/data/mat/

---

Running the Pipeline

git clone https://github.com/fractal360/EEG-BCI-Pipeline.git
python -m venv venv
source venv/bin/activate      # Mac/Linux
venv\Scripts\activate         # Windows
pip install -r requirements.txt
jupyter notebook

Open:

notebooks/01_eeg_pipeline_demo.ipynb

---

Outputs

• CSP spatial-pattern maps
• Motor-imagery epoch visualisations
• Confusion matrices
• Per-subject kappa scores

Aggregate results saved in:

results/kappa_scores.csv

---

License

MIT