Merge branch 'develop' into add-weibo2014-test

Author: bruAristimunha

.github/workflows/test.yml

@@ -50,7 +50,7 @@ jobs:
       - name: Run tests
         run: |
           echo "Running tests"
-          pytest -vv -s --tb=long --durations=0 --log-cli-level=INFO --cov=moabb --cov-report=xml moabb/tests --verbose  -n auto
+          pytest -vv -s --tb=long --durations=0 --log-cli-level=INFO --cov=moabb --cov-report=xml moabb/tests --verbose
 
       - name: Run pipelines
         run: |

docs/source/whats_new.rst

@@ -19,6 +19,8 @@ Develop branch  - 1.4  (dev)
 Enhancements
 ~~~~~~~~~~~~
 
+- Add new dataset :class:`moabb.datasets.BNCI2003_IVa` dataset (:gh:`811` by `Griffin Keeler`_)
+
 Bugs
 ~~~~
 
@@ -42,6 +44,7 @@ Enhancements
 - Adding :func:`moabb.analysis.plotting.dataset_bubble_plot` plus the corresponding tutorial (:gh:`753` by `Pierre Guetschel`_)
 - Adding :func:`moabb.datasets.utils.plot_all_datasets` and update the tutorial (:gh:`758` by `Pierre Guetschel`_)
 - Improve the dataset model cards in each API page (:gh:`765` by `Pierre Guetschel`_)
+- Refactor :class:`moabb.evaluation.CrossSessionEvaluation`, :class:`moabb.evaluation.CrossSubjectEvaluation` and  :class:`moabb.evaluation.WithinSessionEvaluation` to use the new splitter classes (:gh:`769` by `Bruno Aristimunha`_)
 - Adding tutorial on using mne-features (:gh:`762` by `Alexander de Ranitz`_, `Luuk Neervens`_, `Charlynn van Osch`_ and `Bruno Aristimunha`_)
 - Creating tutorial to expose the pre-processing steps (:gh:`771` by `Bruno Aristimunha`_)
 - Add function to auto-generate tables for the paper results documentation page (:gh:`785` by `Lucas Heck`_)
@@ -593,3 +596,4 @@ API changes
 .. _Radovan Vodila: https://github.com/rvodila
 .. _Ulysse Durand: https://github.com/UlysseDurand
 .. _Lucas Heck: https://github.com/lucas-heck
+.. _Griffin Keeler: https://github.com/griffinkeeler

examples/advanced_examples/plot_grid_search_withinsession.py

