okbalefthanded / aawedha

Deep Learning toolbox for EEG based Brain-Computer Interface signals decoding and benchmarking

Aawedha

Aawedha (عاودها means repeate it or do it again in Algerian arabic) is a deep learning learning package based on Keras with Tensorflow backend, for EEG based Brain-Computer Interface (BCI) decoding research and application.

Compatible with Python 3.6 and above

---

Motivation

The main goal for this package is to provide a flexible and complete analysis and benchmarking tool for Deep Learning research in BCI.

---

Features

Aawedha provides a complete set of operations from raw data preprocessing to model evaluation and results visualization. A regular workflow using this package consists of 5 instructions:

• Create a dataset: preprocess raw data to create epoched EEG trials (run once)
• Define an Evaluation : Single subject or Cross Subject analysis with the data and model.
• Generate a random data split.
• Run evaluation : train and test model.
• Visualize the results and what the model has learnt.

The tables below show the available datasets and models, for a detailed tutorial on running the evaluations follow the colaboratory notebook in the examples folder.

Data

Datasets	Paradigm	Participants(subjects)
BCI Competetion IV 2a	Motor Imagery	9
Exoskleton	SSVEP	12
Freiburg Online ERP	ERP	13
Inria ERN	ErrP	26
Laresi Hyrbid	Hybrid ERP/SSVEP	1
Physionet_MI	Motor Imagery	109
San Diego	SSVEP	10
Tsinghua	SSVEP	35

Deep Learning Models

Title	Paradigm	Architecture
EEGNET	Motor Imagery / ERP/Errp	ConvNet
EEGNet SSVEP	SSVEP	ConvNet
DeepConvNet/ ShallowConvNet	Motor Imagery / ERP/Errp	ConvNet
1DCSU	SSVEP	ConvNet
PodNet	SSVEP	ConvNet
KoreaU CNN	SSVEP	ConvNet
Xu_Jiang CNN	SSVEP	ConvNet

---

Installation

First, clone Aawedha using git:

git clone https://github.com/okbalefthanded/aawedha.git

Then, cd to the Aawedha folder, install requirements using pip then proceed to package setup:

cd aawedha

pip install -r requirements.txt

python setup.py install

---

Usage

Follow the colab notebooks in /examples

---

Citation

---

Acknowledgment

aawedha's Issues

[Enhacement] Custom/Addon Model Configurations

Custom and new modules such as Layers, Optimizers and Losses are often developed outside the Keras/Tensorflow main repo and takes time to be officially adopted.
we'll add and test these modules from different sources: Tensorflow-addons, third-party github repos.

[Dataset] Add LARESI hybrid BCI

• Add Hybrid paradigm as a composition of ERP/SSVEP
• Add DataSet class for Hybrid LARESI BCI experiments

Requirements change: TorchSummary -> TorchInfo

• Change the torchsummary package to torchinfo.
• https://github.com/TylerYep/torchinfo/tree/main

[PYTORCH] Sharpness-Aware minimization

• Add SAM/ASAM/GSAM implementation following the code from SAM :

• SAM

• A(adaptive)SAM

• GSAM

[Features] Add Pytorch support

Currently we only support TF/Keras as computing engines, but due to the wider adoption of PyTorch by both the ML and BCI communities, we require an urgent PyTorch support. We will keep both frameworks and experiment with the situation.

[Enhacement] Refactor code

The current code contains a lot of duplication, and since the core features are mature and stable enough; a general refactor is required.

TF calibration metrics

• Expected calibration error (ECE) and Brier loss from Tensorflow probability do not support sparse labels and require nd logits.
• Tensorflow addons Matthew Correlation Coefficient (MCC) does not support sparse labels yet. An open PR is yet to be merged.

Tensorflow/Keras update

• Since the adoption of PyTorch, we reduced the feature development of TF/Keras based operations. Additionally, TFA (tensorflow addons) announced moved to a wind down minimal maintenance and release mode.
  tensorflow/addons#2807

[bug fixes] Check Datasets download links

[feature] Add Baseline method

For a fair comparison, we add non-DL state-of-the art methods as baselines

More datasets

SSVEP

• Single Flicker SSVEP
• Mobile BCI DataSet ERP and SSVEP
• Low amplitude depths and high frequencies SSVEp stimuli for reactive BCI
• eldBETA: A Large Eldercare-oriented Benchmark Database of SSVEP-BCI for the Aging Population
• An Open Dataset for Wearable SSVEP-Based Brain-Computer Interfaces

[Features] Add training on TPUs

[Feature] [dependency] PyTorch-Optimizers

• PyTorch optimizers that are not supported by the official torch implementation are added as separate classes, this behavior makes the codebase heavier, a fix for this is to base the torch optimizers on the PyTorch-Optimizer (as we've done with torchmetrics).

[features] Add automatic datasets download

[Feature] Add JAX support

• Plenty of High-Level API for JAX exists, we think that Elegy is a good fit due to its Keras like design.

[features] Add Visualization and model explainability modules

[Dataset] Add ERP and SSVEP datasets

Motor Imagery and Error-Related potentials datasets have been well tested, other BCI paradigms dataset should be added.

Missing requirement: pingouin for statistical significance testing

Update Pytorch to v2.0

Torchmetrics Breaking changes

Starting from torchmetrics version 0.11.0, all metrics require "task" argument to be specified at instantiation. Also, for multiclass tasks, the number of classes must be provided as "num_classes" argument.

Add Documentation

[DL] Add Models

EEGNet and the models available with it are well tested, newer and different architectures are required.

[Enhacement] port to TF 2.0

The package is well tested on TF 1.15, a quick test with TF 2.0 revealed that the evaluation loop breaks while calling .fit() method with callbacks.
This issue is first raised for class_weights callback when the train_data split has only a portion of all classes. a quick fix can be using Stratified k-fold cross-validation for data split to ensure same percentage of samples of each target class.

[CI] Add Tests

[Feature] Add more SSVEP models

• IENet
• MHLCNN
• DSCNN
• SSVEPNET
• SSVEPFormer
• FTN/DTN [code]
• bi-SiamCA [code]
• tCNN / fb-tCNN [code]

[features] Add pipeline

• evaluation pipeline

[features] add datasets

• INRIA ERN
• Physionet MI