braindecode 1.3.0.dev177069446__py3-none-any.whl

braindecode/datasets/xy.py

@@ -0,0 +1,96 @@
+# Authors: Lukas Gemein <l.gemein@gmail.com>
+#          Robin Schirrmeister <robintibor@gmail.com>
+#
+# License: BSD (3-clause)
+
+from __future__ import annotations
+
+import logging
+
+import mne
+import numpy as np
+import pandas as pd
+from numpy.typing import ArrayLike, NDArray
+
+from .base import BaseConcatDataset, RawDataset
+
+log = logging.getLogger(__name__)
+
+
+def create_from_X_y(
+    X: NDArray,
+    y: ArrayLike,
+    drop_last_window: bool,
+    sfreq: float,
+    ch_names: ArrayLike = None,
+    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.
+
+    decoding with skorch and braindecode, where X is a list of pre-cut trials
+    and y are corresponding targets.
+
+    Parameters
+    ----------
+    X : array-like
+        list of pre-cut trials as n_trials x n_channels x n_times
+    y : array-like
+        targets corresponding to the trials
+    drop_last_window : bool
+        whether or not have a last overlapping window, when
+        windows/windows do not equally divide the continuous signal
+    sfreq : float
+        Sampling frequency of signals.
+    ch_names : array-like
+        Names of the channels.
+    window_size_samples : int
+        window size
+    window_stride_samples : int
+        stride between windows
+
+    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_fixed_length_windows,
+    )
+
+    n_samples_per_x = []
+    base_datasets = []
+    if ch_names is None:
+        ch_names = [str(i) for i in range(X.shape[1])]
+        log.info(f"No channel names given, set to 0-{X.shape[1]}).")
+
+    for x, target in zip(X, y):
+        n_samples_per_x.append(x.shape[1])
+        info = mne.create_info(ch_names=ch_names, sfreq=sfreq)
+        raw = mne.io.RawArray(x, info)
+        base_dataset = RawDataset(
+            raw, pd.Series({"target": target}), target_name="target"
+        )
+        base_datasets.append(base_dataset)
+    base_datasets = BaseConcatDataset(base_datasets)
+
+    if window_size_samples is None and window_stride_samples is None:
+        if not len(np.unique(n_samples_per_x)) == 1:
+            raise ValueError(
+                "if 'window_size_samples' and "
+                "'window_stride_samples' are None, "
+                "all trials have to have the same length"
+            )
+        window_size_samples = n_samples_per_x[0]
+        window_stride_samples = n_samples_per_x[0]
+    windows_datasets = create_fixed_length_windows(
+        base_datasets,
+        start_offset_samples=0,
+        stop_offset_samples=None,
+        window_size_samples=window_size_samples,
+        window_stride_samples=window_stride_samples,
+        drop_last_window=drop_last_window,
+    )
+    return windows_datasets

braindecode/datautil/__init__.py

@@ -0,0 +1,62 @@
+"""Utilities for data manipulation."""
+
+from .channel_utils import (
+    division_channels_idx,
+    match_hemisphere_chans,
+)
+from .serialization import (
+    _check_save_dir_empty,
+    load_concat_dataset,
+    save_concat_dataset,
+)
+from .util import infer_signal_properties
+
+
+def __getattr__(name):
+    # ideas from https://stackoverflow.com/a/57110249/1469195
+    import importlib
+    from warnings import warn
+
+    if name == "create_from_X_y":
+        warn(
+            "create_from_X_y has been moved to datasets, please use from braindecode.datasets import create_from_X_y"
+        )
+        xy = importlib.import_module("..datasets.xy", __package__)
+        return xy.create_from_X_y
+    if name in ["create_from_mne_raw", "create_from_mne_epochs"]:
+        warn(
+            f"{name} has been moved to datasets, please use from braindecode.datasets import {name}"
+        )
+        mne = importlib.import_module("..datasets.mne", __package__)
+        return mne.__dict__[name]
+    if name in [
+        "scale",
+        "exponential_moving_demean",
+        "exponential_moving_standardize",
+        "filterbank",
+        "preprocess",
+        "Preprocessor",
+    ]:
+        warn(
+            f"{name} has been moved to preprocessing, please use from braindecode.preprocessing import {name}"
+        )
+        preprocess = importlib.import_module("..preprocessing.preprocess", __package__)
+        return preprocess.__dict__[name]
+    if name in ["create_windows_from_events", "create_fixed_length_windows"]:
+        warn(
+            f"{name} has been moved to preprocessing, please use from braindecode.preprocessing import {name}"
+        )
+        windowers = importlib.import_module("..preprocessing.windowers", __package__)
+        return windowers.__dict__[name]
+
+    raise AttributeError("No possible import named " + name)
+
+
+__all__ = [
+    "load_concat_dataset",
+    "save_concat_dataset",
+    "_check_save_dir_empty",
+    "match_hemisphere_chans",
+    "division_channels_idx",
+    "infer_signal_properties",
+]

