Braindecode 1.5.0.dev997__tar.gz → 1.5.0.dev998__tar.gz

{braindecode-1.5.0.dev997/braindecode.egg-info → braindecode-1.5.0.dev998}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: braindecode
-Version: 1.5.0.dev997
+Version: 1.5.0.dev998
 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>
@@ -43,8 +43,6 @@ Requires-Dist: eegprep[eeglabio]>=0.2.23; extra == "eegprep"
 Provides-Extra: hub
 Requires-Dist: huggingface_hub[torch]>=0.20.0; extra == "hub"
 Requires-Dist: zarr>=3.0; extra == "hub"
-Provides-Extra: viz
-Requires-Dist: captum>=0.7.0; extra == "viz"
 Provides-Extra: tests
 Requires-Dist: pytest; extra == "tests"
 Requires-Dist: pytest-cov; extra == "tests"
@@ -72,7 +70,7 @@ Requires-Dist: sphinx_design; extra == "docs"
 Requires-Dist: lightning; extra == "docs"
 Requires-Dist: seaborn; extra == "docs"
 Requires-Dist: pre-commit; extra == "docs"
-Requires-Dist: openneuro-py>=2026.4.0; extra == "docs"
+Requires-Dist: openneuro-py; extra == "docs"
 Requires-Dist: plotly; extra == "docs"
 Requires-Dist: shap; extra == "docs"
 Requires-Dist: nbformat; extra == "docs"
@@ -84,7 +82,6 @@ Requires-Dist: braindecode[docs]; extra == "all"
 Requires-Dist: braindecode[hub]; extra == "all"
 Requires-Dist: braindecode[eegprep]; extra == "all"
 Requires-Dist: braindecode[typing]; extra == "all"
-Requires-Dist: braindecode[viz]; extra == "all"
 Dynamic: license-file
 
 .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.17699192.svg

{braindecode-1.5.0.dev997 → braindecode-1.5.0.dev998}/braindecode/datasets/sleep_physionet.py

@@ -6,12 +6,10 @@
 from __future__ import annotations
 
 import os
-import time
 
 import mne
 import numpy as np
 import pandas as pd
-import requests
 from mne.datasets.sleep_physionet.age import fetch_data
 
 from .base import BaseConcatDataset, RawDataset
@@ -61,19 +59,7 @@ class SleepPhysionet(BaseConcatDataset):
         if recording_ids is None:
             recording_ids = [1, 2]
 
-        max_attempts = 5
-        retry_delay_s = 10
-
-        for attempt in range(max_attempts):
-            try:
-                paths = fetch_data(
-                    subject_ids, recording=recording_ids, on_missing="warn"
-                )
-                break
-            except requests.exceptions.RequestException:
-                if attempt == max_attempts - 1:
-                    raise
-                time.sleep(retry_delay_s)
+        paths = fetch_data(subject_ids, recording=recording_ids, on_missing="warn")
 
         all_base_ds = list()
         for p in paths:

{braindecode-1.5.0.dev997 → braindecode-1.5.0.dev998}/braindecode/models/__init__.py

@@ -25,7 +25,6 @@ from .eegpt import EEGPT
 from .eegsimpleconv import EEGSimpleConv
 from .eegsym import EEGSym
 from .eegtcnet import EEGTCNet
-from .emg2qwerty import EMG2QwertyNet
 from .fbcnet import FBCNet
 from .fblightconvnet import FBLightConvNet
 from .fbmsnet import FBMSNet
