NeuroSpark ⚡

Distributed EEG Motor Imagery Pipeline

#eeg #brain-computer-interface #motor-imagery #pyspark #big-data #neuroscience #mlops #dvc #mlflow #kedro #random-forest

---

Pipeline Big Data pour la classification d'imagerie motrice à partir de signaux EEG (PhysioNet Motor Movement/Imagery dataset, 109 sujets, 1 308 fichiers EDF).

Le projet illustre une chaîne complète ingestion → features → entraînement → évaluation → dashboard avec trois outils du quotidien des équipes Data : Kedro, MLflow et DVC.

---

Pourquoi ces trois outils

Le notebook initial (warehouse/etape1_poc/poc_eeg.ipynb) faisait tout dans un seul fichier. Voici ce que chaque outil apporte concrètement :

Kedro — structure et orchestration

Le notebook a été découpé en 5 pipelines indépendantes. Chaque pipeline est un package Python avec ses nodes et son DAG.

• Séparation config / code : hyperparamètres et chemins dans conf/base/parameters.yml
• Catalog déclaratif (catalog.yml) : datasets Spark/JSON définis une fois, appelés par nom
• Visualisation du DAG : make kedro-viz → http://localhost:4141
• Run partiel : kedro run --pipeline=features

MLflow — traçabilité des expériences

À chaque entraînement, MLflow enregistre automatiquement :

Traqué	Détail
Hyperparamètres	num_trees_grid, max_depth_grid, cv_folds
Métriques test	test_accuracy, test_f1, test_precision_weighted, test_recall_weighted
Modèle	Sérialisé (artifact)
Runs CV	4 folds par exemple

Backend SQLite (mlruns/mlflow.db). UI : make mlflow-ui → http://localhost:5000 → onglet Experiments → neuro-spark-eeg-v2.

DVC — versioning des données

Le dataset EEG fait plusieurs Go. DVC le verse dans un cache (local ou S3/GCS) et garde un hash de chaque sortie de pipeline.

• dvc repro ne relance que les étapes dont les inputs ont changé
• dvc dag montre le graphe des dépendances
• dvc.lock enregistre les hashes courants (commit dans Git, pas les données)

Pattern : chaque stage DVC appelle un make correspondant à un pipeline Kedro. Les deux outils se complètent sans se chevaucher.

---

Quick start

Prérequis : Linux, Java 17, Python 3.11+, .venv

git clone https://github.com/ForgedEmir/neuro-spark.git
cd neuro-spark

.venv/bin/pip install -r requirements.txt

make download          # Télécharge le dataset (~3 Go, 1308 fichiers EDF)
make run               # Pipeline complète

Step by step

make ingest        # EDF → Parquet partitionné
make features      # FFT band power + normalisation Z-score
make train         # CrossValidator RandomForest + tracking MLflow
make evaluate      # Métriques sur test set
make export        # Données pour le dashboard

Visualisations

make kedro-viz       # DAG Kedro       → http://localhost:4141
make mlflow-ui       # Tracking ML      → http://localhost:5000
make mlflow-report   # PNG comparant les runs → data/mlflow_report.png
make dashboard       # Dashboard Dash   → http://localhost:8050

DVC

make dvc-dag         # Graphe des stages
make dvc-status      # État du cache
make dvc-repro       # Rejouer en sautant ce qui n'a pas changé

---

Architecture

src/neuro_spark/
├── core.py                       # Algos EEG : FFT, normalisation, MLlib pipeline
├── hooks.py                      # SparkSession (config dans conf/base/spark.yml)
├── settings.py                   # Configuration Kedro
├── pipeline_registry.py          # Enregistre les 5 pipelines
└── pipelines/
    ├── ingestion/                # EDF → Parquet (un fichier par sujet/run)
    ├── features/                 # FFT theta/alpha/beta/gamma + lateralization
    ├── training/                 # CrossValidator + log MLflow
    ├── evaluation/               # Charge le modèle, predict, metrics
    └── export_dashboard/         # Échantillons Parquet pour le dashboard

conf/base/
├── catalog.yml                   # SparkDataset, JSONDataset
├── parameters.yml                # Hyperparamètres ML, chemins, bandes EEG
├── spark.yml                     # spark.executor.memory, arrow, etc.
└── logging.yml                   # Config rich logging

scripts/
├── download_eeg.py               # Récupère le dataset PhysioNet
└── mlflow_report.py              # Génère le rapport graphique des runs

dvc.yaml                          # 6 stages DVC qui appellent make
dashboard.py                      # Dashboard Dash (EEG + prédictions)

---

Données

Métrique	Valeur
Signal brut	~25M lignes (1 308 fichiers EDF, 64 canaux, 160 Hz)
Epochs	~80 000 de 2 secondes
Features	16 par epoch (4 bandes × 3 canaux moteurs C3/Cz/C4 + 4 lateralization)
Classes	Repos (T0), main gauche (T1), main droite (T2)
Accuracy	~44 % (random = 33 %)

---

Tests & lint

make test            # pytest
make lint            # ruff (style)

---

Contributing

Resource	Description
CONTRIBUTING.md	Setup, workflow, PR process
CODE_OF_CONDUCT.md	Community standards
SECURITY.md	Vulnerability reporting
LICENSE	MIT — free to use, modify, distribute

---

NeuroSpark — De l'EEG brut aux prédictions, distribué.