braindecode 0.8__py3-none-any.whl → 1.0.0__py3-none-any.whl

braindecode/datasets/bcicomp.py

@@ -0,0 +1,194 @@
+# Authors: Maciej Sliwowski <maciek.sliwowski@gmail.com>
+#          Mohammed Fattouh <mo.fattouh@gmail.com>
+#
+# License: BSD (3-clause)
+
+from __future__ import annotations
+
+import glob
+import os
+import os.path as osp
+from os import remove
+from shutil import unpack_archive
+
+import mne
+import numpy as np
+from mne.utils import verbose
+from scipy.io import loadmat
+
+from braindecode.datasets import BaseConcatDataset, BaseDataset
+
+DATASET_URL = (
+    "https://stacks.stanford.edu/file/druid:zk881ps0522/"
+    "BCI_Competion4_dataset4_data_fingerflexions.zip"
+)
+
+
+class BCICompetitionIVDataset4(BaseConcatDataset):
+    """BCI competition IV dataset 4.
+
+    Contains ECoG recordings for three patients moving fingers during the experiment.
+    Targets correspond to the time courses of the flexion of each of five fingers.
+    See http://www.bbci.de/competition/iv/desc_4.pdf and
+    http://www.bbci.de/competition/iv/ for the dataset and competition description.
+    ECoG library containing the dataset: https://searchworks.stanford.edu/view/zk881ps0522
+
+    Notes
+    -----
+    When using this dataset please cite [1]_ .
+
+    Parameters
+    ----------
+    subject_ids : list(int) | int | None
+        (list of) int of subject(s) to be loaded. If None, load all available
+        subjects. Should be in range 1-3.
+
+    References
+    ----------
+    .. [1] Miller, Kai J. "A library of human electrocorticographic data and analyses."
+       Nature human behaviour 3, no. 11 (2019): 1225-1235.
+       https://doi.org/10.1038/s41562-019-0678-3
+    """
+
+    possible_subjects = [1, 2, 3]
+
+    def __init__(self, subject_ids: list[int] | int | None = None):
+        data_path = self.download()
+        if isinstance(subject_ids, int):
+            subject_ids = [subject_ids]
+        if subject_ids is None:
+            subject_ids = self.possible_subjects
+        self._validate_subjects(subject_ids)
+        files_list = [f"{data_path}/sub{i}_comp.mat" for i in subject_ids]
+        datasets = []
+        for file_path in files_list:
+            raw_train, raw_test = self._load_data_to_mne(file_path)
+            desc_train = dict(
+                subject=file_path.split("/")[-1].split("sub")[1][0],
+                file_name=file_path.split("/")[-1],
+                session="train",
+            )
+            desc_test = dict(
+                subject=file_path.split("/")[-1].split("sub")[1][0],
+                file_name=file_path.split("/")[-1],
+                session="test",
+            )
+            datasets.append(BaseDataset(raw_train, description=desc_train))
+            datasets.append(BaseDataset(raw_test, description=desc_test))
+        super().__init__(datasets)
+
+    @staticmethod
+    def download(path=None, force_update=False, verbose=None):
+        """Download the dataset.
+
+        Parameters
+        ----------
+        path  (None | str) – Location of where to look for the data storing location.
+        If None, the environment variable or config parameter
+        MNE_DATASETS_(dataset)_PATH is used. If it doesn’t exist, the “~/mne_data”
+        directory is used. If the dataset is not found under the given path, the data
+        will be automatically downloaded to the specified folder.
+        force_update (bool) – Force update of the dataset even if a local copy exists.
+        verbose (bool, str, int, or None) – If not None, override default verbose level
+        (see mne.verbose())
+
+        Returns
+        -------
+
+        """
+        signature = "BCICompetitionIVDataset4"
+        folder_name = "BCI_Competion4_dataset4_data_fingerflexions"
+        # Check if the dataset already exists (unpacked). We have to do that manually
+        # because we are removing .zip file from disk to save disk space.
+
+        from moabb.datasets.download import get_dataset_path  # keep soft dependency
+
+        path = get_dataset_path(signature, path)
+        key_dest = "MNE-{:s}-data".format(signature.lower())
+        # We do not use mne _url_to_local_path due to ':' in the url that causes problems on Windows
+        destination = osp.join(path, key_dest, folder_name)
+        if len(list(glob.glob(osp.join(destination, "*.mat")))) == 6:
+            return destination
+        data_path = _data_dl(
+            DATASET_URL,
+            osp.join(destination, folder_name, signature),
+            force_update=force_update,
+        )
+        unpack_archive(data_path, osp.dirname(destination))
+        # removes .zip file that the data was unpacked from
+        remove(data_path)
+        return destination
+
+    @staticmethod
+    def _prepare_targets(upsampled_targets, targets_stride):
+        original_targets = np.full_like(upsampled_targets, np.nan)
+        original_targets[::targets_stride] = upsampled_targets[::targets_stride]
+        return original_targets
+
+    def _load_data_to_mne(self, file_path):
+        data = loadmat(file_path)
+        test_labels = loadmat(file_path.replace("comp.mat", "testlabels.mat"))
+        train_data = data["train_data"]
+        test_data = data["test_data"]
+        upsampled_train_targets = data["train_dg"]
+        upsampled_test_targets = test_labels["test_dg"]
+
+        signal_sfreq = 1000
+        original_target_sfreq = 25
+        targets_stride = int(signal_sfreq / original_target_sfreq)
+
+        original_targets = self._prepare_targets(
+            upsampled_train_targets, targets_stride
+        )
+        original_test_targets = self._prepare_targets(
+            upsampled_test_targets, targets_stride
+        )
+
+        ch_names = [f"{i}" for i in range(train_data.shape[1])]
+        ch_names += [f"target_{i}" for i in range(original_targets.shape[1])]
+        ch_types = ["ecog" for _ in range(train_data.shape[1])]
+        ch_types += ["misc" for _ in range(original_targets.shape[1])]
+
+        info = mne.create_info(sfreq=signal_sfreq, ch_names=ch_names, ch_types=ch_types)
+        info["temp"] = dict(target_sfreq=original_target_sfreq)
+        train_data = np.concatenate([train_data, original_targets], axis=1)
+        test_data = np.concatenate([test_data, original_test_targets], axis=1)
+
+        raw_train = mne.io.RawArray(train_data.T, info=info)
+        raw_test = mne.io.RawArray(test_data.T, info=info)
+        # TODO: show how to resample targets
+        return raw_train, raw_test
+
+    def _validate_subjects(self, subject_ids):
+        if isinstance(subject_ids, (list, tuple)):
+            if not all((subject in self.possible_subjects for subject in subject_ids)):
+                raise ValueError(
+                    f"Wrong subject_ids parameter. Possible values: {self.possible_subjects}. "
+                    f"Provided {subject_ids}."
+                )
+        else:
+            raise ValueError(
+                "Wrong subject_ids format. Expected types: None, list, tuple, int."
+            )
+
+
+@verbose
+def _data_dl(url, destination, force_update=False, verbose=None):
+    # Code taken from moabb due to problem with ':' occurring in path
+    # On Windows ':' is a forbidden in folder name
+    # moabb/datasets/download.py
+
+    from pooch import file_hash, retrieve  # keep soft dependency
+
+    if not osp.isfile(destination) or force_update:
+        if osp.isfile(destination):
+            os.remove(destination)
+        if not osp.isdir(osp.dirname(destination)):
+            os.makedirs(osp.dirname(destination))
+        known_hash = None
+    else:
+        known_hash = file_hash(destination)
+    data_path = retrieve(
+        url, known_hash, fname=osp.basename(url), path=osp.dirname(destination)
+    )
+    return data_path