@@ -96,7 +95,6 @@ __all__ = [
     "EEGSimpleConv",
     "EEGTCNet",
     "DGCNN",
-    "EMG2QwertyNet",
     "FBCNet",
     "FBLightConvNet",
     "FBMSNet",

{braindecode-1.5.0.dev997 → braindecode-1.5.0.dev998}/braindecode/models/summary.csv

@@ -40,7 +40,6 @@ USleep,Sleep Staging,Classification,128,"n_chans, n_outputs, n_times, sfreq",248
 FBCNet,Motor Imagery,Classification,250,"n_chans, n_outputs, n_times, sfreq",11812,"FCNet(n_chans=22, n_outputs=4, n_times=1000, sfreq=250)","Convolution,FilterBank"
 FBMSNet,Motor Imagery,Classification,250,"n_chans, n_outputs, n_times, sfreq",16231,"FBMSNet(n_chans=22, n_outputs=4, n_times=1000, sfreq=250)","Convolution,FilterBank"
 MetaNeuromotorHand,Handwriting (sEMG),CTC Sequence,2000,"n_chans, n_outputs, n_times, sfreq",1021284,"MetaNeuromotorHand(n_chans=16, n_outputs=100, n_times=32000, sfreq=2000)","Convolution,Attention/Transformer"
-EMG2QwertyNet,Touch typing (sEMG),CTC Sequence,2000,"n_chans, n_outputs, n_times, sfreq",5293315,"EMG2QwertyNet(n_chans=32, n_outputs=99, n_times=8000, sfreq=2000)","Convolution"
 FBLightConvNet,Motor Imagery,Classification,250,"n_chans, n_outputs, n_times, sfreq",6596,"FBLightConvNet(n_chans=22, n_outputs=4, n_times=1000, sfreq=250)","Convolution,FilterBank"
 IFNet,Motor Imagery,Classification,250,"n_chans, n_outputs, n_times, sfreq",9860,"IFNet(n_chans=22, n_outputs=4, n_times=1000, sfreq=250)","Convolution,FilterBank"
 BrainModule,Speech Decoding,Classification,250,"n_chans, n_outputs, n_times, sfreq",6186909,"BrainModule(n_chans=64, n_outputs=29, n_times=160, sfreq=1000)","Convolution"

{braindecode-1.5.0.dev997 → braindecode-1.5.0.dev998}/braindecode/models/util.py

@@ -347,17 +347,6 @@ models_mandatory_parameters: list[
             "n_outputs": 100,
         },
     ),
-    (
-        "EMG2QwertyNet",
-        ["n_chans", "n_outputs", "n_times", "sfreq"],
-        {
-            "n_chans": 32,
-            "n_times": 8000,
-            "sfreq": 2000.0,
-            "input_window_seconds": 4.0,
-            "n_outputs": 99,
-        },
-    ),
     ("FBLightConvNet", ["n_chans", "n_outputs", "n_times", "sfreq"], {"sfreq": 200.0}),
     ("IFNet", ["n_chans", "n_outputs", "n_times", "sfreq"], {"sfreq": 200.0}),
     ("PBT", ["n_chans", "n_outputs", "n_times"], None),
@@ -408,7 +397,6 @@ non_classification_models = [
     "InterpolatedSignalJEPA",
     # Emits a (batch, T_out, vocab) sequence for CTC, not class logits.
     "MetaNeuromotorHand",
-    "EMG2QwertyNet",
 ]
 
 ################################################################

braindecode-1.5.0.dev998/braindecode/version.py

@@ -0,0 +1 @@
+__version__ = "1.5.0.dev998"

braindecode-1.5.0.dev998/braindecode/visualization/__init__.py

@@ -0,0 +1,8 @@
+"""
+Functions for visualisations, especially of the ConvNets.
+"""
+
+from .confusion_matrices import plot_confusion_matrix
+from .gradients import compute_amplitude_gradients
+
+__all__ = ["compute_amplitude_gradients", "plot_confusion_matrix"]

braindecode-1.5.0.dev998/braindecode/visualization/gradients.py

