braindecode 1.3.0.dev177069446__py3-none-any.whl → 1.3.0.dev177628147__py3-none-any.whl

braindecode/datasets/{bids/hub_validation.py → hub_validation.py}

@@ -1,4 +1,3 @@
-# mypy: ignore-errors
 """
 Shared validation utilities for Hub format operations.
 
@@ -11,7 +10,7 @@ This module provides validation functions used by hub.py to avoid code duplicati
 
 from typing import Any, List, Tuple
 
-from ..registry import get_dataset_type
+from .registry import get_dataset_type
 
 
 def validate_dataset_uniformity(

braindecode/datasets/mne.py

@@ -25,35 +25,35 @@ def create_from_mne_raw(
     drop_bad_windows: bool = True,
     accepted_bads_ratio: float = 0.0,
 ) -> BaseConcatDataset:
-    """Create WindowsDatasets from mne.RawArrays.
+    """Create WindowsDatasets from mne.RawArrays
 
     Parameters
     ----------
-    raws : array-like
+    raws: array-like
         list of mne.RawArrays
-    trial_start_offset_samples : int
+    trial_start_offset_samples: int
         start offset from original trial onsets in samples
-    trial_stop_offset_samples : int
+    trial_stop_offset_samples: int
         stop offset from original trial stop in samples
-    window_size_samples : int
+    window_size_samples: int
         window size
-    window_stride_samples : int
+    window_stride_samples: int
         stride between windows
-    drop_last_window : bool
+    drop_last_window: bool
         whether or not have a last overlapping window, when
         windows do not equally divide the continuous signal
-    descriptions : array-like
+    descriptions: array-like
         list of dicts or pandas.Series with additional information about the raws
-    mapping : dict(str: int)
+    mapping: dict(str: int)
         mapping from event description to target value
-    preload : bool
+    preload: bool
         if True, preload the data of the Epochs objects.
-    drop_bad_windows : bool
+    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
+    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
@@ -62,7 +62,7 @@ def create_from_mne_raw(
 
     Returns
     -------
-    windows_datasets : BaseConcatDataset
+    windows_datasets: BaseConcatDataset
         X and y transformed to a dataset format that is compatible with skorch
         and braindecode
     """
@@ -101,23 +101,23 @@ def create_from_mne_epochs(
     window_stride_samples: int,
     drop_last_window: bool,
 ) -> BaseConcatDataset:
-    """Create WindowsDatasets from mne.Epochs.
+    """Create WindowsDatasets from mne.Epochs
 
     Parameters
     ----------
-    list_of_epochs : array-like
+    list_of_epochs: array-like
         list of mne.Epochs
-    window_size_samples : int
+    window_size_samples: int
         window size
-    window_stride_samples : int
+    window_stride_samples: int
         stride between windows
-    drop_last_window : bool
+    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
+    windows_datasets: BaseConcatDataset
         X and y transformed to a dataset format that is compatible with skorch
         and braindecode
     """

braindecode/datasets/moabb.py

@@ -90,14 +90,14 @@ def fetch_data_with_moabb(
 
     Parameters
     ----------
-    dataset_name : str | moabb.datasets.base.BaseDataset
+    dataset_name: str | moabb.datasets.base.BaseDataset
         the name of a dataset included in moabb
-    subject_ids : list(int) | int
+    subject_ids: list(int) | int
         (list of) int of subject(s) to be fetched
-    dataset_kwargs : dict, optional
+    dataset_kwargs: dict, optional
         optional dictionary containing keyword arguments
         to pass to the moabb dataset when instantiating it.
-    data_load_kwargs : dict, optional
+    data_load_kwargs: dict, optional
         optional dictionary containing keyword arguments
         to pass to the moabb dataset's load_data method.
         Allows using the moabb cache_config=None and
@@ -105,8 +105,8 @@ def fetch_data_with_moabb(
 
     Returns
     -------
-    raws : mne.Raw
-    info : pandas.DataFrame
+    raws: mne.Raw
+    info: pandas.DataFrame
     """
     if isinstance(dataset_name, str):
         dataset = _find_dataset_in_moabb(dataset_name, dataset_kwargs)