braindecode/datasets/bids.py

@@ -0,0 +1,245 @@
+"""Dataset for loading BIDS.
+
+More information on BIDS (Brain Imaging Data Structure) can be found at https://bids.neuroimaging.io
+"""
+
+# Authors: Pierre Guetschel <pierre.guetschel@gmail.com>
+#
+# License: BSD (3-clause)
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import mne
+import mne_bids
+import numpy as np
+import pandas as pd
+from joblib import Parallel, delayed
+
+from .base import BaseConcatDataset, BaseDataset, WindowsDataset
+
+
+def _description_from_bids_path(bids_path: mne_bids.BIDSPath) -> dict[str, Any]:
+    return {
+        "path": bids_path.fpath,
+        "subject": bids_path.subject,
+        "session": bids_path.session,
+        "task": bids_path.task,
+        "acquisition": bids_path.acquisition,
+        "run": bids_path.run,
+        "processing": bids_path.processing,
+        "recording": bids_path.recording,
+        "space": bids_path.space,
+        "split": bids_path.split,
+        "description": bids_path.description,
+        "suffix": bids_path.suffix,
+        "extension": bids_path.extension,
+        "datatype": bids_path.datatype,
+    }
+
+
+@dataclass
+class BIDSDataset(BaseConcatDataset):
+    """Dataset for loading BIDS.
+
+    This class has the same parameters as the :func:`mne_bids.find_matching_paths` function
+    as it will be used to find the files to load. The default ``extensions`` parameter was changed.
+
+    More information on BIDS (Brain Imaging Data Structure)
+    can be found at https://bids.neuroimaging.io
+
+    .. Note::
+        For loading "unofficial" BIDS datasets containing epoched data,
+        you can use :class:`BIDSEpochsDataset`.
+
+    Parameters
+    ----------
+    root : pathlib.Path | str
+        The root of the BIDS path.
+    subjects : str | array-like of str | None
+        The subject ID. Corresponds to "sub".
+    sessions : str | array-like of str | None
+        The acquisition session. Corresponds to "ses".
+    tasks : str | array-like of str | None
+        The experimental task. Corresponds to "task".
+    acquisitions: str | array-like of str | None
+        The acquisition parameters. Corresponds to "acq".
+    runs : str | array-like of str | None
+        The run number. Corresponds to "run".
+    processings : str | array-like of str | None
+        The processing label. Corresponds to "proc".
+    recordings : str | array-like of str | None
+        The recording name. Corresponds to "rec".
+    spaces : str | array-like of str | None
+        The coordinate space for anatomical and sensor location
+        files (e.g., ``*_electrodes.tsv``, ``*_markers.mrk``).
+        Corresponds to "space".
+        Note that valid values for ``space`` must come from a list
+        of BIDS keywords as described in the BIDS specification.
+    splits : str | array-like of str | None
+        The split of the continuous recording file for ``.fif`` data.
+        Corresponds to "split".
+    descriptions : str | array-like of str | None
+        This corresponds to the BIDS entity ``desc``. It is used to provide
+        additional information for derivative data, e.g., preprocessed data
+        may be assigned ``description='cleaned'``.
+    suffixes : str | array-like of str | None
+        The filename suffix. This is the entity after the
+        last ``_`` before the extension. E.g., ``'channels'``.
+        The following filename suffix's are accepted:
+        'meg', 'markers', 'eeg', 'ieeg', 'T1w',
+        'participants', 'scans', 'electrodes', 'coordsystem',
+        'channels', 'events', 'headshape', 'digitizer',
+        'beh', 'physio', 'stim'
+    extensions : str | array-like of str | None
+        The extension of the filename. E.g., ``'.json'``.
+        By default, uses the ones accepted by :func:`mne_bids.read_raw_bids`.
+    datatypes : str | array-like of str | None
+        The BIDS data type, e.g., ``'anat'``, ``'func'``, ``'eeg'``, ``'meg'``,
+        ``'ieeg'``.
+    check : bool
+        If ``True``, only returns paths that conform to BIDS. If ``False``
+        (default), the ``.check`` attribute of the returned
+        :class:`mne_bids.BIDSPath` object will be set to ``True`` for paths that
+        do conform to BIDS, and to ``False`` for those that don't.
+    preload : bool
+        If True, preload the data. Defaults to False.
+    n_jobs : int
+        Number of jobs to run in parallel. Defaults to 1.
+    """
+
+    root: Path | str
+    subjects: str | list[str] | None = None
+    sessions: str | list[str] | None = None
+    tasks: str | list[str] | None = None
+    acquisitions: str | list[str] | None = None
+    runs: str | list[str] | None = None
+    processings: str | list[str] | None = None
+    recordings: str | list[str] | None = None
+    spaces: str | list[str] | None = None
+    splits: str | list[str] | None = None
+    descriptions: str | list[str] | None = None
+    suffixes: str | list[str] | None = None
+    extensions: str | list[str] | None = field(
+        default_factory=lambda: [
+            ".con",
+            ".sqd",
+            ".pdf",
+            ".fif",
+            ".ds",
+            ".vhdr",
+            ".set",
+            ".edf",
+            ".bdf",
+            ".EDF",
+            ".snirf",
+            ".cdt",
+            ".mef",
+            ".nwb",
+        ]
+    )
+    datatypes: str | list[str] | None = None
+    check: bool = False
+    preload: bool = False
+    n_jobs: int = 1
+
+    @property
+    def _filter_out_epochs(self):
+        return True
+
+    def __post_init__(self):
+        bids_paths = mne_bids.find_matching_paths(
+            root=self.root,
+            subjects=self.subjects,
+            sessions=self.sessions,
+            tasks=self.tasks,
+            acquisitions=self.acquisitions,
+            runs=self.runs,
+            processings=self.processings,
+            recordings=self.recordings,
+            spaces=self.spaces,
+            splits=self.splits,
+            descriptions=self.descriptions,
+            suffixes=self.suffixes,
+            extensions=self.extensions,
+            datatypes=self.datatypes,
+            check=self.check,
+        )
+        # Filter out .json files files:
+        # (argument ignore_json only available in mne-bids>=0.16)
+        bids_paths = [
+            bids_path for bids_path in bids_paths if bids_path.extension != ".json"
+        ]
+        # Filter out _epo.fif files:
+        if self._filter_out_epochs:
+            bids_paths = [
+                bids_path
+                for bids_path in bids_paths
+                if not (bids_path.suffix == "epo" and bids_path.extension == ".fif")
+            ]
+
+        all_base_ds = Parallel(n_jobs=self.n_jobs)(
+            delayed(self._get_dataset)(bids_path) for bids_path in bids_paths
+        )
+        super().__init__(all_base_ds)
+
+    def _get_dataset(self, bids_path: mne_bids.BIDSPath) -> BaseDataset:
+        description = _description_from_bids_path(bids_path)
+        raw = mne_bids.read_raw_bids(bids_path, verbose=False)
+        if self.preload:
+            raw.load_data()
+        return BaseDataset(raw, description)
+
+
+class BIDSEpochsDataset(BIDSDataset):
+    """**Experimental** dataset for loading :class:`mne.Epochs` organised in BIDS.
+
+    The files must end with ``_epo.fif``.
+
+    .. Warning::
+        Epoched data is not officially supported in BIDS.
+
+    .. Note::
+        **Parameters:** This class has the same parameters as :class:`BIDSDataset` except
+        for arguments ``datatypes``, ``extensions`` and ``check`` which are fixed.
+    """
+
+    @property
+    def _filter_out_epochs(self):
+        return False
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(
+            *args,
+            extensions=".fif",
+            suffixes="epo",
+            check=False,
+            **kwargs,
+        )
+
+    def _set_metadata(self, epochs: mne.BaseEpochs) -> None:
+        # events = mne.events_from_annotations(epochs
+        n_times = epochs.times.shape[0]
+        # id_event = {v: k for k, v in epochs.event_id.items()}
+        annotations = epochs.annotations
+        if annotations is not None:
+            target = annotations.description
+        else:
+            id_events = {v: k for k, v in epochs.event_id.items()}
+            target = [id_events[event_id] for event_id in epochs.events[:, -1]]
+        metadata_dict = {
+            "i_window_in_trial": np.zeros(len(epochs)),
+            "i_start_in_trial": np.zeros(len(epochs)),
+            "i_stop_in_trial": np.zeros(len(epochs)) + n_times,
+            "target": target,
+        }
+        epochs.metadata = pd.DataFrame(metadata_dict)
+
+    def _get_dataset(self, bids_path):
+        description = _description_from_bids_path(bids_path)
+        epochs = mne.read_epochs(bids_path.fpath)
+        self._set_metadata(epochs)
+        return WindowsDataset(epochs, description=description, targets_from="metadata")

