braindecode 1.3.0.dev177069446__py3-none-any.whl

braindecode/datasets/bcicomp.py

@@ -0,0 +1,193 @@
+# 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, RawDataset
+
+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
+
+    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.
+
+    Notes
+    -----
+    When using this dataset please cite [1]_ .
+
+    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(RawDataset(raw_train, description=desc_train))
+            datasets.append(RawDataset(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/__init__.py

@@ -0,0 +1,54 @@
+# mypy: ignore-errors
+"""
+BIDS (Brain Imaging Data Structure) integration for braindecode.
+
+This subpackage provides:
+- BIDS dataset loading (BIDSDataset, BIDSEpochsDataset)
+- BIDS-like format utilities for Hub integration
+- Hugging Face Hub push/pull functionality
+- Validation utilities for Hub operations
+
+More information on BIDS can be found at https://bids.neuroimaging.io
+"""
+
+# Authors: Bruno Aristimunha <b.aristimunha@gmail.com>
+#          Pierre Guetschel <pierre.guetschel@gmail.com>
+#          Kuntal Kokate
+#
+# License: BSD (3-clause)
+
+from typing import TYPE_CHECKING
+
+# Only import hub at init level (needed by base.py)
+# Other imports are deferred to avoid circular imports
+from .hub import HubDatasetMixin
+
+# For static type checkers (mypy), provide explicit imports
+if TYPE_CHECKING:
+    from .datasets import BIDSDataset, BIDSEpochsDataset
+    from .iterable import BIDSIterableDataset
+
+
+def __getattr__(name: str):
+    """Lazy imports to avoid circular dependencies."""
+    if name in ("BIDSDataset", "BIDSEpochsDataset"):
+        from .datasets import BIDSDataset, BIDSEpochsDataset
+
+        return {"BIDSDataset": BIDSDataset, "BIDSEpochsDataset": BIDSEpochsDataset}[
+            name
+        ]
+    elif name == "BIDSIterableDataset":
+        from .iterable import BIDSIterableDataset
+
+        return BIDSIterableDataset
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    # Dataset classes
+    "BIDSDataset",
+    "BIDSEpochsDataset",
+    "BIDSIterableDataset",
+    # Hub integration
+    "HubDatasetMixin",
+]

braindecode/datasets/bids/datasets.py

@@ -0,0 +1,239 @@
+# mypy: ignore-errors
+"""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, RawDataset, WindowsDataset
+
+
+def _description_from_bids_path(bids_path: mne_bids.BIDSPath) -> dict[str, Any]:
+    description = {"path": bids_path.fpath, **bids_path.entities}
+    description.update(
+        {
+            "suffix": bids_path.suffix,
+            "extension": bids_path.extension,
+            "datatype": bids_path.datatype,
+        }
+    )
+    return description
+
+
+@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) -> RawDataset:
+        description = _description_from_bids_path(bids_path)
+        raw = mne_bids.read_raw_bids(bids_path, verbose=False)
+        if self.preload:
+            raw.load_data()
+        return RawDataset(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")