@@ -127,15 +127,15 @@ class MOABBDataset(BaseConcatDataset):
 
     Parameters
     ----------
-    dataset_name : str
+    dataset_name: str
         name of dataset included in moabb to be fetched
-    subject_ids : list(int) | int | None
+    subject_ids: list(int) | int | None
         (list of) int of subject(s) to be fetched. If None, data of all
         subjects is fetched.
-    dataset_kwargs : dict, optional
+    dataset_kwargs: dict, optional
         optional dictionary containing keyword arguments
         to pass to the moabb dataset when instantiating it.
-    dataset_load_kwargs : dict, optional
+    dataset_load_kwargs: dict, optional
         optional dictionary containing keyword arguments
         to pass to the moabb dataset's load_data method.
         Allows using the moabb cache_config=None and

braindecode/datasets/nmt.py

@@ -9,6 +9,7 @@ Note:
     - The signal unit may not be uV and further examination is required.
     - The spectrum shows that the signal may have been band-pass filtered from about 2 - 33Hz,
     which needs to be further determined.
+
 """
 
 # Authors: Mohammad Bayazi <mj.darvishi92@gmail.com>
@@ -31,7 +32,6 @@ from joblib import Parallel, delayed
 from mne.datasets import fetch_dataset
 
 from braindecode.datasets.base import BaseConcatDataset, RawDataset
-from braindecode.datasets.utils import _correct_dataset_path
 
 NMT_URL = "https://zenodo.org/record/10909103/files/NMT.zip"
 NMT_archive_name = "NMT.zip"
@@ -66,17 +66,17 @@ class NMT(BaseConcatDataset):
 
     Parameters
     ----------
-    path : str
+    path: str
         Parent directory of the dataset.
-    recording_ids : list(int) | int
+    recording_ids: list(int) | int
         A (list of) int of recording id(s) to be read (order matters and will
         overwrite default chronological order, e.g. if recording_ids=[1,0],
         then the first recording returned by this class will be chronologically
         later than the second recording. Provide recording_ids in ascending
         order to preserve chronological order.).
-    target_name : str
+    target_name: str
         Can be "pathological", "gender", or "age".
-    preload : bool
+    preload: bool
         If True, preload the data of the Raw objects.
 
     References
@@ -96,34 +96,22 @@ class NMT(BaseConcatDataset):
         preload=False,
         n_jobs=1,
     ):
-        # Convert empty string to None for consistency
-        if path == "":
-            path = None
+        # correct the path if needed
+        if path is not None:
+            list_csv = glob.glob(f"{path}/**/Labels.csv", recursive=True)
+            if isinstance(list_csv, list) and len(list_csv) > 0:
+                path = Path(list_csv[0]).parent
 
-        # Download dataset if not present
-        if path is None:
+        if path is None or len(list_csv) == 0:
             path = fetch_dataset(
                 dataset_params=NMT_dataset_params,
-                path=None,
+                path=Path(path) if path is not None else None,
                 processor="unzip",
                 force_update=False,
             )
             # First time we fetch the dataset, we need to move the files to the
             # correct directory.
-            path = _correct_dataset_path(
-                path, NMT_archive_name, "nmt_scalp_eeg_dataset"
-            )
-        else:
-            # Validate that the provided path is a valid NMT dataset
-            if not Path(f"{path}/Labels.csv").exists():
-                raise ValueError(
-                    f"The provided path {path} does not contain a valid "
-                    "NMT dataset (missing Labels.csv). Please ensure the "
-                    "path points directly to the NMT dataset directory."
-                )
-            path = _correct_dataset_path(
-                path, NMT_archive_name, "nmt_scalp_eeg_dataset"
-            )
+            path = _correct_path(path)
 
         # Get all file paths
         file_paths = glob.glob(
@@ -149,10 +137,7 @@ class NMT(BaseConcatDataset):
             os.path.join(path, "Labels.csv"), index_col="recordname"
         )
         if recording_ids is not None:
-            # Match metadata by record name instead of position to fix alignment bug
-            # when CSV order differs from sorted file order
-            selected_recordnames = [os.path.basename(fp) for fp in file_paths]
-            description = description.loc[selected_recordnames]
+            description = description.iloc[recording_ids]
         description.replace(
             {
                 "not specified": "X",
@@ -191,6 +176,39 @@ class NMT(BaseConcatDataset):
         return base_dataset
 
 
+def _correct_path(path: str):
+    """
+    Check if the path is correct and rename the file if needed.
+
+    Parameters
+    ----------
+    path: basestring
+        Path to the file.
+
+    Returns
+    -------
+    path: basestring
+        Corrected path.
+    """
+    if not Path(path).exists():
+        unzip_file_name = f"{NMT_archive_name}.unzip"
+        if (Path(path).parent / unzip_file_name).exists():
+            try:
+                os.rename(
+                    src=Path(path).parent / unzip_file_name,
+                    dst=Path(path),
+                )
+
+            except PermissionError:
+                raise PermissionError(
+                    f"Please rename {Path(path).parent / unzip_file_name}"
+                    + f"manually to {path} and try again."
+                )
+        path = os.path.join(path, "nmt_scalp_eeg_dataset")
+
+    return path
+
+
 def _get_header(*args):
     all_paths = {**_NMT_PATHS}
     return all_paths[args[0]]
@@ -198,24 +216,19 @@ def _get_header(*args):
 
 def _fake_pd_read_csv(*args, **kwargs):
     # Create a list of lists to hold the data
-    # Updated to match the file IDs from _NMT_PATHS (0000036-0000042)
-    # to align with the mocked glob.glob return value
     data = [
-        ["0000036.edf", "normal", 35, "male", "train"],
-        ["0000037.edf", "abnormal", 28, "female", "test"],
-        ["0000038.edf", "normal", 62, "male", "train"],
-        ["0000039.edf", "abnormal", 41, "female", "test"],
-        ["0000040.edf", "normal", 19, "male", "train"],
-        ["0000041.edf", "abnormal", 55, "female", "test"],
-        ["0000042.edf", "normal", 71, "male", "train"],
+        ["0000001.edf", "normal", 35, "male", "train"],
+        ["0000002.edf", "abnormal", 28, "female", "test"],
+        ["0000003.edf", "normal", 62, "male", "train"],
+        ["0000004.edf", "abnormal", 41, "female", "test"],
+        ["0000005.edf", "normal", 19, "male", "train"],
+        ["0000006.edf", "abnormal", 55, "female", "test"],
+        ["0000007.edf", "normal", 71, "male", "train"],
     ]
 
     # Create the DataFrame, specifying column names
     df = pd.DataFrame(data, columns=["recordname", "label", "age", "gender", "loc"])
 
-    # Set recordname as index to match the real pd.read_csv behavior with index_col="recordname"
-    df.set_index("recordname", inplace=True)
-
     return df
 
 
@@ -275,33 +288,18 @@ _NMT_PATHS = {
 class _NMTMock(NMT):
     """Mocked class for testing and examples."""
 
-    @mock.patch("pathlib.Path.exists", return_value=True)
-    @mock.patch("braindecode.datasets.nmt._correct_dataset_path")
-    @mock.patch("mne.datasets.fetch_dataset")
-    @mock.patch("pandas.read_csv", new=_fake_pd_read_csv)
-    @mock.patch("mne.io.read_raw_edf", new=_fake_raw)
     @mock.patch("glob.glob", return_value=_NMT_PATHS.keys())
+    @mock.patch("mne.io.read_raw_edf", new=_fake_raw)
+    @mock.patch("pandas.read_csv", new=_fake_pd_read_csv)
     def __init__(
         self,
         mock_glob,
-        mock_fetch,
-        mock_correct_path,
-        mock_path_exists,
         path,
         recording_ids=None,
         target_name="pathological",
         preload=False,
         n_jobs=1,
     ):
-        # Prevent download by providing a dummy path if empty/None
-        if not path:
-            path = "mocked_nmt_path"
-
-        # Mock fetch_dataset to return a valid path without downloading
-        mock_fetch.return_value = path
-        # Mock _correct_dataset_path to return the path as-is
-        mock_correct_path.side_effect = lambda p, *args, **kwargs: p
-
         with warnings.catch_warnings():
             warnings.filterwarnings("ignore", message="Cannot save date file")
             super().__init__(

braindecode/datasets/sleep_physio_challe_18.py

@@ -1,4 +1,6 @@
-"""PhysioNet Challenge 2018 dataset."""
+"""
+PhysioNet Challenge 2018 dataset.
+"""
 
 # Authors: Hubert Banville <hubert.jbanville@gmail.com>
 #          Bruno Aristimunha <b.aristimunha@gmail.com>
@@ -251,7 +253,7 @@ class SleepPhysionetChallenge2018(BaseConcatDataset):
 
     Parameters
     ----------
-    subject_ids : list(int) | str | None
+    subject_ids: list(int) | str | None
         (list of) int of subject(s) to be loaded.
         - If `None`, loads all subjects (both training and test sets [no label associated]).
         - If `"training"`, loads only the training set subjects.
@@ -263,7 +265,7 @@ class SleepPhysionetChallenge2018(BaseConcatDataset):
         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.
-    load_eeg_only : bool
+    load_eeg_only: bool
         If True, only load the EEG channels and discard the others (EOG, EMG,
         temperature, respiration) to avoid resampling the other signals.
     preproc : list(Preprocessor) | None

braindecode/datasets/sleep_physionet.py

@@ -25,18 +25,18 @@ class SleepPhysionet(BaseConcatDataset):
 
     Parameters
     ----------
-    subject_ids : list(int) | int | None
+    subject_ids: list(int) | int | None
         (list of) int of subject(s) to be loaded. If None, load all available
         subjects.
-    recording_ids : list(int) | None
+    recording_ids: list(int) | None
         Recordings to load per subject (each subject except 13 has two
         recordings). Can be [1], [2] or [1, 2] (same as None).
-    preload : bool
+    preload: bool
         If True, preload the data of the Raw objects.
-    load_eeg_only : bool
+    load_eeg_only: bool
         If True, only load the EEG channels and discard the others (EOG, EMG,
         temperature, respiration) to avoid resampling the other signals.
-    crop_wake_mins : float
+    crop_wake_mins: float
         Number of minutes of wake time to keep before the first sleep event
         and after the last sleep event. Used to reduce the imbalance in this
         dataset. Default of 30 mins.

braindecode/datasets/tuh.py

@@ -1,6 +1,5 @@
 """
