""".. _bcic-iv-2a-moabb-trial: Basic Brain Decoding on EEG Data ======================================== This tutorial shows you how to train and test deep learning models with Braindecode in a classical EEG setting: you have trials of data with labels (e.g., Right Hand, Left Hand, etc.). .. contents:: This example covers: :local: :depth: 2 """ ###################################################################### # Loading and preparing the data # ------------------------------------- # ###################################################################### # Loading the dataset # ~~~~~~~~~~~~~~~~~~~~~~~ # ###################################################################### # First, we load the data. In this tutorial, we load the BCI Competition # IV 2a data [1]_ using braindecode's wrapper to load via # `MOABB library `_ [2]_. # # .. note:: # To load your own datasets either via mne or from # preprocessed X/y numpy arrays, see :ref:`mne-dataset-example` # and :ref:`custom-dataset-example`. # from braindecode.datasets import MOABBDataset subject_id = 3 dataset = MOABBDataset(dataset_name="BNCI2014_001", subject_ids=[subject_id]) ###################################################################### # Preprocessing # ~~~~~~~~~~~~~ # ###################################################################### # Now we apply preprocessing like bandpass filtering to our dataset. # You can either apply functions provided by :class:`mne.io.Raw` or # :class:`mne.Epochs` or apply your own functions, either to the # MNE object or the underlying numpy array. # # .. note:: # Generally, braindecode prepocessing is directly applied to the loaded # data, and not applied on-the-fly as transformations, such as in # PyTorch-libraries like ``_. # from numpy import multiply from braindecode.preprocessing import ( Preprocessor, exponential_moving_standardize, preprocess, ) low_cut_hz = 4.0 # low cut frequency for filtering high_cut_hz = 38.0 # high cut frequency for filtering # Parameters for exponential moving standardization factor_new = 1e-3 init_block_size = 1000 # Factor to convert from V to uV factor = 1e6 preprocessors = [ Preprocessor("pick_types", eeg=True, meg=False, stim=False), # Keep EEG sensors Preprocessor(lambda data: multiply(data, factor)), # Convert from V to uV Preprocessor("filter", l_freq=low_cut_hz, h_freq=high_cut_hz), # Bandpass filter Preprocessor( exponential_moving_standardize, # Exponential moving standardization factor_new=factor_new, init_block_size=init_block_size, ), ] # Transform the data preprocess(dataset, preprocessors, n_jobs=-1) ###################################################################### # Extracting Compute Windows # ~~~~~~~~~~~~~~~~~~~~~~~~~~ # ###################################################################### # Now we extract compute windows from the signals, these will be the inputs # to the deep networks during training. In the case of trialwise # decoding, we just have to decide if we want to include some part # before and/or after the trial. For our work with this dataset, # it was often beneficial to also include the 500 ms before the trial. # from braindecode.preprocessing import create_windows_from_events trial_start_offset_seconds = -0.5 # Extract sampling frequency, check that they are same in all datasets sfreq = dataset.datasets[0].raw.info["sfreq"] assert all([ds.raw.info["sfreq"] == sfreq for ds in dataset.datasets]) # Calculate the trial start offset in samples. trial_start_offset_samples = int(trial_start_offset_seconds * sfreq) # Create windows using braindecode function for this. It needs parameters to define how # trials should be used. windows_dataset = create_windows_from_events( dataset, trial_start_offset_samples=trial_start_offset_samples, trial_stop_offset_samples=0, preload=True, ) ###################################################################### # Splitting the dataset into training and validation sets # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ # ###################################################################### # We can easily split the dataset using additional info stored in the # description attribute, in this case ``session`` column. We select # ``0train`` for training and ``1test`` for validation. # splitted = windows_dataset.split("session") train_set = splitted["0train"] # Session train valid_set = splitted["1test"] # Session evaluation ###################################################################### # Creating a model # ---------------- # ###################################################################### # Now we create the deep learning model! # First thing we need to do is know the properties of our signals. # For this, we use the :func:`braindecode.datautil.infer_signal_properties` function: # from braindecode.datautil import infer_signal_properties sig_props = infer_signal_properties(train_set, mode="classification") print(sig_props) ###################################################################### # Braindecode comes with some # predefined convolutional neural network architectures for raw # time-domain EEG. Here, we use the :class:`ShallowFBCSPNet # ` model from [3]_. These models are # pure `PyTorch `_ deep learning models, therefore # to use your own model, it just has to be a normal PyTorch # :class:`torch.nn.Module`. # import torch from braindecode.models import ShallowFBCSPNet from braindecode.util import set_random_seeds cuda = torch.cuda.is_available() # check if GPU is available, if True chooses to use it device = "cuda" if cuda else "cpu" if cuda: torch.backends.cudnn.benchmark = True # Set random seed to be able to roughly reproduce results # Note that with cudnn benchmark set to True, GPU indeterminism # may still make results substantially different between runs. # To obtain more consistent results at the cost of increased computation time, # you can set `cudnn_benchmark=False` in `set_random_seeds` # or remove `torch.backends.cudnn.benchmark = True` seed = 20200220 set_random_seeds(seed=seed, cuda=cuda) model = ShallowFBCSPNet( n_chans=sig_props["n_chans"], n_outputs=sig_props["n_outputs"], n_times=sig_props["n_times"], final_conv_length="auto", ) # Display torchinfo table describing the model print(model) # Send model to GPU if cuda: model = model.cuda() ###################################################################### # Model Training # -------------- # ###################################################################### # Now we will train the network! :class:`EEGClassifier # ` is a Braindecode object # responsible for managing the training of neural networks. # It inherits from :class:`skorch.classifier.NeuralNetClassifier`, # so the training logic is the same as in ``_. # ###################################################################### # .. note:: # In this tutorial, we use some default parameters that we # have found to work well for motor decoding, however we strongly # encourage you to perform your own hyperparameter optimization using # cross validation on your training data. # from skorch.callbacks import LRScheduler from skorch.helper import predefined_split from braindecode import EEGClassifier # We found these values to be good for the shallow network: lr = 0.0625 * 0.01 weight_decay = 0 # For deep4 they should be: # lr = 1 * 0.01 # weight_decay = 0.5 * 0.001 batch_size = 64 n_epochs = 4 classes = list(range(sig_props["n_outputs"])) clf = EEGClassifier( model, criterion=torch.nn.CrossEntropyLoss, optimizer=torch.optim.AdamW, train_split=predefined_split(valid_set), # using valid_set for validation optimizer__lr=lr, optimizer__weight_decay=weight_decay, batch_size=batch_size, callbacks=[ "accuracy", ("lr_scheduler", LRScheduler("CosineAnnealingLR", T_max=n_epochs - 1)), ], device=device, classes=classes, ) # Model training for the specified number of epochs. ``y`` is ``None`` as it is # already supplied in the dataset. _ = clf.fit(train_set, y=None, epochs=n_epochs) ###################################################################### # Plotting Results # ---------------- # ###################################################################### # Now we use the history stored by skorch throughout training to plot # accuracy and loss curves. # import matplotlib.pyplot as plt import pandas as pd from matplotlib.lines import Line2D # Extract loss and accuracy values for plotting from history object results_columns = ["train_loss", "valid_loss", "train_accuracy", "valid_accuracy"] df = pd.DataFrame( clf.history[:, results_columns], columns=results_columns, index=clf.history[:, "epoch"], ) # get percent of misclass for better visual comparison to loss df = df.assign( train_misclass=100 - 100 * df.train_accuracy, valid_misclass=100 - 100 * df.valid_accuracy, ) fig, ax1 = plt.subplots(figsize=(8, 3)) df.loc[:, ["train_loss", "valid_loss"]].plot( ax=ax1, style=["-", ":"], marker="o", color="tab:blue", legend=False, fontsize=14 ) ax1.tick_params(axis="y", labelcolor="tab:blue", labelsize=14) ax1.set_ylabel("Loss", color="tab:blue", fontsize=14) ax2 = ax1.twinx() # instantiate a second axes that shares the same x-axis df.loc[:, ["train_misclass", "valid_misclass"]].plot( ax=ax2, style=["-", ":"], marker="o", color="tab:red", legend=False ) ax2.tick_params(axis="y", labelcolor="tab:red", labelsize=14) ax2.set_ylabel("Misclassification Rate [%]", color="tab:red", fontsize=14) ax2.set_ylim(ax2.get_ylim()[0], 85) # make some room for legend ax1.set_xlabel("Epoch", fontsize=14) # where some data has already been plotted to ax handles = [] handles.append( Line2D([0], [0], color="black", linewidth=1, linestyle="-", label="Train") ) handles.append( Line2D([0], [0], color="black", linewidth=1, linestyle=":", label="Valid") ) plt.legend(handles, [h.get_label() for h in handles], fontsize=14) plt.tight_layout() ###################################################################### # Plotting a Confusion Matrix # ---------------------------- # ####################################################################### # Here we generate a confusion matrix as in [3]_. # from sklearn.metrics import confusion_matrix from braindecode.visualization import plot_confusion_matrix # generate confusion matrices # get the targets y_true = valid_set.get_metadata().target y_pred = clf.predict(valid_set) # generating confusion matrix confusion_mat = confusion_matrix(y_true, y_pred) # add class labels # label_dict is class_name : str -> i_class : int label_dict = windows_dataset.datasets[0].window_kwargs[0][1]["mapping"] # sort the labels by values (values are integer class labels) labels = [k for k, v in sorted(label_dict.items(), key=lambda kv: kv[1])] # plot the basic conf. matrix plot_confusion_matrix(confusion_mat, class_names=labels) ############################################################# # # # References # ---------- # # .. [1] Tangermann, M., Müller, K.R., Aertsen, A., Birbaumer, N., Braun, C., # Brunner, C., Leeb, R., Mehring, C., Miller, K.J., Mueller-Putz, G. # and Nolte, G., 2012. Review of the BCI competition IV. # Frontiers in neuroscience, 6, p.55. # # .. [2] Jayaram, Vinay, and Alexandre Barachant. # "MOABB: trustworthy algorithm benchmarking for BCIs." # Journal of neural engineering 15.6 (2018): 066011. # # .. [3] Schirrmeister, R.T., Springenberg, J.T., Fiederer, L.D.J., Glasstetter, M., # Eggensperger, K., Tangermann, M., Hutter, F., Burgard, W. and Ball, T. (2017), # Deep learning with convolutional neural networks for EEG decoding and visualization. # Hum. Brain Mapping, 38: 5391-5420. https://onlinelibrary.wiley.com/doi/10.1002/hbm.23730. # # .. include:: /links.inc