braindecode/datautil/channel_utils.py

@@ -0,0 +1,114 @@
+"""
+Utilities for EEG channel manipulation and selection.
+
+This module provides functions for dividing and matching EEG channels,
+particularly for hemisphere-aware processing.
+"""
+
+import re
+from re import search
+
+
+def match_hemisphere_chans(left_chs, right_chs):
+    """
+    Match channels of the left and right hemispheres based on their names.
+
+    This function pairs channels from the left and right hemispheres by matching
+    their numeric identifiers. For a left channel with number N, it finds the
+    corresponding right channel with number N+1.
+
+    Parameters
+    ----------
+    left_chs : list of str
+        A list of channel names from the left hemisphere.
+    right_chs : list of str
+        A list of channel names from the right hemisphere.
+
+    Returns
+    -------
+    list of tuples
+        List of tuples with matched channel names from the left and right hemispheres.
+        Each tuple contains (left_channel, right_channel).
+
+    Raises
+    ------
+    ValueError
+        If the left and right channels do not match in length.
+    ValueError
+        If a channel name does not contain a number.
+    ValueError
+        If no matching right hemisphere channel is found for a left channel.
+
+    Examples
+    --------
+    >>> left = ['C3', 'F3']
+    >>> right = ['C4', 'F4']
+    >>> match_hemisphere_chans(left, right)
+    [('C3', 'C4'), ('F3', 'F4')]
+    """
+    if len(left_chs) != len(right_chs):
+        raise ValueError("Left and right channels do not match.")
+    right_chs = list(right_chs)
+    regexp = r"\d+"
+    out = []
+    for left in left_chs:
+        match = re.search(regexp, left)
+        if match is None:
+            raise ValueError(f"Channel '{left}' does not contain a number.")
+        chan_idx = 1 + int(match.group())
+        target_r = re.sub(regexp, str(chan_idx), left)
+        for right in right_chs:
+            if right == target_r:
+                out.append((left, right))
+                right_chs.remove(right)
+                break
+        else:
+            raise ValueError(
+                f"Found no right hemisphere matching channel for '{left}'."
+            )
+    return out
+
+
+def division_channels_idx(ch_names):
+    """
+    Divide EEG channel names into left, right, and middle based on numbering.
+
+    This function categorizes channels by their numeric suffix:
+    - Odd-numbered channels → left hemisphere
+    - Even-numbered channels → right hemisphere
+    - Channels without numbers → middle/midline
+
+    Parameters
+    ----------
+    ch_names : list of str
+        A list of EEG channel names to be divided based on their numbering.
+
+    Returns
+    -------
+    tuple of lists
+        Three lists containing the channel names:
+        - left: Odd-numbered channels (e.g., C3, F3, P3)
+        - right: Even-numbered channels (e.g., C4, F4, P4)
+        - middle: Channels without numbers (e.g., Cz, Fz, Pz)
+
+    Notes
+    -----
+    The function identifies channel numbers by searching for numeric characters
+    in the channel names. Standard 10-20 system EEG channel naming conventions
+    use odd numbers for left hemisphere and even numbers for right hemisphere.
+
+    Examples
+    --------
+    >>> channels = ['FP1', 'FP2', 'O1', 'O2', 'FZ']
+    >>> division_channels_idx(channels)
+    (['FP1', 'O1'], ['FP2', 'O2'], ['FZ'])
+    """
+    left, right, middle = [], [], []
+    for ch in ch_names:
+        number = search(r"\d+", ch)
+        if number is not None:
+            (left if int(number[0]) % 2 else right).append(ch)
+        else:
+            middle.append(ch)
+
+    return left, right, middle

braindecode/datautil/hub_formats.py