-Dataset classes for the Temple University Hospital (TUH) EEG Corpus and the.
-
+Dataset classes for the Temple University Hospital (TUH) EEG Corpus and the
 TUH Abnormal EEG Corpus.
 """
 
@@ -27,32 +26,31 @@ from .base import BaseConcatDataset, RawDataset
 
 
 class TUH(BaseConcatDataset):
-    """Temple University Hospital (TUH) EEG Corpus.
-
+    """Temple University Hospital (TUH) EEG Corpus
     (www.isip.piconepress.com/projects/tuh_eeg/html/downloads.shtml#c_tueg).
 
     Parameters
     ----------
-    path : str
+    path: str
         Parent directory of the dataset.
-    recording_ids : list(int) | int
+    recording_ids: list(int) | int
         A (list of) int of recording id(s) to be read (order matters and will
         overwrite default chronological order, e.g. if recording_ids=[1,0],
         then the first recording returned by this class will be chronologically
         later then the second recording. Provide recording_ids in ascending
         order to preserve chronological order.).
-    target_name : str
+    target_name: str
         Can be 'gender', or 'age'.
-    preload : bool
+    preload: bool
         If True, preload the data of the Raw objects.
-    add_physician_reports : bool
+    add_physician_reports: bool
         If True, the physician reports will be read from disk and added to the
         description.
-    rename_channels : bool
+    rename_channels: bool
         If True, rename the EEG channels to the standard 10-05 system.
-    set_montage : bool
+    set_montage: bool
         If True, set the montage to the standard 10-05 system.
-    n_jobs : int
+    n_jobs: int
         Number of jobs to be used to read files in parallel.
     """
 
