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

braindecode/datasets/bids/hub_io.py

@@ -1,197 +0,0 @@
-# mypy: ignore-errors
-"""
-Low-level Zarr I/O helpers for Hub integration.
-
-These functions keep the Zarr serialization details isolated from hub.py.
-"""
-
-from __future__ import annotations
-
-import json
-import warnings
-from pathlib import Path
-
-import numpy as np
-import pandas as pd
-from mne.utils import _soft_import
-
-zarr = _soft_import("zarr", purpose="hugging face integration", strict=False)
-
-
-def _sanitize_for_json(obj):
-    """Replace NaN/Inf with None for valid JSON."""
-    if isinstance(obj, float):
-        if np.isnan(obj) or np.isinf(obj):
-            return None
-        return obj
-    if isinstance(obj, dict):
-        return {k: _sanitize_for_json(v) for k, v in obj.items()}
-    if isinstance(obj, list):
-        return [_sanitize_for_json(v) for v in obj]
-    if isinstance(obj, np.ndarray):
-        return _sanitize_for_json(obj.tolist())
-    return obj
-
-
-def _restore_nan_from_json(obj):
-    """Restore NaN values from None in JSON-loaded data."""
-    if isinstance(obj, dict):
-        return {k: _restore_nan_from_json(v) for k, v in obj.items()}
-    if isinstance(obj, list):
-        if len(obj) > 0 and all(isinstance(x, (int, float, type(None))) for x in obj):
-            return [np.nan if x is None else x for x in obj]
-        return [_restore_nan_from_json(v) for v in obj]
-    return obj
-
-
-def _save_windows_to_zarr(
-    grp, data, metadata, description, info, compressor, target_name
-):
-    """Save windowed data to Zarr group (low-level function)."""
-    data_array = data.astype(np.float32)
-    compressors_list = [compressor] if compressor is not None else None
-
-    grp.create_array(
-        "data",
-        data=data_array,
-        chunks=(1, data_array.shape[1], data_array.shape[2]),
-        compressors=compressors_list,
-    )
-
-    store_path = getattr(grp.store, "path", getattr(grp.store, "root", None))
-    metadata_path = Path(store_path) / grp.path / "metadata.tsv"
-    metadata.to_csv(metadata_path, sep="\t", index=True)
-
-    grp.attrs["description"] = json.loads(description.to_json(date_format="iso"))
-    grp.attrs["info"] = _sanitize_for_json(info)
-
-    if target_name is not None:
-        grp.attrs["target_name"] = target_name
-
-
-def _save_eegwindows_to_zarr(
-    grp, raw, metadata, description, info, targets_from, last_target_only, compressor
-):
-    """Save EEG continuous raw data to Zarr group (low-level function)."""
-    continuous_data = raw.get_data()
-    continuous_float = continuous_data.astype(np.float32)
-    compressors_list = [compressor] if compressor is not None else None
-
-    grp.create_array(
-        "data",
-        data=continuous_float,
-        chunks=(continuous_float.shape[0], min(10000, continuous_float.shape[1])),
-        compressors=compressors_list,
-    )
-
-    store_path = getattr(grp.store, "path", getattr(grp.store, "root", None))
-    metadata_path = Path(store_path) / grp.path / "metadata.tsv"
-    metadata.to_csv(metadata_path, sep="\t", index=True)
-
-    grp.attrs["description"] = json.loads(description.to_json(date_format="iso"))
-    grp.attrs["info"] = _sanitize_for_json(info)
-    grp.attrs["targets_from"] = targets_from
-    grp.attrs["last_target_only"] = last_target_only
-
-
-def _load_windows_from_zarr(grp, preload):
-    """Load windowed data from Zarr group (low-level function)."""
-    store_path = getattr(grp.store, "path", getattr(grp.store, "root", None))
-    metadata_path = Path(store_path) / grp.path / "metadata.tsv"
-    metadata = pd.read_csv(metadata_path, sep="\t", index_col=0)
-
-    description = pd.Series(grp.attrs["description"])
-    info_dict = _restore_nan_from_json(grp.attrs["info"])
-
-    if preload:
-        data = grp["data"][:]
-    else:
-        data = grp["data"][:]
-        warnings.warn(
-            "Lazy loading from Zarr not fully implemented yet. "
-            "Loading all data into memory.",
-            UserWarning,
-        )
-
-    target_name = grp.attrs.get("target_name", None)
-
-    return data, metadata, description, info_dict, target_name
-
-
-def _load_eegwindows_from_zarr(grp, preload):
-    """Load EEG continuous raw data from Zarr group (low-level function)."""
-    store_path = getattr(grp.store, "path", getattr(grp.store, "root", None))
-    metadata_path = Path(store_path) / grp.path / "metadata.tsv"
-    metadata = pd.read_csv(metadata_path, sep="\t", index_col=0)
-
-    description = pd.Series(grp.attrs["description"])
-    info_dict = _restore_nan_from_json(grp.attrs["info"])
-
-    if preload:
-        data = grp["data"][:]
-    else:
-        data = grp["data"][:]
-        warnings.warn(
-            "Lazy loading from Zarr not fully implemented yet. "
-            "Loading all data into memory.",
-            UserWarning,
-        )
-
-    targets_from = grp.attrs.get("targets_from", "metadata")
-    last_target_only = grp.attrs.get("last_target_only", True)
-
-    return data, metadata, description, info_dict, targets_from, last_target_only
-
-
-def _save_raw_to_zarr(grp, raw, description, info, target_name, compressor):
-    """Save RawDataset continuous raw data to Zarr group (low-level function)."""
-    continuous_data = raw.get_data()
-    continuous_float = continuous_data.astype(np.float32)
-    compressors_list = [compressor] if compressor is not None else None
-
-    grp.create_array(
-        "data",
-        data=continuous_float,
-        chunks=(continuous_float.shape[0], min(10000, continuous_float.shape[1])),
-        compressors=compressors_list,
-    )
-
-    grp.attrs["description"] = json.loads(description.to_json(date_format="iso"))
-    grp.attrs["info"] = _sanitize_for_json(info)
-
-    if target_name is not None:
-        grp.attrs["target_name"] = target_name
-
-
-def _load_raw_from_zarr(grp, preload):
-    """Load RawDataset continuous raw data from Zarr group (low-level function)."""
-    description = pd.Series(grp.attrs["description"])
-    info_dict = _restore_nan_from_json(grp.attrs["info"])
-
-    if preload:
-        data = grp["data"][:]
-    else:
-        data = grp["data"][:]
-        warnings.warn(
-            "Lazy loading from Zarr not fully implemented yet. "
-            "Loading all data into memory.",
-            UserWarning,
-        )
-
-    target_name = grp.attrs.get("target_name", None)
-
-    return data, description, info_dict, target_name
-
-
-def _create_compressor(compression, compression_level):
-    """Create a Zarr v3 compressor codec."""
-    if zarr is False:
-        raise ImportError(
-            "Zarr is not installed. Install with: pip install braindecode[hub]"
-        )
-
-    if compression is None or compression not in ("blosc", "zstd", "gzip"):
-        return None
-
-    name = "zstd" if compression == "blosc" else compression
-    return {"name": name, "configuration": {"level": compression_level}}