@@ -9,7 +9,6 @@
 """
 
 import os
-from pickle import load
 
 import matplotlib.pyplot as plt
 import seaborn as sns
@@ -132,44 +131,3 @@
 )
 sns.pointplot(data=result, y="score", x="pipeline", ax=axes, palette="Set1")
 axes.set_ylabel("ROC AUC")
-
-##########################################################
-# Load Best Model Parameter
-# -------------------------
-# The best model are automatically saved in a pickle file, in the
-# results directory. It is possible to load those model for each
-# dataset, subject and session. Here, we could see that the grid
-# search found a l1_ratio that is different from the baseline
-# value.
-
-with open(
-    "./Results/Models_WithinSession/BNCI2014-001/1/1test/GridSearchEN/fitted_model_best.pkl",
-    "rb",
-) as pickle_file:
-    GridSearchEN_Session_E = load(pickle_file)
-
-print(
-    "Best Parameter l1_ratio Session_E GridSearchEN ",
-    GridSearchEN_Session_E.best_params_["LogistReg__l1_ratio"],
-)
-
-print(
-    "Best Parameter l1_ratio Session_E VanillaEN: ",
-    pipelines["VanillaEN"].steps[2][1].l1_ratio,
-)
-
-with open(
-    "./Results/Models_WithinSession/BNCI2014-001/1/0train/GridSearchEN/fitted_model_best.pkl",
-    "rb",
-) as pickle_file:
-    GridSearchEN_Session_T = load(pickle_file)
-
-print(
-    "Best Parameter l1_ratio Session_T GridSearchEN ",
-    GridSearchEN_Session_T.best_params_["LogistReg__l1_ratio"],
-)
-
-print(
-    "Best Parameter l1_ratio Session_T VanillaEN: ",
-    pipelines["VanillaEN"].steps[2][1].l1_ratio,
-)

moabb/datasets/__init__.py

@@ -25,6 +25,7 @@
 from .bnci import BNCI2015003  # noqa: F401
 from .bnci import BNCI2015004  # noqa: F401
 from .bnci import (
+    BNCI2003_004,
     BNCI2014_001,
     BNCI2014_002,
     BNCI2014_004,

moabb/datasets/bnci.py

@@ -1,7 +1,11 @@
 """BNCI 2014-001 Motor imagery dataset."""
 
+import io
+import zipfile
+from pathlib import Path
+
 import numpy as np
-from mne import create_info
+from mne import Annotations, create_info
 from mne.channels import make_standard_montage
 from mne.io import RawArray
 from mne.utils import verbose
@@ -73,6 +77,7 @@ def load_data(
         dictionary containing events and their code.
     """
     dataset_list = {
+        "BNCI2003-004": _load_data_iva_2003,
         "BNCI2014-001": _load_data_001_2014,
         "BNCI2014-002": _load_data_002_2014,
         "BNCI2014-004": _load_data_004_2014,
@@ -88,6 +93,7 @@ def load_data(
     }
 
     baseurl_list = {
+        "BNCI2003-004": "https://www.bbci.de/competition/",
         "BNCI2014-001": BNCI_URL,
         "BNCI2014-002": BNCI_URL,
         "BNCI2015-001": BNCI_URL,
@@ -119,6 +125,57 @@ def load_data(
     )
 
 
+@verbose
+def _load_data_iva_2003(
+    subject,
+    path=None,
+    force_update=False,
+    update_path=None,
+    base_url=None,
+    only_filenames=False,
+    verbose=None,
+):
+    """Loads data for the BNCI2003-IVa dataset."""
+    # Raises ValueError is subject is not between 1 and 5
+    if (subject < 1) or (subject > 5):
+        raise ValueError(f"Subject must be between 1 and 5. Got {subject}")
+
+    subject_names = ["aa", "al", "av", "aw", "ay"]
+
+    # fmt: off
+    ch_names = ['Fp1', 'AFp1', 'Fpz', 'AFp2', 'Fp2', 'AF7', 'AF3',
+                'AF4', 'AF8', 'FAF5', 'FAF1', 'FAF2', 'FAF6', 'F7',
+                'F5', 'F3', 'F1', 'Fz', 'F2', 'F4', 'F6', 'F8', 'FFC7',
+                'FFC5', 'FFC3', 'FFC1', 'FFC2', 'FFC4', 'FFC6', 'FFC8',
+                'FT9', 'FT7', 'FC5', 'FC3', 'FC1', 'FCz', 'FC2', 'FC4',
+                'FC6', 'FT8', 'FT10', 'CFC7', 'CFC5', 'CFC3', 'CFC1',
+                'CFC2', 'CFC4', 'CFC6', 'CFC8', 'T7', 'C5', 'C3', 'C1',
+                'Cz','C2', 'C4', 'C6', 'T8', 'CCP7', 'CCP5', 'CCP3', 'CCP1',
+                'CCP2', 'CCP4', 'CCP6', 'CCP8', 'TP9', 'TP7', 'CP5', 'CP3',
+                'CP1', 'CPz', 'CP2', 'CP4', 'CP6', 'TP8', 'TP10', 'PCP7',
+                'PCP5', 'PCP3', 'PCP1', 'PCP2', 'PCP4', 'PCP6', 'PCP8', 'P9',
+                'P7', 'P5', 'P3', 'P1', 'Pz', 'P2', 'P4', 'P6', 'P8', 'P10',
+                'PPO7', 'PPO5', 'PPO1', 'PPO2', 'PPO6', 'PPO8', 'PO7', 'PO3',
+                'PO1', 'POz', 'PO2', 'PO4', 'PO8', 'OPO1', 'OPO2', 'O1',
+                'Oz', 'O2', 'OI1', 'OI2', 'I1', 'I2']
+    # fmt: on
+    ch_type = ["eeg"] * 118
+
+    url = "{u}download/competition_iii/berlin/100Hz/data_set_IVa_{r}_mat.zip".format(
+        u=base_url, r=subject_names[subject - 1]
+    )
+
+    filename = data_path(url, path, force_update, update_path)
+
+    if only_filenames:
+        return filename
+
+    runs, ev = _convert_bbci2003(filename[0], ch_names, ch_type)
+
+    session = {"0train": {"0": runs}}
+    return session
+
+
 @verbose
 def _load_data_001_2014(
     subject,
@@ -698,6 +755,102 @@ def _convert_run_bbci(run, ch_types, verbose=None):
     return raw, event_id
 
 
+def _convert_bbci2003(filename, ch_names, ch_type):
+    """
+    Process motor imagery data from MAT files.
+
+     Parameters
+     ----------
+        filename (str):
+            Path to the MAT file.
+        ch_names (list of str):
+            List of channel names.
+        ch_type (list of str):
+            List of channel types.
+
+    Returns
+    -------
+        raw (instance of RawArray):
+            returns MNE Raw object.
+    """
+    zip_path = Path(filename)
+
+    with zipfile.ZipFile(zip_path, "r") as z:
+        mat_files = [f for f in z.namelist() if f.endswith(".mat")]
+
+        if not mat_files:
+            raise FileNotFoundError("No .mat file found in zip archive.")
+
+        with z.open(mat_files[0]) as f:
+            data = loadmat(io.BytesIO(f.read()))
+
+        run = data
+        raw, ev = _convert_run_bbci2003(run, ch_names, ch_type)
+        return raw, ev
+
+
+@verbose
+def _convert_run_bbci2003(run, ch_names, ch_types, verbose=None):
+    """
+    Converts one run to a raw MNE object.
+
+    Parameters
+    ----------
+        run (ndarray):
+            The continuous EEG signal.
+        ch_names (list of str):
+            List of channel names.
+        ch_types (list of str):
+            List of channel types.
+        verbose (bool, str, int, or None):
+            If not None, override default verbose level (see :func:`mne.verbose`
+            and :ref:`Logging documentation <tut_logging>` for more).
+
+    Returns:
+        raw (instance of RawArray):
+            MNE Raw object.
+        event_id (dict):
+            Dictionary containing class names.
+    """
+    class_map = {
+        "right": "right_hand",
+        "foot": "feet",
+    }
+
+    raw_labels = run["mrk"]["y"][0, 0][0]
+    labels_mask = ~np.isnan(raw_labels)
+    valid_labels = raw_labels[labels_mask]
+    labels = valid_labels.astype(int) - 1
+
+    raw_positions = run["mrk"][0][0]["pos"][0]
+    positions = raw_positions[labels_mask]
+
+    sfreq = float(run["nfo"][0, 0]["fs"][0, 0])
+    eeg_data = run["cnt"]
+    raw_classes = run["mrk"]["className"]
+
+    while isinstance(raw_classes, (list, np.ndarray)) and len(raw_classes) == 1:
+        raw_classes = raw_classes[0]
+    class_names = [cls[0] for cls in raw_classes]
+
+    for i, word in enumerate(class_names):
+        if word in class_map:
+            class_names[i] = class_map[word]
+
+    info = create_info(ch_names=ch_names, ch_types=ch_types, sfreq=sfreq)
+
+    onset = positions / sfreq
+    duration = 0
+    description = [class_names[i] for i in labels]
+    annotations = Annotations(onset=onset, duration=duration, description=description)
+
+    event_id = {name: i for i, name in enumerate(class_names)}
+    raw = RawArray(data=eeg_data.T, info=info, verbose=verbose)
+    raw.set_annotations(annotations)
+
+    return raw, event_id
+
+
 @verbose
 def _convert_run_epfl(run, verbose=None):
     """Convert one run to raw."""
@@ -752,6 +905,51 @@ def data_path(
         )
 
 
+class BNCI2003_004(MNEBNCI):
+    """
+    BNCI2003_IVa Motor Imagery dataset.
+
+    Dataset IVa from BCI Competition III [1]_.
+
+    **Dataset Description**
+
+    This data set was recorded from five healthy subjects. Subjects sat in
+    a comfortable chair with arms resting on armrests. This data set
+    contains only data from the 4 initial sessions without feedback.
+    Visual cues indicated for 3.5 s which of the following 3 motor
+    imageries the subject should perform: (L) left hand, (R) right hand,
+    (F) right foot. The presentation of target cues were intermitted by
+    periods of random length, 1.75 to 2.25 s, in which the subject could
+    relax.
+
+    There were two types of visual stimulation: (1) where targets were
+    indicated by letters appearing behind a fixation cross (which might
+    nevertheless induce little target-correlated eye movements), and (2)
+    where a randomly moving object indicated targets (inducing target-
+    uncorrelated eye movements). From subjects al and aw 2 sessions of
+    both types were recorded, while from the other subjects 3 sessions
+    of type (2) and 1 session of type (1) were recorded.
+
+    References
+    ----------
+    .. [1] Guido Dornhege, Benjamin Blankertz, Gabriel Curio, and Klaus-Robert
+           Müller. Boosting bit rates in non-invasive EEG single-trial
+           classifications by feature combination and multi-class paradigms.
+           IEEE Trans. Biomed. Eng., 51(6):993-1002, June 2004.
+    """
+
+    def __init__(self):
+        super().__init__(
+            subjects=list(range(1, 6)),
+            sessions_per_subject=1,
+            events={"right_hand": 0, "feet": 1},
+            code="BNCI2003-004",
+            interval=[0, 3.5],
+            paradigm="imagery",
+            doi="10.1109/TBME.2004.827088",
+        )
+
+
 @depreciated_alias("BNCI2014001", "1.1")
 class BNCI2014_001(MNEBNCI):
     """BNCI 2014-001 Motor Imagery dataset.

moabb/datasets/summary_imagery.csv

@@ -1,5 +1,6 @@
 Dataset, #Subj, #Chan, #Classes, #Trials / class, Trials length (s), Freq (Hz), #Sessions, #Runs, Total_trials, PapersWithCode leaderboard
 AlexMI,8,16,3,20,3,512,1,1,480,https://paperswithcode.com/dataset/alexandremotorimagery-moabb
+BNCI2003_004,5,118,2,84,3.5,100,1,1,1400,
 BNCI2014_001,9,22,4,144,4,250,2,6,62208,https://paperswithcode.com/dataset/bnci2014-001-moabb-1
 BNCI2014_002,14,15,2,80,5,512,1,8,17920,https://paperswithcode.com/dataset/bnci2014-002-moabb-1
 BNCI2014_004,9,3,2,360,4.5,250,5,1,32400,https://paperswithcode.com/dataset/bnci2014-004-moabb-1

moabb/evaluations/__init__.py

@@ -10,4 +10,4 @@
     WithinSessionEvaluation,
 )
 from .splitters import CrossSessionSplitter, CrossSubjectSplitter, WithinSessionSplitter
-from .utils import create_save_path, save_model_cv, save_model_list
+from .utils import _create_save_path, _save_model_cv