@@ -381,31 +379,30 @@ def _parse_age_and_gender_from_edf_header(file_path):
 
 class TUHAbnormal(TUH):
     """Temple University Hospital (TUH) Abnormal EEG Corpus.
-
     see www.isip.piconepress.com/projects/tuh_eeg/html/downloads.shtml#c_tuab
 
     Parameters
     ----------
-    path : str
+    path: str
         Parent directory of the dataset.
-    recording_ids : list(int) | int
+    recording_ids: list(int) | int
         A (list of) int of recording id(s) to be read (order matters and will
         overwrite default chronological order, e.g. if recording_ids=[1,0],
         then the first recording returned by this class will be chronologically
         later then the second recording. Provide recording_ids in ascending
         order to preserve chronological order.).
-    target_name : str
+    target_name: str
         Can be 'pathological', 'gender', or 'age'.
-    preload : bool
+    preload: bool
         If True, preload the data of the Raw objects.
-    add_physician_reports : bool
+    add_physician_reports: bool
         If True, the physician reports will be read from disk and added to the
         description.
-    rename_channels : bool
+    rename_channels: bool
         If True, rename the EEG channels to the standard 10-05 system.
-    set_montage : bool
+    set_montage: bool
         If True, set the montage to the standard 10-05 system.
-    n_jobs : int
+    n_jobs: int
         Number of jobs to be used to read files in parallel.
     """
 