braindecode/datasets/chb_mit.py

@@ -1,163 +0,0 @@
-"""
-This dataset is a BIDS-compatible version of the CHB-MIT Scalp EEG Database.
-
-It reorganizes the file structure to comply with the BIDS specification. To this effect:
-
-    The data from subject chb21 was moved to sub-01/ses-02.
-    Metadata was organized according to BIDS.
-    Data in the EEG edf files was modified to keep only the 18 channels from a double banana bipolar montage.
-    Annotations were formatted as BIDS-score compatible `tsv` files.
-"""
-
-# Authors: Dan, Jonathan
-#          Shoeb, Ali (Data collector)
-#          Bruno Aristimunha <b.aristimunha@gmail.com>
-#
-# License: BSD (3-clause)
-from __future__ import annotations
-
-from pathlib import Path
-
-from mne.datasets import fetch_dataset
-
-from braindecode.datasets import BIDSDataset
-from braindecode.datasets.utils import _correct_dataset_path
-
-CHB_MIT_URL = "https://zenodo.org/records/10259996/files/BIDS_CHB-MIT.zip"
-CHB_MIT_archive_name = "chb_mit_bids.zip"
-CHB_MIT_folder_name = "CHB-MIT-BIDS-eeg-dataset"
-CHB_MIT_dataset_name = "CHB-MIT-EEG-Corpus"
-
-CHB_MIT_dataset_params = {
-    "dataset_name": CHB_MIT_dataset_name,
-    "url": CHB_MIT_URL,
-    "archive_name": CHB_MIT_archive_name,
-    "folder_name": CHB_MIT_folder_name,
-    "hash": "078f4e110e40d10fef1a38a892571ad24666c488e8118a01002c9224909256ed",  # sha256
-    "config_key": CHB_MIT_dataset_name,
-}
-
-
-class CHBMIT(BIDSDataset):
-    """The Children's Hospital Boston EEG Dataset.
-
-    This database, collected at the Children's Hospital Boston, consists of EEG recordings
-    from pediatric subjects with intractable seizures. Subjects were monitored for up to
-    several days following withdrawal of anti-seizure medication in order to characterize
-    their seizures and assess their candidacy for surgical intervention.
-
-    **Description of the contents of the dataset:**
-
-    Each folder (sub-01, sub-01, etc.) contains between 9 and 42 continuous .edf
-    files from a single subject. Hardware limitations resulted in gaps between
-    consecutively-numbered .edf files, during which the signals were not recorded;
-    in most cases, the gaps are 10 seconds or less, but occasionally there are much
-    longer gaps. In order to protect the privacy of the subjects, all protected health
-    information (PHI) in the original .edf files has been replaced with surrogate information
-    in the files provided here. Dates in the original .edf files have been replaced by
-    surrogate dates, but the time relationships between the individual files belonging
-    to each case have been preserved. In most cases, the .edf files contain exactly one
-    hour of digitized EEG signals, although those belonging to case sub-10 are two hours
-    long, and those belonging to cases sub-04, sub-06, sub-07, sub-09, and sub-23 are
-    four hours long; occasionally, files in which seizures are recorded are shorter.
-
-    The EEG is recorded at 256 Hz with a 16-bit resolution. The recordings are
-    referenced in a double banana bipolar montage with 18 channels from the 10-20 electrode system.
-
-    This BIDS-compatible version of the dataset was published by Jonathan Dan :footcite:`Dan2025`
-    and is based on the original CHB MIT EEG Database :footcite:`Guttag2010`, :footcite:`Shoeb2009`.
-
-    .. versionadded:: 1.3
-
-    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.
-
-    References
-    ----------
-    .. footbibliography::
-    """
-
-    def __init__(self, root=None, *args, **kwargs):
-        # Download dataset if not present
-        if root is None:
-            path_root = fetch_dataset(
-                dataset_params=CHB_MIT_dataset_params,
-                path=None,
-                processor="unzip",
-                force_update=False,
-            )
-            # First time we fetch the dataset, we need to move the files to the
-            # correct directory.
-            path_root = _correct_dataset_path(
-                path_root, CHB_MIT_archive_name, "BIDS_CHB-MIT"
-            )
-        else:
-            # Validate that the provided root is a valid BIDS dataset
-            if not Path(f"{root}/participants.tsv").exists():
-                raise ValueError(
-                    f"The provided root directory {root} does not contain a valid "
-                    "BIDS dataset (missing participants.tsv). Please ensure the "
-                    "root points directly to the BIDS dataset directory."
-                )
-            path_root = root
-
-        kwargs["root"] = path_root
-
-        super().__init__(
-            *args,
-            extensions=".edf",
-            check=False,
-            **kwargs,
-        )