@@ -0,0 +1,62 @@
+# Authors: Robin Schirrmeister <robintibor@gmail.com>
+#          Sarthak Tayal <sarthaktayal2@gmail.com>
+#
+# License: BSD (3-clause)
+
+import numpy as np
+import torch
+from skorch.utils import to_numpy, to_tensor
+
+from braindecode.util import set_random_seeds
+
+
+def compute_amplitude_gradients(model, dataset, batch_size, seed=20240205):
+    """Compute amplitude gradients after seeding for reproducibility."""
+    cuda = next(model.parameters()).is_cuda
+    set_random_seeds(seed=seed, cuda=cuda)
+    loader = torch.utils.data.DataLoader(
+        dataset, batch_size=batch_size, drop_last=False, shuffle=False
+    )
+    all_amp_grads = []
+    for batch_X, _, _ in loader:
+        this_amp_grads = compute_amplitude_gradients_for_X(
+            model,
+            batch_X,
+        )
+        all_amp_grads.append(this_amp_grads)
+    all_amp_grads = np.concatenate(all_amp_grads, axis=1)
+    return all_amp_grads
+
+
+def compute_amplitude_gradients_for_X(model, X):
+    device = next(model.parameters()).device
+    ffted = np.fft.rfft(X, axis=2)
+    amps = np.abs(ffted)
+    phases = np.angle(ffted)
+    amps_th = to_tensor(amps.astype(np.float32), device=device).requires_grad_(True)
+    phases_th = to_tensor(phases.astype(np.float32), device=device).requires_grad_(True)
+
+    # rebuild fft coefficients from amplitude and phase as real valued pairs,
+    # convert to complex, and invert back to the time domain.
+    # torch.irfft was removed after being deprecated since pytorch 1.7,
+    # so we use torch.fft.irfft which expects complex input directly.
+    fft_coefs = amps_th.unsqueeze(-1) * torch.stack(
+        (torch.cos(phases_th), torch.sin(phases_th)), dim=-1
+    )
+    fft_coefs = fft_coefs.squeeze(3)
+
+    complex_fft_coefs = torch.view_as_complex(fft_coefs)
+    iffted = torch.fft.irfft(complex_fft_coefs, n=X.shape[2], dim=2)
+
+    outs = model(iffted)
+
+    n_filters = outs.shape[1]
+    amp_grads_per_filter = np.full((n_filters,) + ffted.shape, np.nan, dtype=np.float32)
+    for i_filter in range(n_filters):
+        mean_out = torch.mean(outs[:, i_filter])
+        mean_out.backward(retain_graph=True)
+        amp_grads = to_numpy(amps_th.grad.clone())
+        amp_grads_per_filter[i_filter] = amp_grads
+        amps_th.grad.zero_()
+    assert not np.any(np.isnan(amp_grads_per_filter))
+    return amp_grads_per_filter