braindecode/datasets/xy.py

@@ -26,32 +26,31 @@ def create_from_X_y(
     window_size_samples: int | None = None,
     window_stride_samples: int | None = None,
 ) -> BaseConcatDataset:
-    """Create a BaseConcatDataset of WindowsDatasets from X and y to be used for.
-
+    """Create a BaseConcatDataset of WindowsDatasets from X and y to be used for
     decoding with skorch and braindecode, where X is a list of pre-cut trials
     and y are corresponding targets.
 
     Parameters
     ----------
-    X : array-like
+    X: array-like
         list of pre-cut trials as n_trials x n_channels x n_times
-    y : array-like
+    y: array-like
         targets corresponding to the trials
-    drop_last_window : bool
+    drop_last_window: bool
         whether or not have a last overlapping window, when
         windows/windows do not equally divide the continuous signal
-    sfreq : float
+    sfreq: float
         Sampling frequency of signals.
-    ch_names : array-like
+    ch_names: array-like
         Names of the channels.
-    window_size_samples : int
+    window_size_samples: int
         window size
-    window_stride_samples : int
+    window_stride_samples: int
         stride between windows
 
     Returns
     -------
-    windows_datasets : BaseConcatDataset
+    windows_datasets: BaseConcatDataset
         X and y transformed to a dataset format that is compatible with skorch
         and braindecode
     """

braindecode/datautil/__init__.py

@@ -1,4 +1,6 @@
-"""Utilities for data manipulation."""
+"""
+Utilities for data manipulation.
+"""
 
 from .channel_utils import (
     division_channels_idx,
@@ -9,7 +11,6 @@ from .serialization import (
     load_concat_dataset,
     save_concat_dataset,
 )
-from .util import infer_signal_properties
 
 
 def __getattr__(name):
@@ -58,5 +59,4 @@ __all__ = [
     "_check_save_dir_empty",
     "match_hemisphere_chans",
     "division_channels_idx",
-    "infer_signal_properties",
 ]

braindecode/datautil/serialization.py

@@ -1,4 +1,6 @@
-"""Convenience functions for storing and loading of windows datasets."""
+"""
+Convenience functions for storing and loading of windows datasets.
+"""
 
 # Authors: Lukas Gemein <l.gemein@gmail.com>
 #
@@ -33,25 +35,24 @@ def save_concat_dataset(path, concat_dataset, overwrite=False):
 
 
 def _outdated_load_concat_dataset(path, preload, ids_to_load=None, target_name=None):
-    """Load a stored BaseConcatDataset from.
-
+    """Load a stored BaseConcatDataset from
     files.
 
     Parameters
     ----------
-    path : pathlib.Path
+    path: pathlib.Path
         Path to the directory of the .fif / -epo.fif and .json files.
-    preload : bool
+    preload: bool
         Whether to preload the data.
-    ids_to_load : None | list(int)
+    ids_to_load: None | list(int)
         Ids of specific files to load.
-    target_name : None or str
+    target_name: None or str
         Load specific description column as target. If not given, take saved
         target name.
 
     Returns
     -------
-    concat_dataset : BaseConcatDataset
+    concat_dataset: BaseConcatDataset
     """
     # assume we have a single concat dataset to load
     is_raw = (path / "0-raw.fif").is_file()