@@ -0,0 +1,180 @@
+"""
+Format converters for Hugging Face Hub integration.
+
+This module provides Zarr format converters to transform EEG datasets for
+efficient storage and fast random access during training on the Hugging Face Hub.
+
+This module provides a standalone functional API that delegates to the
+HubDatasetMixin methods for all actual implementations.
+"""
+
+# Authors: Kuntal Kokate
+#
+# License: BSD (3-clause)
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import TYPE_CHECKING, Dict, List, Optional, Union
+
+# Import registry for dynamic class lookup
+from ..datasets.registry import get_dataset_class
+
+# Import dataset classes for type checking only
+if TYPE_CHECKING:
+    from ..datasets.base import BaseConcatDataset
+
+
+# =============================================================================
+# Zarr Format Converters
+# =============================================================================
+
+
+def convert_to_zarr(
+    dataset: BaseConcatDataset,
+    output_path: Union[str, Path],
+    compression: str = "blosc",
+    compression_level: int = 5,
+    overwrite: bool = False,
+) -> Path:
+    """Convert BaseConcatDataset to Zarr format.
+
+    Zarr provides cloud-native chunked storage, optimized for random access
+    during training. This is the format used for Hugging Face Hub uploads,
+    based on comprehensive benchmarking showing:
+    - Fastest random access: 0.010 ms (critical for PyTorch DataLoader)
+    - Fast save/load: 0.46s / 0.12s
+    - Good compression: ~23% size reduction with blosc
+
+    Parameters
+    ----------
+    dataset : BaseConcatDataset
+        The dataset to convert.
+    output_path : str | Path
+        Path where the Zarr directory will be created.
+    compression : str, default="blosc"
+        Compression algorithm. Options: "blosc" (recommended), "zstd", "gzip", None.
+        blosc uses zstd codec by default, providing best balance of speed and compression.
+    compression_level : int, default=5
+        Compression level (0-9). Level 5 provides optimal balance based on benchmarks.
+    overwrite : bool, default=False
+        Whether to overwrite existing directory.
+
+    Returns
+    -------
+    Path
+        Path to the created Zarr directory.
+
+    Notes
+    -----
+    The chunking strategy is optimized for random access:
+    - Windowed data: Each window is a separate chunk (1, n_channels, n_times)
+    - Raw data: Chunks of (n_channels, 10000) samples
+
+    Examples
+    --------
+    >>> dataset = NMT(path=path, preload=True)
+    >>> # Use default settings (optimal from benchmarks)
+    >>> zarr_path = convert_to_zarr(dataset, "dataset.zarr")
+    >>>
+    >>> # Or customize compression
+    >>> zarr_path = convert_to_zarr(
+    ...     dataset, "dataset.zarr",
+    ...     compression="blosc",
+    ...     compression_level=5
+    ... )
+    """
+    output_path = Path(output_path)
+
+    if output_path.exists():
+        if not overwrite:
+            raise FileExistsError(
+                f"{output_path} already exists. Set overwrite=True to replace it."
+            )
+        # Remove existing directory if overwrite is True
+        shutil.rmtree(output_path)
+
+    # Delegate to HubDatasetMixin method
+    dataset._convert_to_zarr_inline(output_path, compression, compression_level)
+
+    return output_path
+
+
+def load_from_zarr(
+    input_path: Union[str, Path],
+    preload: bool = True,
+    ids_to_load: Optional[List[int]] = None,
+):
+    """Load BaseConcatDataset from Zarr format.
+
+    Zarr is the format used for braindecode Hub datasets, providing
+    the fastest random access performance for training with PyTorch.
+
+    Parameters
+    ----------
+    input_path : str | Path
+        Path to the Zarr directory.
+    preload : bool, default=True
+        Whether to load data into memory. If False, uses lazy loading
+        (data is loaded on-demand during training).
+    ids_to_load : list of int | None
+        Specific recording IDs to load. If None, loads all.
+
+    Returns
+    -------
+    BaseConcatDataset
+        The loaded dataset.
+
+    Examples
+    --------
+    >>> # Load from local zarr directory
+    >>> dataset = load_from_zarr("dataset.zarr", preload=True)
+    >>>
+    >>> # Load from Hugging Face Hub (handled automatically)
+    >>> from braindecode.datasets import BaseConcatDataset
+    >>> dataset = BaseConcatDataset.from_pretrained("username/dataset-name")
+    """
+    # Delegate to HubDatasetMixin static method
+    BaseConcatDataset = get_dataset_class("BaseConcatDataset")
+
+    # Load full dataset using mixin method
+    dataset = BaseConcatDataset._load_from_zarr_inline(Path(input_path), preload)
+
+    # Filter to specific IDs if requested
+    if ids_to_load is not None:
+        # Get only the requested datasets
+        filtered_datasets = [dataset.datasets[i] for i in ids_to_load]
+        dataset = BaseConcatDataset(filtered_datasets)
+
+    return dataset
+
+
+# =============================================================================
+# Utility Functions
+# =============================================================================
+
+
+def get_format_info(dataset: "BaseConcatDataset") -> Dict:
+    """Get dataset information for Hub metadata.
+
+    Validates that all datasets in the concat have uniform properties
+    (channels, sampling frequency) and raises an error if not.
+
+    Parameters
+    ----------
+    dataset : BaseConcatDataset
+        The dataset to analyze.
+
+    Returns
+    -------
+    dict
+        Dictionary with dataset statistics and format info.
+
+    Raises
+    ------
+    ValueError
+        If datasets have inconsistent channels or sampling frequencies.
+    """
+    # Delegate to HubDatasetMixin method
+    return dataset._get_format_info_inline()