braindecode/datasets/mne.py

@@ -0,0 +1,172 @@
+# Authors: Lukas Gemein <l.gemein@gmail.com>
+#          Robin Schirrmeister <robintibor@gmail.com>
+#
+# License: BSD (3-clause)
+
+from __future__ import annotations
+
+import mne
+import numpy as np
+import pandas as pd
+
+from .base import BaseConcatDataset, BaseDataset, WindowsDataset
+
+
+def create_from_mne_raw(
+    raws: list[mne.io.BaseRaw],
+    trial_start_offset_samples: int,
+    trial_stop_offset_samples: int,
+    window_size_samples: int,
+    window_stride_samples: int,
+    drop_last_window: bool,
+    descriptions: list[dict | pd.Series] | None = None,
+    mapping: dict[str, int] | None = None,
+    preload: bool = False,
+    drop_bad_windows: bool = True,
+    accepted_bads_ratio: float = 0.0,
+) -> BaseConcatDataset:
+    """Create WindowsDatasets from mne.RawArrays
+
+    Parameters
+    ----------
+    raws: array-like
+        list of mne.RawArrays
+    trial_start_offset_samples: int
+        start offset from original trial onsets in samples
+    trial_stop_offset_samples: int
+        stop offset from original trial stop in samples
+    window_size_samples: int
+        window size
+    window_stride_samples: int
+        stride between windows
+    drop_last_window: bool
+        whether or not have a last overlapping window, when
+        windows do not equally divide the continuous signal
+    descriptions: array-like
+        list of dicts or pandas.Series with additional information about the raws
+    mapping: dict(str: int)
+        mapping from event description to target value
+    preload: bool
+        if True, preload the data of the Epochs objects.
+    drop_bad_windows: bool
+        If True, call `.drop_bad()` on the resulting mne.Epochs object. This
+        step allows identifying e.g., windows that fall outside of the
+        continuous recording. It is suggested to run this step here as otherwise
+        the BaseConcatDataset has to be updated as well.
+    accepted_bads_ratio: float, optional
+        Acceptable proportion of trials withinconsistent length in a raw. If
+        the number of trials whose length is exceeded by the window size is
+        smaller than this, then only the corresponding trials are dropped, but
+        the computation continues. Otherwise, an error is raised. Defaults to
+        0.0 (raise an error).
+
+    Returns
+    -------
+    windows_datasets: BaseConcatDataset
+        X and y transformed to a dataset format that is compatible with skorch
+        and braindecode
+    """
+    # Prevent circular import
+    from ..preprocessing.windowers import create_windows_from_events
+
+    if descriptions is not None:
+        if len(descriptions) != len(raws):
+            raise ValueError(
+                f"length of 'raws' ({len(raws)}) and 'description' "
+                f"({len(descriptions)}) has to match"
+            )
+        base_datasets = [
+            BaseDataset(raw, desc) for raw, desc in zip(raws, descriptions)
+        ]
+    else:
+        base_datasets = [BaseDataset(raw) for raw in raws]
+
+    base_datasets = BaseConcatDataset(base_datasets)
+    windows_datasets = create_windows_from_events(
+        base_datasets,
+        trial_start_offset_samples=trial_start_offset_samples,
+        trial_stop_offset_samples=trial_stop_offset_samples,
+        window_size_samples=window_size_samples,
+        window_stride_samples=window_stride_samples,
+        drop_last_window=drop_last_window,
+        mapping=mapping,
+        drop_bad_windows=drop_bad_windows,
+        preload=preload,
+        accepted_bads_ratio=accepted_bads_ratio,
+    )
+    return windows_datasets
+
+
+def create_from_mne_epochs(
+    list_of_epochs: list[mne.BaseEpochs],
+    window_size_samples: int,
+    window_stride_samples: int,
+    drop_last_window: bool,
+) -> BaseConcatDataset:
+    """Create WindowsDatasets from mne.Epochs
+
+    Parameters
+    ----------
+    list_of_epochs: array-like
+        list of mne.Epochs
+    window_size_samples: int
+        window size
+    window_stride_samples: int
+        stride between windows
+    drop_last_window: bool
+        whether or not have a last overlapping window, when
+        windows do not equally divide the continuous signal
+
+    Returns
+    -------
+    windows_datasets: BaseConcatDataset
+        X and y transformed to a dataset format that is compatible with skorch
+        and braindecode
+    """
+    # Prevent circular import
+    from ..preprocessing.windowers import _check_windowing_arguments
+
+    _check_windowing_arguments(0, 0, window_size_samples, window_stride_samples)
+
+    list_of_windows_ds = []
+    for epochs in list_of_epochs:
+        event_descriptions = epochs.events[:, 2]
+        original_trial_starts = epochs.events[:, 0]
+        stop = len(epochs.times) - window_size_samples
+
+        # already includes last incomplete window start
+        starts = np.arange(0, stop + 1, window_stride_samples)
+
+        if not drop_last_window and starts[-1] < stop:
+            # if last window does not end at trial stop, make it stop there
+            starts = np.append(starts, stop)
+
+        fake_events = [[start, window_size_samples, -1] for start in starts]
+
+        for trial_i, trial in enumerate(epochs):
+            metadata = pd.DataFrame(
+                {
+                    "i_window_in_trial": np.arange(len(fake_events)),
+                    "i_start_in_trial": starts + original_trial_starts[trial_i],
+                    "i_stop_in_trial": starts
+                    + original_trial_starts[trial_i]
+                    + window_size_samples,
+                    "target": len(fake_events) * [event_descriptions[trial_i]],
+                }
+            )
+            # window size - 1, since tmax is inclusive
+            mne_epochs = mne.Epochs(
+                mne.io.RawArray(trial, epochs.info),
+                fake_events,
+                baseline=None,
+                tmin=0,
+                tmax=(window_size_samples - 1) / epochs.info["sfreq"],
+                metadata=metadata,
+            )
+
+            mne_epochs.drop_bad(reject=None, flat=None)
+
+            windows_ds = WindowsDataset(mne_epochs)
+            list_of_windows_ds.append(windows_ds)
+
+    return BaseConcatDataset(list_of_windows_ds)