Braindecode 1.8.1.dev176771289__tar.gz → 1.8.1.dev176972175__tar.gz

{braindecode-1.8.1.dev176771289 → braindecode-1.8.1.dev176972175}/NOTICE.txt

@@ -47,7 +47,6 @@ The following components are licensed under the MIT License:
 - `braindecode/models/mirepnet.py`
 - `braindecode/models/popt.py`
 - `braindecode/models/tfm_tokenizer.py`
-- `braindecode/modules/popt_modules.py`
 - `braindecode/models/brainomni.py`
 - `braindecode/modules/quantization.py`
 - `braindecode/modules/linear_attention.py`

{braindecode-1.8.1.dev176771289/braindecode.egg-info → braindecode-1.8.1.dev176972175}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: braindecode
-Version: 1.8.1.dev176771289
+Version: 1.8.1.dev176972175
 Summary: Deep learning software to decode EEG, ECG or MEG signals
 Author-email: Robin Tibor Schirrmeister <robintibor@gmail.com>, Bruno Aristimunha Pinto <b.aristimunha@gmail.com>, Alexandre Gramfort <agramfort@meta.com>
 Maintainer-email: Alexandre Gramfort <agramfort@meta.com>, Bruno Aristimunha Pinto <b.aristimunha@gmail.com>, Robin Tibor Schirrmeister <robintibor@gmail.com>
@@ -32,8 +32,8 @@ Requires-Dist: joblib
 Requires-Dist: torchinfo
 Requires-Dist: pandas
 Requires-Dist: wfdb>=4.3.1
-Requires-Dist: linear_attention_transformer
 Requires-Dist: docstring_inheritance
+Requires-Dist: einops
 Requires-Dist: pydantic>=2.0
 Provides-Extra: moabb
 Requires-Dist: moabb>=1.4.3; extra == "moabb"

{braindecode-1.8.1.dev176771289 → braindecode-1.8.1.dev176972175}/braindecode/augmentation/__init__.py

