BrainDecode Plot

.gitignore

@@ -115,3 +115,4 @@ analysis/*
 
 # mac os x stuff
 *DS_store*
+/examples/pipelines_BrainDecode/

docs/source/whats_new.rst

@@ -25,6 +25,7 @@ Enhancements
 - Adding new tutorial to benchmark with GridSearchCV (:gh:`323` by `Igor Carrara`_)
 - Add six deep learning models (Tensorflow), and build a tutorial to show to use the deep learning model (:gh:`326` by `Igor Carrara`_, `Bruno Aristimunha`_ and `Sylvain Chevallier`_)
 - Add a augmentation model to the pipeline (:gh:`326` by `Igor Carrara`_)
+- Add BrainDecode example(:gh:`340` by `Igor Carrara`_ and `Bruno Aristimunha`_)
 - Add Google Analytics to the documentation (:gh:`335` by `Bruno Aristimunha`_)
 
 Bugs

examples/plot_braindecode.py

@@ -0,0 +1,166 @@
+"""
+=============================================================
+Benchmarking on MOABB with BrainDecode deep net architectures
+=============================================================
+This example shows how to use BrainDecode in combination with MOABB evaluation.
+In this example we use the architecture ShallowFBCSPNet.
+"""
+# Authors: Igor Carrara <igor.carrara@inria.fr>
+#          Bruno Aristimunha <b.aristimunha@gmail.com>
+#
+# License: BSD (3-clause)
+
+import matplotlib.pyplot as plt
+import mne
+import torch
+from braindecode import EEGClassifier
+from braindecode.models import EEGNetv4
+from sklearn.pipeline import Pipeline
+from skorch.callbacks import EarlyStopping, EpochScoring
+from skorch.dataset import ValidSplit
+
+from moabb.analysis.plotting import score_plot
+from moabb.datasets import BNCI2014001
+from moabb.evaluations import CrossSessionEvaluation
+from moabb.paradigms import MotorImagery
+from moabb.pipelines.utils_pytorch import (
+    InputShapeSetterEEG,
+    Transformer,
+    get_shape_from_baseconcat,
+)
+from moabb.utils import setup_seed
+
+
+mne.set_log_level(False)
+
+# Print Information PyTorch
+print(f"Torch Version: {torch.__version__}")
+
+# Set up GPU if it is there
+cuda = torch.cuda.is_available()
+device = "cuda" if cuda else "cpu"
+print("GPU is", "AVAILABLE" if cuda else "NOT AVAILABLE")
+
+
+###############################################################################
+# In this example, we will use only the dataset ``BNCI2014001``.
+#
+# Running the benchmark
+# ---------------------
+#
+# This example use the CrossSession evaluation procedure. We focus on the dataset BNCI2014001 and only on 1 subject
+# to reduce the computational time.
+#
+# To keep the computational time low the number of epoch is reduced. In a real situation we suggest to use
+# EPOCH = 1000
+# PATIENCE = 300
+#
+# This code is implemented to run on CPU. If you're using a GPU, do not use multithreading
+# (i.e. set n_jobs=1)
+
+
+# Set random seed to be able to reproduce results
+setup_seed(42)
+
+# Ensure that all operations are deterministic on GPU (if used) for reproducibility
+torch.backends.cudnn.deterministic = True
+torch.backends.cudnn.benchmark = False
+
+
+# Hyperparameter
+LEARNING_RATE = 0.0625 * 0.01  # result taken from BrainDecode
+WEIGHT_DECAY = 0  # result taken from BrainDecode
+BATCH_SIZE = 64  # result taken from BrainDecode
+EPOCH = 10
+PATIENCE = 3
+fmin = 4
+fmax = 100
+tmin = 0
+tmax = None
+
+# Load the dataset
+dataset = BNCI2014001()
+events = ["right_hand", "left_hand"]
+paradigm = MotorImagery(
+    events=events, n_classes=len(events), fmin=fmin, fmax=fmax, tmin=tmin, tmax=tmax
+)
+subjects = [1]
+X, _, _ = paradigm.get_data(dataset=dataset, subjects=subjects)
+# Define Transformer of Dataset compatible with Brain Decode
+create_dataset = Transformer()
+
+##############################################################################
+# Create Pipelines
+# ----------------
+# In order to create a pipeline we need to load a model from BrainDecode.
+# the second step is to define a skorch model using EEGClassifier from BrainDecode
+# that allow to convert the PyTorch model in a scikit-learn classifier.
+
+model = EEGNetv4(
+    in_chans=X.shape[1], n_classes=len(events), input_window_samples=X.shape[2]
+)
+
+"""model = EEGNetv4(in_chans=1,
+                 n_classes=2,
+                 input_window_samples=100
+                 )"""
+
+# Send model to GPU
+if cuda:
+    model.cuda()
+
+# Define a Skorch classifier
+clf = EEGClassifier(
+    module=model,
+    criterion=torch.nn.CrossEntropyLoss,
+    optimizer=torch.optim.Adam,
+    optimizer__lr=LEARNING_RATE,
+    batch_size=BATCH_SIZE,
+    max_epochs=EPOCH,
+    train_split=ValidSplit(0.2),
+    device=device,
+    callbacks=[
+        EarlyStopping(monitor="valid_loss", patience=PATIENCE),
+        EpochScoring(
+            scoring="accuracy", on_train=True, name="train_acc", lower_is_better=False
+        ),
+        EpochScoring(
+            scoring="accuracy", on_train=False, name="valid_acc", lower_is_better=False
+        ),
+        InputShapeSetterEEG(
+            params_list=["in_chans", "input_window_samples", "n_classes"],
+            input_dim_fn=get_shape_from_baseconcat,
+            module_name="module",
+        ),
+    ],
+    verbose=1,  # Not printing the results foe each epoch
+)
+
+# Create the pipelines
+pipes = {}
+pipes["EEGNetV4"] = Pipeline([("Braindecode_dataset", create_dataset), ("Net", clf)])
+
+
+##############################################################################
+# Evaluation
+# ----------
+dataset.subject_list = dataset.subject_list[:2]
+
+evaluation = CrossSessionEvaluation(
+    paradigm=paradigm,
+    datasets=dataset,
+    suffix="braindecode_example",
+    overwrite=True,
+    return_epochs=True,
+    n_jobs=1,
+)
+
+results = evaluation.process(pipes)
+
+print(results.head())
+
+##############################################################################
+# Plot Results
+# ----------------
+score_plot(results)
+plt.show()

moabb/pipelines/__init__.py

@@ -21,3 +21,12 @@
     from .utils_deep_model import EEGNet, TCN_block
 except ModuleNotFoundError as err:
     print("Tensorflow not install, you could not use deep learning pipelines")
+
+try:
+    from .utils_pytorch import InputShapeSetterEEG, get_shape_from_baseconcat
+except ModuleNotFoundError as err:
+    print(
+        "To use the get_shape_from_baseconcar and InputShapeSetterEEG, "
+        "you need to install `braindecode`."
+        "`pip install braindecode` or Please refer to `https://braindecode.org`."
+    )

moabb/pipelines/utils_pytorch.py

@@ -0,0 +1,144 @@
+from functools import partial
+from inspect import getmembers, isclass, isroutine
+
+from braindecode.datasets import BaseConcatDataset, create_from_X_y
+from numpy import unique
+from sklearn.base import BaseEstimator, TransformerMixin
+from skorch.callbacks import Callback
+from torch.nn import Module
+
+
+class Transformer(BaseEstimator, TransformerMixin):
+    """
+    Class to Load the data from MOABB in a format compatible with braindecode
+    """
+
+    def __init__(self, kw_args=None):
+        self.kw_args = kw_args
+
+    def fit(self, X, y=None):
+        self.y = y
+        return self
+
+    def transform(self, X, y=None):
+        dataset = create_from_X_y(
+            X.get_data(),
+            y=self.y,
+            window_size_samples=X.get_data().shape[2],
+            window_stride_samples=X.get_data().shape[2],
+            drop_last_window=False,
+            sfreq=X.info["sfreq"],
+        )
+
+        return dataset
+
+    def __sklearn_is_fitted__(self):
+        """Return True since Transfomer is stateless."""
+        return True
+
+
+def get_shape_from_baseconcat(X):
+    """Get the shape of the data after BaseConcatDataset is applied"""
+    if isinstance(X, BaseConcatDataset):
+        in_channel = X[0][0].shape[0]
+        input_window_samples = X[0][0].shape[1]
+        return {"in_chans": in_channel, "input_window_samples": input_window_samples}
+    else:
+        return X.shape
+
+
+def _find_model_from_braindecode(model_name):
+    # soft dependency on braindecode
+    model_list = []
+    import braindecode.models as models
+
+    for ds in getmembers(models, isclass):
+        if issubclass(ds[1], Module):
+            model_list.append(ds[1])
+
+    for model in model_list:
+        if model_name == model.__name__:
+            # return an instance of the found model not initialized
+            if model_name == "ShallowFBCSPNet":
+                model = partial(model, final_conv_length="auto")
+
+            return model
+    raise ValueError(f"{model_name} not found in braindecode models")
+
+
+class InputShapeSetterEEG(Callback):
+    """Sets the input dimension of the PyTorch module to the input dimension
+    of the training data.
+    This can be of use when the shape of X is not known beforehand,
+    e.g. when using a skorch model within an sklearn pipeline and
+    grid-searching feature transformers, or using feature selection
+    methods.InputShapeSetterEEG
+    Basic usage:
+
+    Parameters
+    ----------
+    params_list : list
+      The list of parameters that define the
+      input dimension in its ``__init__`` method.
+      Usually the mandatory parameters from the model.
+    input_dim_fn : callable, None (default=None)
+      In case your ``X`` value is more complex and deriving the input
+      dimension is not as easy as ``X.shape[-1]`` you can pass a callable
+      to this parameter which takes ``X`` and returns the input dimension.
+    module_name : str (default='module')
+      Only needs change when you are using more than one module in your
+      skorch model (e.g., in case of GANs).
+    """
+
+    def __init__(
+        self,
+        params_list=None,
+        input_dim_fn=None,
+        module_name="module",
+    ):
+        self.module_name = module_name
+        self.params_list = params_list
+        self.input_dim_fn = input_dim_fn
+
+    def get_input_dim(self, X):
+        if self.input_dim_fn is not None:
+            return self.input_dim_fn(X)
+        if len(X.shape) < 2:
+            raise ValueError(
+                "Expected at least two-dimensional input data for X. "
+                "If your data is one-dimensional, please use the "
+                "`input_dim_fn` parameter to infer the correct "
+                "input shape."
+            )
+        return X.shape[-1]
+
+    def on_train_begin(self, net, X, y, **kwargs):
+        # Get the parameters of the neural network
+        params = net.get_params()
+        # Get the input dimensions from the BaseConcat dataset
+        params_get_from_dataset: dict = self.get_input_dim(X)
+        # Get the number of classes in the output labels
+        params_get_from_dataset["n_classes"] = len(unique(y))
+
+        # Get all the parameters of the neural network module
+        all_params_module = getmembers(params["module"], lambda x: not (isroutine(x)))
+        # Filter the parameters to only include the selected ones
+        selected_params_module = list(
+            filter(lambda x: x in self.params_list, all_params_module)
+        )
+
+        # Check if the selected parameters from the model already match the dataset parameters
+        if all(
+            self.params_get_from_dataset[name] == value
+            for name, value in selected_params_module
+        ):
+            return
+
+        # Find the new module based on the current module's class name
+        new_module = _find_model_from_braindecode(net.module.__class__.__name__)
+        # Initialize the new module with the dataset parameters
+        module_initilized = new_module(**params_get_from_dataset)
+        # Set the neural network module to the new initialized module
+        net.set_params(**{"module": module_initilized})
+        # Initialize the new module
+        net.initialize_module()