{braindecode-1.5.0.dev997 → braindecode-1.5.0.dev998/braindecode.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: braindecode
-Version: 1.5.0.dev997
+Version: 1.5.0.dev998
 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>
@@ -43,8 +43,6 @@ Requires-Dist: eegprep[eeglabio]>=0.2.23; extra == "eegprep"
 Provides-Extra: hub
 Requires-Dist: huggingface_hub[torch]>=0.20.0; extra == "hub"
 Requires-Dist: zarr>=3.0; extra == "hub"
-Provides-Extra: viz
-Requires-Dist: captum>=0.7.0; extra == "viz"
 Provides-Extra: tests
 Requires-Dist: pytest; extra == "tests"
 Requires-Dist: pytest-cov; extra == "tests"
@@ -72,7 +70,7 @@ Requires-Dist: sphinx_design; extra == "docs"
 Requires-Dist: lightning; extra == "docs"
 Requires-Dist: seaborn; extra == "docs"
 Requires-Dist: pre-commit; extra == "docs"
-Requires-Dist: openneuro-py>=2026.4.0; extra == "docs"
+Requires-Dist: openneuro-py; extra == "docs"
 Requires-Dist: plotly; extra == "docs"
 Requires-Dist: shap; extra == "docs"
 Requires-Dist: nbformat; extra == "docs"
@@ -84,7 +82,6 @@ Requires-Dist: braindecode[docs]; extra == "all"
 Requires-Dist: braindecode[hub]; extra == "all"
 Requires-Dist: braindecode[eegprep]; extra == "all"
 Requires-Dist: braindecode[typing]; extra == "all"
-Requires-Dist: braindecode[viz]; extra == "all"
 Dynamic: license-file
 
 .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.17699192.svg

{braindecode-1.5.0.dev997 → braindecode-1.5.0.dev998}/braindecode.egg-info/SOURCES.txt

@@ -77,7 +77,6 @@ braindecode/models/eegpt.py
 braindecode/models/eegsimpleconv.py
 braindecode/models/eegsym.py
 braindecode/models/eegtcnet.py
-braindecode/models/emg2qwerty.py
 braindecode/models/fbcnet.py
 braindecode/models/fblightconvnet.py
 braindecode/models/fbmsnet.py
@@ -133,12 +132,8 @@ braindecode/training/callbacks.py
 braindecode/training/losses.py
 braindecode/training/scoring.py
 braindecode/visualization/__init__.py
-braindecode/visualization/attribution.py
 braindecode/visualization/confusion_matrices.py
-braindecode/visualization/frequency.py
-braindecode/visualization/metrics.py
-braindecode/visualization/sanity.py
-braindecode/visualization/topology.py
+braindecode/visualization/gradients.py
 docs/Makefile
 docs/api.rst
 docs/cite.rst

{braindecode-1.5.0.dev997 → braindecode-1.5.0.dev998}/braindecode.egg-info/requires.txt

@@ -20,7 +20,6 @@ braindecode[docs]
 braindecode[hub]
 braindecode[eegprep]
 braindecode[typing]
-braindecode[viz]
 
 [docs]
 sphinx_gallery
@@ -38,7 +37,7 @@ sphinx_design
 lightning
 seaborn
 pre-commit
-openneuro-py>=2026.4.0
+openneuro-py
 plotly
 shap
 nbformat
@@ -66,6 +65,3 @@ bids_validator
 [typing]
 exca>=0.5.10
 numpydantic>=1.7
-
-[viz]
-captum>=0.7.0

{braindecode-1.5.0.dev997 → braindecode-1.5.0.dev998}/docs/api.rst

@@ -153,7 +153,6 @@ interface for all EEG models and can derive variable names when needed.
      EEGSimpleConv
      EEGSym
      EEGTCNet
-     EMG2QwertyNet
      FBCNet
      FBLightConvNet
      FBMSNet
@@ -803,107 +802,16 @@ Functions available in braindecode util module.
  Visualization
 ***************
 
-Tools for opening up trained EEG decoders: per-trial attribution maps, sanity-check
-protocols that probe whether those maps reflect what the model actually learned,
-attribution-quality metrics, topographic projection, and confusion-matrix plotting.
-
-The end-to-end workflow tracks the EEG-XAI benchmark of Sujatha Ravindran &
-Contreras-Vidal (Sci Rep 2023, DOI `10.1038/s41598-023-43871-8
-<https://doi.org/10.1038/s41598-023-43871-8>`_): compute attributions, randomize labels
-and weights, score the resulting maps against the trained-model reference, and decide
-which methods are trustworthy on your data. See the :ref:`interpretability tutorial
-<interpretability-tutorial>` for a worked example on BCI IV 2a.
+Visualization module contains functions for visualizing EEG data, including plotting the
+confusion matrix and computing amplitude gradients. The visualization module is useful
+for understanding the performance of the model and for interpreting the results.
 
 :py:mod:`braindecode.visualization`:
 
 .. currentmodule:: braindecode.visualization
 
-Time-domain attribution
-=======================
-
-Per-trial attribution maps in the input domain. Each function takes ``(model, x,
-target)`` and returns a tensor with the same spatial shape as ``x``; all are thin
-wrappers around `captum <https://captum.ai/>`_ (a soft dependency installed via ``pip
-install braindecode[viz]``) and raise :class:`ImportError` without it.
-
-.. autosummary::
-    :toctree: generated/
-
-     saliency
-     input_x_gradient
-     integrated_gradients
-     layer_grad_cam
-     guided_backprop
-     deconvolution
-     deep_lift
-     lrp
-
-Frequency-domain attribution
-============================
-
-Gradient of each model output with respect to the **amplitude spectrum** of the input —
-a complement to the time-domain methods that makes oscillatory contributions (e.g.
-alpha/beta motor imagery) visible directly in the topomap. Implemented in pure PyTorch
-via ``rfft``/``irfft`` round-tripping; no captum needed.
-
-.. autosummary::
-    :toctree: generated/
-
-     amplitude_gradients
-     amplitude_gradients_per_trial
-
-Sanity-check protocols
-======================
-
-Adebayo et al. (NeurIPS 2018) randomization checks for attribution maps, reused on EEG
-decoders by Sujatha Ravindran & Contreras-Vidal. :func:`random_target` powers the
-**label-randomization** check (does the map change when you ask about the wrong class?)
-and :func:`cascading_layer_reset` powers the **weight-randomization** check (does the
-map collapse as the trained weights are progressively replaced?). An attribution method
-that survives both is suspicious — its output likely reflects architecture rather than
-learning.
-
-.. autosummary::
-    :toctree: generated/
-
-     random_target
-     cascading_layer_reset
-
-Attribution-quality metrics
-===========================
-
-Score how similar two attribution maps are: typically a trained-model attribution
-against a randomized-model attribution, or against a ground-truth mask from a simulator.
-:func:`compute_metrics` returns twelve cosine / Pearson / mass-accuracy / rank-accuracy
-variants; :func:`compute_ssim_metrics` adds four SSIM-based scores using a pure-torch
-reimplementation of skimage's structural similarity (no extra dependency). Pass
-``chs_info=`` to score topographic projections instead of raw attribution maps.
-
-.. autosummary::
-    :toctree: generated/
-
-     compute_metrics
-     compute_ssim_metrics
-     METRIC_NAMES
-     SSIM_METRIC_NAMES
-
-Topography
-==========
-
-Project per-channel scalar values onto a 2-D scalp topomap grid via Clough-Tocher
-triangulation on MNE-derived sensor coordinates. Returns a plain ``ndarray`` so callers
-can compose with their own plotting stack rather than going through
-:func:`mne.viz.plot_topomap` (and its matplotlib roundtrip).
-
-.. autosummary::
-    :toctree: generated/
-
-     project_to_topomap
-
-Plotting
-========
-
 .. autosummary::
     :toctree: generated/
 
+     compute_amplitude_gradients
      plot_confusion_matrix

{braindecode-1.5.0.dev997 → braindecode-1.5.0.dev998}/docs/whats_new.rst

@@ -62,16 +62,6 @@ Enhancements
   instantiation, so keeping them in ``state_dict`` only bloated checkpoints and
   caused spurious mismatches when ``n_chans`` (or the position-bank config)
   differed between save and load. (:gh:`993` by `Pierre Guetschel`_)
-- Add :mod:`braindecode.visualization` interpretability utilities, all built on
-  plain PyTorch autograd with no extra dependencies:
-  :func:`~braindecode.visualization.saliency`,
-  :func:`~braindecode.visualization.input_x_gradient`,
-  :func:`~braindecode.visualization.integrated_gradients`,
-  :func:`~braindecode.visualization.layer_grad_cam`,
-  :func:`~braindecode.visualization.project_to_topomap` (thin wrapper around
-  :func:`mne.viz.plot_topomap`), and :func:`~braindecode.visualization.compute_metrics`
-  for quantitative attribution comparison. A new tutorial,
-  :ref:`interpretability-tutorial`, walks through the full pipeline.
 - Add :class:`braindecode.models.MetaNeuromotorHand`, a port of the
   handwriting decoder from Meta / CTRL-labs' generic neuromotor interface
   (Kaifosh, Reardon et al., Nature 2025). The model takes raw 16-channel
@@ -87,26 +77,6 @@ Enhancements
   the upstream repository; see the class docstring for the license
   warning and the pretrained-checkpoint loading recipe.
   By `Bruno Aristimunha`_.
-- Add :class:`braindecode.models.EMG2QwertyNet`, a port of the
-  TDS-Conv-CTC touch-typing decoder from
-  ``facebookresearch/emg2qwerty`` (Sivakumar et al., NeurIPS 2024). The
-  model takes raw 32-channel surface EMG (two 16-electrode wristbands at
-  2 kHz) and emits per-frame scores over a 99-class typing
-  vocabulary (98 keys + CTC blank); pass ``log_softmax=True`` to get
-  log-probabilities directly consumable by :class:`~torch.nn.CTCLoss`. The pipeline is a parameter-free
-  log-spectrogram front-end, per-electrode-per-band BatchNorm, a
-  circular rotation-invariant MLP (one per band), and a stack of
-  Time-Depth-Separable convolutional blocks (Hannun et al., 2019) without
-  temporal padding. The encoder ``nn.Sequential`` mirrors upstream's
-  ``TDSConvCTCModule.model`` indices for parameter-bearing children, so
-  upstream emg2qwerty checkpoints load directly via ``load_state_dict``
-  (after stripping the PyTorch-Lightning ``network.`` prefix); the
-  class-level :attr:`~braindecode.models.EMG2QwertyNet.mapping` only
-  remaps the head from ``model.4.{weight,bias}`` to
-  ``final_layer.{weight,bias}``. Distributed under CC BY-NC 4.0 to
-  match the upstream repository; see the class docstring for the
-  license warning and the pretrained-checkpoint loading recipe.
-  By `Bruno Aristimunha`_.
 
 API and behavior changes
 ========================
@@ -171,14 +141,6 @@ Bug fixes
   embedding weights when fine-tuning on a subset of the pre-training channels.
   Two new HuggingFace checkpoints are published: ``braindecode/signal-jepa`` and
   ``braindecode/signal-jepa_without-chans`` (:gh:`991` by `Pierre Guetschel`_)
-- Bump ``openneuro-py`` to ``>=2026.4.0`` so the docs build picks up upstream
-  PR ``#308`` (``DatasetFile.key`` → ``id``). The previous ``<2026.4`` pin
-  (:gh:`1000`) avoided a libc double-free seen with newer releases but broke
-  ``examples/datasets_io/plot_bids_dataset_example.py`` against the live
-  OpenNeuro 5.0.0 GraphQL schema (``Cannot query field "key" on type
-  "DatasetFile"``) (:gh:`1002` by `Bruno Aristimunha`_)
-- Retry transient TLS failures from ``physionet.org`` when fetching
-  :class:`braindecode.datasets.SleepPhysionet` (by `Bruno Aristimunha`_)
 
 Code health
 ============

{braindecode-1.5.0.dev997 → braindecode-1.5.0.dev998}/pyproject.toml

@@ -78,7 +78,6 @@ documentation = "https://braindecode.org/stable/index.html"
 moabb = ["moabb>=1.4.3"]
 eegprep = ["eegprep[eeglabio]>=0.2.23"]
 hub = ["huggingface_hub[torch]>=0.20.0", "zarr>=3.0"]
-viz = ["captum>=0.7.0"]
 tests = [
     'pytest',
     'pytest-cov',
@@ -109,7 +108,7 @@ docs = [
     'lightning',
     'seaborn',
     'pre-commit',
-    'openneuro-py>=2026.4.0',  # 2026.4.0 fixes DatasetFile.key->id after the OpenNeuro 5.0.0 schema change; older versions break against the live GraphQL server
+    'openneuro-py',
     'plotly',
     'shap',
     'nbformat',
@@ -123,7 +122,6 @@ all = [
     "braindecode[hub]",
     "braindecode[eegprep]",
     "braindecode[typing]",
-    "braindecode[viz]",
 ]
 
 [tool.setuptools]