@@ -137,7 +138,7 @@ def _load_signals(fif_file, preload, is_raw):
         with open(pkl_file, "rb") as f:
             signals = pickle.load(f)
 
-        if all(Path(f).exists() for f in signals.filenames):
+        if all(f.exists() for f in signals.filenames):
             if preload:
                 signals.load_data()
             return signals
@@ -174,27 +175,26 @@ def _load_signals(fif_file, preload, is_raw):
 
 
 def load_concat_dataset(path, preload, ids_to_load=None, target_name=None, n_jobs=1):
-    """Load a stored BaseConcatDataset from.
-
+    """Load a stored BaseConcatDataset from
     files.
 
     Parameters
     ----------
-    path : str | pathlib.Path
+    path: str | pathlib.Path
         Path to the directory of the .fif / -epo.fif and .json files.
-    preload : bool
+    preload: bool
         Whether to preload the data.
-    ids_to_load : list of int | None
+    ids_to_load: list of int | None
         Ids of specific files to load.
-    target_name : str | list | None
+    target_name: str | list | None
         Load specific description column as target. If not given, take saved
         target name.
-    n_jobs : int
+    n_jobs: int
         Number of jobs to be used to read files in parallel.
 
     Returns
     -------
-    concat_dataset : BaseConcatDataset
+    concat_dataset: BaseConcatDataset
     """
     # Make sure we always work with a pathlib.Path
     path = Path(path)
@@ -306,11 +306,9 @@ def _load_kwargs_json(kwargs_name, sub_dir):
 
 
 def _is_outdated_saved(path):
-    """Data was saved in the old way if there are 'description.json', '-raw.fif'.
-
+    """Data was saved in the old way if there are 'description.json', '-raw.fif'
     or '-epo.fif' in path (no subdirectories) OR if there are more 'fif' files
-    than 'description.json' files.
-    """
+    than 'description.json' files."""
     description_files = glob(os.path.join(path, "**/description.json"))
     fif_files = glob(os.path.join(path, "**/*-raw.fif")) + glob(
         os.path.join(path, "**/*-epo.fif")
@@ -344,7 +342,7 @@ def _check_save_dir_empty(save_dir):
         Directory under which a `BaseConcatDataset` will be saved.
 
     Raises
-    ------
+    -------
     FileExistsError
         If ``save_dir`` is not a valid directory for saving.
     """