@@ -14,6 +14,7 @@ from .transforms import (
     FrequencyShift,
     FTSurrogate,
     GaussianNoise,
+    LabelSmoothing,
     MaskEncoding,
     Mixup,
     SegmentationReconstruction,
@@ -40,6 +41,7 @@ __all__ = [
     "CutMix",
     "ChannelsDropout",
     "GaussianNoise",
+    "LabelSmoothing",
     "ChannelsSymmetry",
     "SmoothTimeMask",
     "BandstopFilter",

{braindecode-1.8.1.dev176771289 → braindecode-1.8.1.dev176972175}/braindecode/augmentation/functional.py

@@ -19,7 +19,7 @@ from mne.filter import notch_filter
 from scipy.interpolate import Rbf
 from sklearn.utils import check_random_state
 from torch.fft import fft, ifft
-from torch.nn.functional import pad
+from torch.nn.functional import one_hot, pad
 
 
 def _max_float_dtype(device: torch.device | str) -> torch.dtype:
@@ -1089,10 +1089,12 @@ def mixup(
         Online: https://arxiv.org/abs/1710.09412
     .. [2] https://github.com/facebookresearch/mixup-cifar10/blob/master/train.py
     """
-    device = X.device
     batch_size, n_channels, n_times = X.shape
 
-    X_mix = torch.zeros((batch_size, n_channels, n_times)).to(device)
+    X_mix = X.new_zeros(
+        (batch_size, n_channels, n_times),
+        dtype=X.dtype if X.is_floating_point() else torch.get_default_dtype(),
+    )
     y_a = y.clone()
     y_b = y[idx_perm].clone()
 
@@ -1150,6 +1152,97 @@ def cutmix(
     return X_mix, (y.clone(), y[idx_perm].clone(), lam)
 
 
+def label_smoothing(
+    X: torch.Tensor,
+    y: torch.Tensor,
+    epsilon: float,
+    num_classes: int | None = None,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    """Smooth targets toward the uniform distribution over the classes.
+
+    See [1]_ for details.
+
+    Parameters
+    ----------
+    X : torch.Tensor
+        EEG data in form ``batch_size, n_channels, n_times``. Returned
+        unchanged.
+    y : torch.Tensor
+        Target of length ``batch_size`` holding class indices (float values
+        are accepted when they are integral), or a floating-point tensor of
+        shape ``batch_size, num_classes`` holding target distributions.
+    epsilon : float
+        Smoothing parameter between 0 and 1: the weight of the uniform
+        distribution mixed into the targets. ``0`` returns the unsmoothed
+        targets.
+    num_classes : int | None, optional
+        Number of classes. Required when ``y`` holds class indices; when
+        ``y`` already holds distributions, it must match the size of the
+        last dimension of ``y``. Defaults to None.
+
+    Returns
+    -------
+    tuple
+        ``X``, ``y``. Where ``X`` is unchanged and ``y`` is a
+        floating-point tensor of shape ``batch_size, num_classes`` whose
+        rows sum to one.
+
+    References
+    ----------
+    .. [1] Christian Szegedy, Vincent Vanhoucke, Jonathon Shlens and
+        Zbigniew Wojna (2016). Rethinking the Inception Architecture for
+        Computer Vision. In 2016 IEEE Conference on Computer Vision and
+        Pattern Recognition (CVPR), pp. 2818-2826.
+        Online: https://arxiv.org/abs/1512.00567
+    """
+    if not isinstance(epsilon, Real) or not 0.0 <= float(epsilon) <= 1.0:
+        raise ValueError(
+            f"epsilon should be a real number between 0 and 1. Got {epsilon!r}."
+        )
+    if num_classes is not None and (
+        not isinstance(num_classes, int)
+        or isinstance(num_classes, bool)
+        or num_classes < 2
+    ):
+        raise ValueError(
+            f"num_classes should be an integer of at least 2. Got {num_classes!r}."
+        )
+
+    if y.dim() == 1:
+        # class-index targets: smooth their one-hot encoding
+        if num_classes is None:
+            raise ValueError("num_classes is required when y holds class indices.")
+        if not torch.all(y == y.floor()):
+            raise ValueError(
+                "y holds non-integral values; class-index targets should be "
+                "integers or integral floats."
+            )
+        if y.numel() > 0 and (y.min() < 0 or y.max() >= num_classes):
+            raise ValueError(f"y holds class indices outside [0, {num_classes}).")
+        one_hot_y = one_hot(y.long(), num_classes).to(dtype=X.dtype)
+        return X, one_hot_y * (1.0 - epsilon) + epsilon / num_classes
+
+    if y.is_floating_point() and y.dim() >= 2:
+        # target distributions: interpolate them toward the uniform one
+        n_classes = y.shape[-1]
+        if num_classes is not None and num_classes != n_classes:
+            raise ValueError(
+                f"num_classes ({num_classes}) does not match the size of the "
+                f"last dimension of y ({n_classes})."
+            )
+        if n_classes < 2:
+            raise ValueError(
+                f"y should hold distributions over at least 2 classes. Got {n_classes}."
+            )
+        return X, y * (1.0 - epsilon) + epsilon / n_classes
+
+    raise ValueError(
+        "y should hold class indices or floating-point target distributions "
+        f"with a class dimension; got dtype {y.dtype} and shape "
+        f"{tuple(y.shape)}."
+    )
+
+
 def segmentation_reconstruction(
     X: torch.Tensor,
     y: torch.Tensor,

{braindecode-1.8.1.dev176771289 → braindecode-1.8.1.dev176972175}/braindecode/augmentation/transforms.py

@@ -30,6 +30,7 @@ from .functional import (
     frequency_shift,
     ft_surrogate,
     gaussian_noise,
+    label_smoothing,
     mask_encoding,
     mixup,
     segmentation_reconstruction,
@@ -1155,6 +1156,98 @@ class CutMix(Mixup):
         return dict(params, cut_t_start=start, cut_t_len=end - start)
 
 
+class LabelSmoothing(Transform):
+    """Label smoothing from Szegedy et al. (2016) [1]_.
+
+    Replaces each target with its convex combination with the uniform
+    distribution over the classes, penalizing over-confident predictions.
+    The signals are returned unchanged; only the targets change.
+
+    The smoothed targets are floating-point distributions of shape
+    ``batch_size, num_classes`` (each row sums to one), so the training
+    loss must accept target distributions, e.g. soft cross-entropy
+    ``-(y * torch.log_softmax(logits, dim=-1)).sum(-1).mean()`` or
+    ``torch.nn.KLDivLoss``. The transform composes before target-mixing
+    transforms such as :class:`braindecode.augmentation.Mixup`, whose
+    fractional-target path then mixes the smoothed distributions. The
+    fixed-expansion mode (``n_augmentation > 0``) of
+    :class:`braindecode.augmentation.AugmentedDataLoader` is not supported:
+    it cannot concatenate the unsmoothed original targets with the reshaped
+    smoothed copies.
+
+    Parameters
+    ----------
+    epsilon : float
+        Smoothing parameter between 0 and 1: the weight of the uniform
+        distribution mixed into the targets. ``0`` disables smoothing.
+    num_classes : int | None, optional
+        Number of classes. Required when the targets are class indices;
+        when the targets are already distributions of shape
+        ``batch_size, num_classes``, it must match their last dimension.
+        Defaults to None.
+    random_state : int | numpy.random.Generator, optional
+        Seed to be used to instantiate numpy random number generator
+        instance. The transform is deterministic, so the seed only feeds
+        the application-probability machinery, which is inactive here.
+        Defaults to None.
+
+    References
+    ----------
+    .. [1] Christian Szegedy, Vincent Vanhoucke, Jonathon Shlens and
+       Zbigniew Wojna (2016). Rethinking the Inception Architecture for
+       Computer Vision. In 2016 IEEE Conference on Computer Vision and
+       Pattern Recognition (CVPR), pp. 2818-2826.
+       Online: https://arxiv.org/abs/1512.00567
+    """
+
+    operation = staticmethod(label_smoothing)  # type: ignore[assignment]
+
+    def __init__(self, epsilon, num_classes=None, random_state=None):
+        super().__init__(
+            probability=1.0,  # LabelSmoothing has to be applied to whole batches
+            random_state=random_state,
+        )
+        if not isinstance(epsilon, Real) or not 0.0 <= float(epsilon) <= 1.0:
+            raise ValueError(
+                f"epsilon should be a real number between 0 and 1. Got {epsilon!r}."
+            )
+        if num_classes is not None and (
+            not isinstance(num_classes, int)
+            or isinstance(num_classes, bool)
+            or num_classes < 2
+        ):
+            raise ValueError(
+                f"num_classes should be an integer of at least 2. Got {num_classes!r}."
+            )
+        self.epsilon = epsilon
+        self.num_classes = num_classes
+
+    def get_augmentation_params(self, *batch):
+        """Return transform parameters.
+
+        Parameters
+        ----------
+        X : tensor.Tensor
+            The data.
+        y : tensor.Tensor
+            The labels.
+
+        Returns
+        -------
+        params : dict
+            Contains
+
+            * epsilon : float
+                Smoothing parameter between 0 and 1.
+            * num_classes : int | None
+                The number of classes.
+        """
+        return {
+            "epsilon": self.epsilon,
+            "num_classes": self.num_classes,
+        }
+
+
 class SegmentationReconstruction(Transform):
     """Segmentation Reconstruction from Lotte (2015) [Lotte2015]_.
 

{braindecode-1.8.1.dev176771289 → braindecode-1.8.1.dev176972175}/braindecode/datasets/chb_mit.py

@@ -16,12 +16,7 @@ It reorganizes the file structure to comply with the BIDS specification. To this
 # 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
+from braindecode.datasets.utils import _ZenodoBIDSDataset
 
 CHB_MIT_URL = "https://zenodo.org/records/10259996/files/BIDS_CHB-MIT.zip"
 CHB_MIT_archive_name = "chb_mit_bids.zip"
@@ -38,7 +33,7 @@ CHB_MIT_dataset_params = {
 }
 
 
-class CHBMIT(BIDSDataset):
+class CHBMIT(_ZenodoBIDSDataset):
     """The Children's Hospital Boston EEG Dataset.
 
     This database, collected at the Children's Hospital Boston, consists of EEG recordings
@@ -129,35 +124,6 @@ class CHBMIT(BIDSDataset):
     .. 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,
-        )
+    _dataset_params = CHB_MIT_dataset_params
+    _archive_name = CHB_MIT_archive_name
+    _unzipped_dir = "BIDS_CHB-MIT"

{braindecode-1.8.1.dev176771289 → braindecode-1.8.1.dev176972175}/braindecode/datasets/siena.py

@@ -15,12 +15,7 @@ It reorganizes the file structure to comply with the BIDS specification. To this
 # 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
+from braindecode.datasets.utils import _ZenodoBIDSDataset
 
 SIENA_URL = "https://zenodo.org/records/10640762/files/BIDS_Siena.zip"
 SIENA_archive_name = "SIENA.zip"
@@ -37,7 +32,7 @@ SIENA_dataset_params = {
 }
 
 
-class SIENA(BIDSDataset):
+class SIENA(_ZenodoBIDSDataset):
     """The Siena EEG Dataset.
 
     The database consists of EEG recordings of 14 patients acquired at the Unit of Neurology
@@ -128,35 +123,6 @@ class SIENA(BIDSDataset):
         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,
-        )
+    _dataset_params = SIENA_dataset_params
+    _archive_name = SIENA_archive_name
+    _unzipped_dir = "BIDS_Siena"

{braindecode-1.8.1.dev176771289 → braindecode-1.8.1.dev176972175}/braindecode/datasets/sleep_physio_challe_18.py

@@ -57,52 +57,6 @@ def ensure_metafiles_exist():
         _download_if_missing(file_path, url)
 
 
-def _update_pc18_sleep_records(fname=PC18_RECORDS):
-    """Create CSV file with information about available PC18 recordings."""
-    # Load and massage the checksums.
-    sha_train_df = pd.read_csv(
-        PC18_SHA1_TRAINING,
-        sep="  ",
-        header=None,
-        names=["sha", "fname"],
-        engine="python",
-    )
-    sha_test_df = pd.read_csv(
-        PC18_SHA1_TEST, sep="  ", header=None, names=["sha", "fname"], engine="python"
-    )
-    sha_train_df["Split"] = "training"
-    sha_test_df["Split"] = "test"
-    sha_df = pd.concat([sha_train_df, sha_test_df], axis=0, ignore_index=True)
-    select_records = (
-        sha_df.fname.str.startswith("tr") | sha_df.fname.str.startswith("te")
-    ) & ~sha_df.fname.str.endswith("arousal.mat")
-    sha_df = sha_df[select_records]
-    sha_df["Record"] = sha_df["fname"].str.split("/", expand=True)[0]
-    sha_df["fname"] = sha_df[["Split", "fname"]].agg("/".join, axis=1)
-
-    # Load and massage the data.
-    data = pd.read_csv(PC18_INFO)
-
-    data = data.reset_index().rename({"index": "Subject"}, axis=1)
-    data["Sex"] = (
-        data["Sex"].map({"F": "female", "M": "male", "m": "male"}).astype("category")
-    )
-    data = sha_df.merge(data, on="Record")
-
-    data["Record type"] = (
-        data["fname"]
-        .str.split(".", expand=True)[1]
-        .map({"hea": "Header", "mat": "PSG", "arousal": "Arousal"})
-        .astype("category")
-    )
-    data = data[
-        ["Subject", "Record", "Record type", "Split", "Age", "Sex", "sha", "fname"]
-    ].sort_values(by="Subject")
-
-    # Save the data.
-    data.to_csv(fname, index=False)
-
-
 def _data_path(path=None):
     """Get path to local copy of PC18 dataset."""
     key = "PC18_DATASET_PATH"

{braindecode-1.8.1.dev176771289 → braindecode-1.8.1.dev176972175}/braindecode/datasets/utils.py

@@ -9,6 +9,10 @@ from __future__ import annotations
 import os
 from pathlib import Path
 
+from mne.datasets import fetch_dataset
+
+from .bids import BIDSDataset
+
 
 def _correct_dataset_path(
     path: str, archive_name: str, subfolder_name: str | None = None
@@ -65,3 +69,36 @@ def _correct_dataset_path(
             path = subfolder_path
 
     return path
+
+
+class _ZenodoBIDSDataset(BIDSDataset):
+    """A BIDS dataset in EDF files, downloaded from a Zenodo archive when no
+    ``root`` is given. Subclasses set the three class attributes below."""
+
+    _dataset_params: dict
+    _archive_name: str  # the downloaded archive
+    _unzipped_dir: str  # the folder the archive extracts to
+
+    def __init__(self, root=None, *args, **kwargs):
+        if root is None:
+            path_root = fetch_dataset(
+                dataset_params=self._dataset_params,
+                path=None,
+                processor="unzip",
+                force_update=False,
+            )
+            # The first fetch extracts into a nested folder: point at the data.
+            path_root = _correct_dataset_path(
+                path_root, self._archive_name, self._unzipped_dir
+            )
+        elif 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."
+            )
+        else:
+            path_root = root
+        super().__init__(
+            *args, root=path_root, extensions=".edf", check=False, **kwargs
+        )

{braindecode-1.8.1.dev176771289 → braindecode-1.8.1.dev176972175}/braindecode/functional/__init__.py

@@ -1,5 +1,7 @@
+from .attention import scaled_dot_product_attention
 from .functions import (
     _get_gaussian_kernel1d,
+    apply_rotary,
     daubechies_filters,
     drop_path,
     dwt_max_level,
@@ -10,6 +12,9 @@ from .functions import (
     pairwise_iou_1d,
     plv_time,
     prefer_fft_conv,
+    rotary_angles,
+    rotary_frequencies,
+    rotate_half,
     rotate_pairs,
     safe_log,
     sinusoidal_positional_encoding,
@@ -17,10 +22,16 @@ from .functions import (
     square,
     wavelet_decomposition,
 )
-from .initialization import glorot_weight_zero_bias, rescale_parameter
+from .initialization import (
+    glorot_weight_zero_bias,
+    init_weights_,
+    rescale_parameter,
+)
+from .patches import pad_or_crop_to_patches, patch_count
 
 __all__ = [
     "_get_gaussian_kernel1d",
+    "apply_rotary",
     "daubechies_filters",
     "drop_path",
     "dwt_max_level",
@@ -28,15 +39,22 @@ __all__ = [
     "hilbert_freq",
     "identity",
     "iou_1d",
+    "pad_or_crop_to_patches",
     "pairwise_iou_1d",
+    "patch_count",
     "plv_time",
     "prefer_fft_conv",
+    "rotary_angles",
+    "rotary_frequencies",
+    "rotate_half",
     "rotate_pairs",
     "safe_log",
+    "scaled_dot_product_attention",
     "sinusoidal_positional_encoding",
     "spectral_input",
     "square",
     "wavelet_decomposition",
     "glorot_weight_zero_bias",
     "rescale_parameter",
+    "init_weights_",
 ]