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

braindecode/datasets/hub_validation.py

@@ -1,113 +0,0 @@
-"""
-Shared validation utilities for Hub format operations.
-
-This module provides validation functions used by hub.py to avoid code duplication.
-"""
-
-# Authors: Kuntal Kokate
-#
-# License: BSD (3-clause)
-
-from typing import Any, List, Tuple
-
-from .registry import get_dataset_type
-
-
-def validate_dataset_uniformity(
-    datasets: List[Any],
-) -> Tuple[str, List[str], float]:
-    """
-    Validate all datasets have uniform type, channels, and sampling frequency.
-
-    Parameters
-    ----------
-    datasets : list
-        List of dataset objects to validate.
-
-    Returns
-    -------
-    dataset_type : str
-        The validated dataset type (WindowsDataset, EEGWindowsDataset, or RawDataset).
-    first_ch_names : list of str
-        Channel names from the first dataset.
-    first_sfreq : float
-        Sampling frequency from the first dataset.
-
-    Raises
-    ------
-    ValueError
-        If datasets have mixed types, inconsistent channels, or inconsistent
-        sampling frequencies.
-    TypeError
-        If dataset type is not supported.
-    """
-    if not datasets:
-        raise ValueError("No datasets provided for validation.")
-
-    first_ds = datasets[0]
-    dataset_type = get_dataset_type(first_ds)
-
-    # Get reference channel names and sampling frequency from the first dataset
-    first_ch_names, first_sfreq = _get_ch_names_and_sfreq(first_ds, dataset_type)
-
-    # Validate all datasets have uniform properties
-    for i, ds in enumerate(datasets):
-        ds_type = get_dataset_type(ds)
-        if ds_type != dataset_type:
-            raise ValueError(
-                f"Mixed dataset types in concat: dataset 0 is {dataset_type} "
-                f"but dataset {i} is {ds_type}"
-            )
-
-        ch_names, sfreq = _get_ch_names_and_sfreq(ds, dataset_type)
-
-        if ch_names != first_ch_names:
-            raise ValueError(
-                f"Inconsistent channel names: dataset 0 has {first_ch_names} "
-                f"but dataset {i} has {ch_names}"
-            )
-
-        if sfreq != first_sfreq:
-            _raise_sfreq_error(first_sfreq, sfreq, i)
-
-    return dataset_type, first_ch_names, first_sfreq
-
-
-def _get_ch_names_and_sfreq(ds: Any, dataset_type: str) -> Tuple[List[str], float]:
-    """Return (ch_names, sfreq) for supported dataset types."""
-    if dataset_type == "WindowsDataset":
-        obj = ds.windows
-    elif dataset_type in ("EEGWindowsDataset", "RawDataset"):
-        obj = ds.raw
-    else:
-        raise TypeError(f"Unsupported dataset type: {dataset_type}")
-
-    return obj.ch_names, obj.info["sfreq"]
-
-
-def _raise_sfreq_error(expected: float, actual: float, idx: int):
-    """
-    Raise standardized sampling frequency error.
-
-    Parameters
-    ----------
-    expected : float
-        Expected sampling frequency from dataset 0.
-    actual : float
-        Actual sampling frequency from current dataset.
-    idx : int
-        Index of the dataset with inconsistent sampling frequency.
-
-    Raises
-    ------
-    ValueError
-        Always raised with standardized error message.
-    """
-    raise ValueError(
-        f"Inconsistent sampling frequencies: dataset 0 has {expected} Hz "
-        f"but dataset {idx} has {actual} Hz. "
-        f"Please resample all datasets to a common frequency before saving. "
-        f"Use braindecode.preprocessing.preprocess("
-        f"[Preprocessor(Resample(sfreq={expected}))], concat_ds) "
-        f"to resample your datasets."
-    )

braindecode/datasets/registry.py

@@ -1,120 +0,0 @@
-"""
-Dataset registry for Hub integration.
-
-Datasets register themselves here so Hub code can look them up by name
-without direct imports (avoiding circular dependencies).
-"""
-
-# Authors: Kuntal Kokate
-#
-# License: BSD (3-clause)
-
-from typing import Any, Dict, Type
-
-# Global registry mapping dataset class names to classes
-_DATASET_REGISTRY: Dict[str, Type] = {}
-
-
-def register_dataset(cls: Type) -> Type:
-    """
-    Decorator to register a dataset class in the global registry.
-
-    Parameters
-    ----------
-    cls : Type
-        The dataset class to register.
-
-    Returns
-    -------
-    Type
-        The same class (unchanged), so this can be used as a decorator.
-    """
-    _DATASET_REGISTRY[cls.__name__] = cls
-    return cls
-
-
-def _available_datasets_str() -> str:
-    """Return a human-readable list of registered dataset class names."""
-    if not _DATASET_REGISTRY:
-        return "<no registered datasets>"
-    return ", ".join(_DATASET_REGISTRY.keys())
-
-
-def get_dataset_class(name: str) -> Type:
-    """
-    Retrieve a registered dataset class by name.
-
-    Parameters
-    ----------
-    name : str
-        Name of the dataset class (e.g., 'WindowsDataset').
-
-    Returns
-    -------
-    Type
-        The dataset class.
-
-    Raises
-    ------
-    KeyError
-        If the class name is not registered.
-    """
-    try:
-        return _DATASET_REGISTRY[name]
-    except KeyError as exc:
-        raise KeyError(
-            f"Dataset class '{name}' not found in registry. "
-            f"Available classes: {_available_datasets_str()}"
-        ) from exc
-
-
-def get_dataset_type(obj: Any) -> str:
-    """
-    Get the registered type name for a dataset instance.
-
-    Parameters
-    ----------
-    obj : Any
-        The object to check.
-
-    Returns
-    -------
-    str
-        The name of the dataset class (e.g., 'WindowsDataset').
-
-    Raises
-    ------
-    TypeError
-        If the object is not an instance of any registered dataset class.
-    """
-    for cls in _DATASET_REGISTRY.values():
-        if isinstance(obj, cls):
-            return cls.__name__
-
-    raise TypeError(
-        f"Object of type {type(obj).__name__} is not a registered dataset class. "
-        f"Available classes: {_available_datasets_str()}"
-    )
-
-
-def is_registered_dataset(obj: Any, class_name: str) -> bool:
-    """
-    Check if an object is an instance of a registered dataset class.
-
-    Parameters
-    ----------
-    obj : Any
-        The object to check.
-    class_name : str
-        Name of the dataset class to check against.
-
-    Returns
-    -------
-    bool
-        True if obj is an instance of the named class, False otherwise.
-    """
-    try:
-        cls = get_dataset_class(class_name)
-    except KeyError:
-        return False
-    return isinstance(obj, cls)

braindecode/datautil/hub_formats.py

@@ -1,180 +0,0 @@
-"""
-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()