braindecode/datasets/siena.py

@@ -1,162 +0,0 @@
-"""
-This dataset is a BIDS compatible version of the Siena Scalp EEG Database.
-
-It reorganizes the file structure to comply with the BIDS specification. To this effect:
-
--   Metadata was organized according to BIDS.
--   Data in the EEG edf files was modified to keep only the 19 channels from a 10-20 EEG system.
--   Annotations were formatted as BIDS-score compatible tsv files.
-"""
-
-# Authors: Dan, Jonathan
-#          Detti, Paolo
-#          Bruno Aristimunha <b.aristimunha@gmail.com>
-#
-# License: BSD (3-clause)
-from __future__ import annotations
-
-from pathlib import Path
-
-from mne.datasets import fetch_dataset
-
-from braindecode.datasets import BIDSDataset
-from braindecode.datasets.utils import _correct_dataset_path
-
-SIENA_URL = "https://zenodo.org/records/10640762/files/BIDS_Siena.zip"
-SIENA_archive_name = "SIENA.zip"
-SIENA_folder_name = "SIENA-BIDS-eeg-dataset"
-SIENA_dataset_name = "SIENA-EEG-Corpus"
-
-SIENA_dataset_params = {
-    "dataset_name": SIENA_dataset_name,
-    "url": SIENA_URL,
-    "archive_name": SIENA_archive_name,
-    "folder_name": SIENA_folder_name,
-    "hash": "126e71e18570cf359a440ba5227494ecffca4b0b0057c733f90ec29ba5e15ff8",  # sha256
-    "config_key": SIENA_dataset_name,
-}
-
-
-class SIENA(BIDSDataset):
-    """The Siena EEG Dataset.
-
-    The database consists of EEG recordings of 14 patients acquired at the Unit of Neurology
-    and Neurophysiology of the University of Siena.
-
-    Subjects include 9 males (ages 25-71) and 5 females (ages 20-58).
-    Subjects were monitored with a Video-EEG with a sampling rate of 512 Hz,
-    with electrodes arranged on the basis of the international 10-20 System.
-
-    Most of the recordings also contain 1 or 2 EKG signals.
-    The diagnosis of epilepsy and the classification of seizures according to the
-    criteria of the International League Against Epilepsy were performed by an expert
-    clinician after a careful review of the clinical and electrophysiological
-    data of each patient.
-
-    This BIDS-compatible version of the dataset was published by Jonathan Dan [Dan2025]_
-    and is based on the original Siena Scalp EEG Database [Detti2020a]_, [Detti2020b]_.
-
-    .. versionadded:: 1.3
-
-    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.
-
-    References
-    ----------
-    .. [Detti2020a] Detti, P. (2020). Siena Scalp EEG Database (version 1.0.0).
-        PhysioNet. RRID:SCR_007345. https://doi.org/10.13026/5d4a-j060
-    .. [Detti2020b] Detti, P., Vatti, G., Zabalo Manrique de Lara, G.
-        EEG Synchronization Analysis for Seizure Prediction:
-        A Study on Data of Noninvasive Recordings.
-        Processes 2020, 8(7), 846; https://doi.org/10.3390/pr8070846
-    .. [Dan2025] Dan, J., Pale, U., Amirshahi, A., Cappelletti, W.,
-        Ingolfsson, T. M., Wang, X., ... & Ryvlin, P. (2025).
-        SzCORE: seizure community open-source research evaluatio
-        framework for the validation of electroencephalography-based
-        automated seizure detection algorithms. Epilepsia, 66, 14-24.
-    """
-
-    def __init__(self, root=None, *args, **kwargs):
-        # Download dataset if not present
-        if root is None:
-            path_root = fetch_dataset(
-                dataset_params=SIENA_dataset_params,
-                path=None,
-                processor="unzip",
-                force_update=False,
-            )
-            # First time we fetch the dataset, we need to move the files to the
-            # correct directory.
-            path_root = _correct_dataset_path(
-                path_root, SIENA_archive_name, "BIDS_Siena"
-            )
-        else:
-            # Validate that the provided root is a valid BIDS dataset
-            if not Path(f"{root}/participants.tsv").exists():
-                raise ValueError(
-                    f"The provided root directory {root} does not contain a valid "
-                    "BIDS dataset (missing participants.tsv). Please ensure the "
-                    "root points directly to the BIDS dataset directory."
-                )
-            path_root = root
-
-        kwargs["root"] = path_root
-
-        super().__init__(
-            *args,
-            extensions=".edf",
-            check=False,
-            **kwargs,
-        )

braindecode/datasets/utils.py

@@ -1,67 +0,0 @@
-"""Utility functions for dataset handling."""
-
-# Authors: Bruno Aristimunha <b.aristimunha@gmail.com>
-#
-# License: BSD (3-clause)
-
-from __future__ import annotations
-
-import os
-from pathlib import Path
-
-
-def _correct_dataset_path(
-    path: str, archive_name: str, subfolder_name: str | None = None
-) -> str:
-    """
-    Correct the dataset path after download and extraction.
-
-    This function handles two common post-download scenarios:
-    1. Renames '.unzip' suffixed directories created by some extraction tools
-    2. Navigates into a subfolder if the archive extracts to a nested directory
-
-    Parameters
-    ----------
-    path : str
-        Expected path to the dataset directory.
-    archive_name : str
-        Name of the downloaded archive file without extension
-        (e.g., "chb_mit_bids", "NMT").
-    subfolder_name : str | None
-        Name of the subfolder within the extracted archive that contains the
-        actual data. If provided and the subfolder exists, the path will be
-        updated to point to it. If None, only renaming is attempted.
-        Default is None.
-
-    Returns
-    -------
-    str
-        The corrected path to the dataset directory.
-
-    Raises
-    ------
-    PermissionError
-        If the '.unzip' directory exists but cannot be renamed due to
-        insufficient permissions.
-    """
-    if not Path(path).exists():
-        unzip_file_name = f"{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."
-                )
-
-    # Check if the subfolder exists inside the path
-    if subfolder_name is not None:
-        subfolder_path = os.path.join(path, subfolder_name)
-        if Path(subfolder_path).exists():
-            path = subfolder_path
-
-    return path