Braindecode 1.5.0.dev172791986__tar.gz → 1.5.0.dev176208946__tar.gz

{braindecode-1.5.0.dev172791986/braindecode.egg-info → braindecode-1.5.0.dev176208946}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: braindecode
-Version: 1.5.0.dev172791986
+Version: 1.5.0.dev176208946
 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>

{braindecode-1.5.0.dev172791986 → braindecode-1.5.0.dev176208946}/braindecode/models/__init__.py

@@ -4,7 +4,7 @@ from .atcnet import ATCNet
 from .attentionbasenet import AttentionBaseNet
 from .attn_sleep import AttnSleep
 from .base import EEGModuleMixin
-from .bendr import BENDR, InterpolatedBENDR
+from .bendr import BENDR
 from .biot import BIOT, InterpolatedBIOT
 from .brainmodule import BrainModule
 from .cbramod import CBraMod
@@ -99,7 +99,6 @@ __all__ = [
     "FBMSNet",
     "HybridNet",
     "IFNet",
-    "InterpolatedBENDR",
     "InterpolatedBIOT",
     "InterpolatedLaBraM",
     "InterpolatedModel",

{braindecode-1.5.0.dev172791986 → braindecode-1.5.0.dev176208946}/braindecode/models/bendr.py

@@ -1,60 +1,12 @@
 import copy
 
-import numpy as np
 import torch
 from einops.layers.torch import Rearrange
 from torch import nn
+from torch.nn.utils.parametrize import register_parametrization
 
 from braindecode.models.base import EEGModuleMixin
-
-# The 20 channels used to pre-train BENDR, in the order expected by the
-# `braindecode/braindecode-bendr` checkpoint. The first 19 entries are the
-# EEG channels taken verbatim from `dn3.transforms.instance.To1020.EEG_20_div`
-# (https://github.com/SPOClab-ca/dn3/blob/master/dn3/transforms/instance.py).
-# Their positions come from MNE's ``standard_1005`` montage (T5/T6 are
-# legacy names that share positions with P7/P8 there).
-#
-# The 20th entry is ``SCALE``, a relative-amplitude statistic (not an
-# electrode) appended by ``To1020(include_scale_ch=True)`` during
-# pre-training. Since it has no physical position, the ``loc`` below is
-# the centroid of the 19 EEG positions — purely a placeholder so that
-# :class:`~braindecode.modules.ChannelInterpolationLayer` (used by
-# :class:`InterpolatedBENDR`) can build a valid spline interpolation
-# matrix. It is NOT the SCALE the pre-training pipeline computes
-# (which is an RMS-like amplitude via ``dn3.MappingDeep1010``); users
-# who need a faithful SCALE must compute it themselves and feed 20
-# channels to :class:`BENDR` directly.
-_BENDR_TARGET_CHS_TUPLES: list[tuple[str, tuple[float, float, float]]] = [
-    ("FP1", (-0.0294367, +0.0839171, -0.0069900)),  # standard_1005
-    ("FP2", (+0.0298723, +0.0848959, -0.0070800)),  # standard_1005
-    ("F7", (-0.0702629, +0.0424743, -0.0114200)),  # standard_1005
-    ("F3", (-0.0502438, +0.0531112, +0.0421920)),  # standard_1005
-    ("FZ", (+0.0003122, +0.0585120, +0.0664620)),  # standard_1005
-    ("F4", (+0.0518362, +0.0543048, +0.0408140)),  # standard_1005
-    ("F8", (+0.0730431, +0.0444217, -0.0120000)),  # standard_1005
-    ("T7", (-0.0841611, -0.0160187, -0.0093460)),  # standard_1005
-    ("C3", (-0.0653581, -0.0116317, +0.0643580)),  # standard_1005
-    ("CZ", (+0.0004009, -0.0091670, +0.1002440)),  # standard_1005
-    ("C4", (+0.0671179, -0.0109003, +0.0635800)),  # standard_1005
-    ("T8", (+0.0850799, -0.0150203, -0.0094900)),  # standard_1005
-    ("T5", (-0.0724343, -0.0734527, -0.0024870)),  # standard_1005 (= P7)
-    ("P3", (-0.0530073, -0.0787878, +0.0559400)),  # standard_1005
-    ("PZ", (+0.0003247, -0.0811150, +0.0826150)),  # standard_1005
-    ("P4", (+0.0556667, -0.0785602, +0.0565610)),  # standard_1005
-    ("T6", (+0.0730557, -0.0730683, -0.0025400)),  # standard_1005 (= P8)
-    ("O1", (-0.0294134, -0.1124490, +0.0088390)),  # standard_1005
-    ("O2", (+0.0298426, -0.1121560, +0.0088000)),  # standard_1005
-    (
-        "SCALE",
-        (+0.0006439, -0.0131942, +0.0278448),
-    ),  # centroid of the 19 EEG positions (placeholder; see comment above)
-]
-
-_BENDR_TARGET_CHS_INFO: list[dict] = [
-    {"ch_name": ch, "kind": "eeg", "loc": np.asarray(loc, dtype=float)}
-    for ch, loc in _BENDR_TARGET_CHS_TUPLES
-]
-BENDR_CHANNEL_ORDER: list[str] = [ch for ch, _ in _BENDR_TARGET_CHS_TUPLES]
+from braindecode.modules.parametrization import MaxNormParametrize
 
 
 class BENDR(EEGModuleMixin, nn.Module):
@@ -243,6 +195,15 @@ class BENDR(EEGModuleMixin, nn.Module):
         The contextualizer is still created (to allow loading pretrained weights) but is not
         used in the forward pass. Requires input length of at least
         ``4 * product(enc_downsample)`` samples (384 with default downsampling of 96x).
+    n_chans_pretrained : int or None, default=None
+        Number of input channels the pretrained weights expect (20 for the official BENDR
+        checkpoint). When set and ``n_chans != n_chans_pretrained``, a 1x1 Conv1d with
+        max-norm constraint projects from ``n_chans`` to ``n_chans_pretrained`` before the
+        encoder. This allows fine-tuning pretrained BENDR on datasets with arbitrary channel
+        counts. When using ``from_pretrained``, pass ``strict=False`` since the checkpoint
+        will not contain ``channel_projection`` weights.
+    chan_proj_max_norm : float, default=1.0
+        Max-norm constraint value for the channel projection weights.
     """
 
     def __init__(
@@ -270,6 +231,8 @@ class BENDR(EEGModuleMixin, nn.Module):
         start_token=-5,  # Value for start token embedding
         final_layer=True,  # Whether to include the final linear layer
         encoder_only=False,  # If True, bypass contextualizer and use 4-chunk pooling
+        n_chans_pretrained=None,  # Expected input channels of pretrained weights
+        chan_proj_max_norm=1.0,  # Max-norm for channel projection weights
     ):
         super().__init__(
             n_outputs=n_outputs,
@@ -283,34 +246,25 @@ class BENDR(EEGModuleMixin, nn.Module):
         # Keep these parameters if needed later, otherwise they are captured by the mixin
         del n_outputs, n_chans, chs_info, n_times, input_window_seconds, sfreq
 
-        # If the user supplies chs_info, require it to match BENDR_CHANNEL_ORDER
-        # exactly (case-insensitive). Arbitrary channel sets should go through
-        # InterpolatedBENDR — same pattern as Labram / InterpolatedLaBraM.
-        # When chs_info is absent (the usual n_chans=20 path, incl.
-        # from_pretrained), no check is performed.
-        try:
-            _chs_info = self.chs_info
-        except ValueError:
-            _chs_info = None
-        if _chs_info is not None:
-            user_names = [ch["ch_name"] for ch in _chs_info]  # type: ignore[index]
-            canonical = BENDR_CHANNEL_ORDER
-            if [n.lower() for n in user_names] != [n.lower() for n in canonical]:
-                raise ValueError(
-                    f"BENDR requires chs_info to match BENDR_CHANNEL_ORDER exactly "
-                    f"({len(canonical)} channels, specific order; last is 'SCALE'). "
-                    f"Got {len(user_names)} channel(s). For arbitrary channel sets, "
-                    f"use InterpolatedBENDR "
-                    f"(from braindecode.models import InterpolatedBENDR)."
-                )
-
         self.encoder_h = encoder_h
         self.contextualizer_hidden = contextualizer_hidden
         self.include_final_layer = final_layer
         self.encoder_only = encoder_only
 
+        # Channel projection for pretrained weight compatibility
+        encoder_n_chans = self.n_chans
+        if n_chans_pretrained is not None and self.n_chans != n_chans_pretrained:
+            conv = nn.Conv1d(self.n_chans, n_chans_pretrained, 1, bias=False)
+            register_parametrization(
+                conv, "weight", MaxNormParametrize(chan_proj_max_norm)
+            )
+            self.channel_projection = conv
+            encoder_n_chans = n_chans_pretrained
+        else:
+            self.channel_projection = None
+
         self.encoder = _ConvEncoderBENDR(
-            in_features=self.n_chans,
+            in_features=encoder_n_chans,
             encoder_h=encoder_h,
             dropout=drop_prob,
             projection_head=projection_head,
@@ -354,6 +308,8 @@ class BENDR(EEGModuleMixin, nn.Module):
         self._build_head(n_outputs)
 
     def forward(self, x, return_features=False):
+        if self.channel_projection is not None:
+            x = self.channel_projection(x)
         encoded = self.encoder(x)
         # encoded: [batch_size, encoder_h, n_encoded_times]
 
@@ -596,23 +552,3 @@ class _BENDRContextualizer(nn.Module):
         # x: [batch_size, in_features, seq_len + 1]
 
         return x
-
-
-# -----------------------------------------------------------------------------
-# InterpolatedBENDR — experimental channel-interpolation variant of BENDR
-# -----------------------------------------------------------------------------
-# Wraps :class:`BENDR` with an MNE-backed channel-interpolation layer that
-# projects arbitrary user ``chs_info`` to the canonical 20-channel BENDR
-# input (:data:`_BENDR_TARGET_CHS_INFO` — the 19 pre-training EEG channels
-# plus a ``SCALE`` placeholder at the centroid of those 19 positions).
-# Frozen by default; set ``trainable=True`` to fine-tune the projection.
-#
-# NOTE: the ``SCALE`` target has no physical position, so the row of the
-# interpolation matrix that produces it is a spatial spline of the user's
-# EEG channels — *not* the dn3 ``MappingDeep1010`` RMS statistic the
-# checkpoint saw during pre-training. Expect degraded zero-shot transfer
-# from the SCALE channel; downstream fine-tuning should still work.
-
-from braindecode.models.interpolated import InterpolatedModel  # noqa: E402
-
-InterpolatedBENDR = InterpolatedModel(BENDR, _BENDR_TARGET_CHS_INFO)

{braindecode-1.5.0.dev172791986 → braindecode-1.5.0.dev176208946}/braindecode/models/summary.csv

@@ -49,7 +49,6 @@ LUNA,General,"Classification,Embedding",128,"n_chans, n_times, sfreq, chs_info",
 MEDFormer,General,Classification,250,"n_chans, n_outputs, n_times",5313924,"MEDFormer(n_chans=22, n_outputs=4, n_times=1000)","Foundation Model,Convolution"
 REVE,General,Classification,200,"n_outputs, n_times, n_chans",69481476,"REVE(n_times=1000, n_outputs=4, n_chans=19)","Foundation Model,Attention/Transformer"
 DGCNN,Emotion Recognition,Classification,128,"n_chans, n_outputs, n_times, chs_info",1037385,"DGCNN(n_chans=62, n_outputs=4, n_times=128)","Graph Neural Network,Channel"
-InterpolatedBENDR,General,"Classification,Embedding",250,"chs_info, n_outputs, n_times",157143101,"InterpolatedBENDR(chs_info=<user>, n_outputs=4, n_times=1000)","Foundation Model,Convolution,Channel"
 InterpolatedBIOT,"Sleep Staging, Epilepsy",Classification,200,"chs_info, n_outputs, n_times, sfreq",3184101,"InterpolatedBIOT(chs_info=<user>, n_outputs=5, sfreq=200, n_times=6000)","Foundation Model,Channel"
 InterpolatedLaBraM,General,"Classification, Embedding",200,"chs_info, n_outputs, n_times",5866196,"InterpolatedLaBraM(chs_info=<user>, n_outputs=4, n_times=1000)","Convolution,Foundation Model,Channel"
 InterpolatedSignalJEPA,"Motor Imagery, ERP, SSVEP",Embedding,128,"chs_info",3456882,"InterpolatedSignalJEPA(chs_info=<user>)","Convolution,Channel,Foundation Model"

{braindecode-1.5.0.dev172791986 → braindecode-1.5.0.dev176208946}/braindecode/models/util.py

@@ -240,28 +240,6 @@ def _get_labram_chs_info() -> list[dict]:
     return result
 
 
-def _get_bendr_chs_info() -> list[dict]:
-    """Return the 20-channel canonical chs_info for BENDR with 12-element locs.
-
-    Same lazy-import rationale as :func:`_get_labram_chs_info`. The last entry
-    is the ``SCALE`` amplitude-statistic placeholder (see
-    ``braindecode.models.bendr``).
-    """
-    import numpy as np
-
-    from braindecode.models.bendr import _BENDR_TARGET_CHS_INFO
-
-    result = []
-    for ch in _BENDR_TARGET_CHS_INFO:
-        loc3 = np.asarray(ch["loc"], dtype=float)
-        loc12 = np.zeros(12, dtype=float)
-        loc12[:3] = loc3[:3]
-        result.append(
-            {"ch_name": ch["ch_name"], "kind": ch["kind"], "loc": loc12.tolist()}
-        )
-    return result
-
-
 models_mandatory_parameters: list[
     tuple[str, list[SigArgName], dict[SigArgName, Any] | None | Any]
 ] = [
@@ -341,19 +319,7 @@ models_mandatory_parameters: list[
     ("PBT", ["n_chans", "n_outputs", "n_times"], None),
     ("SSTDPN", ["n_chans", "n_outputs", "n_times", "sfreq"], None),
     ("BrainModule", ["n_chans", "n_outputs", "n_times", "sfreq"], None),
-    (
-        "BENDR",
-        ["n_chans", "n_outputs", "n_times"],
-        # Callable: BENDR now requires chs_info to match BENDR_CHANNEL_ORDER
-        # when supplied; deferred to avoid a circular import (util.py is loaded
-        # by base.py before bendr.py).
-        lambda: {"chs_info": _get_bendr_chs_info()},
-    ),
-    (
-        "InterpolatedBENDR",
-        ["chs_info", "n_outputs", "n_times"],
-        {"chs_info": _chs_info_4ch},  # MNE interpolation needs >=4 channels
-    ),
+    ("BENDR", ["n_chans", "n_outputs", "n_times"], None),
     ("LUNA", ["n_chans", "n_times", "n_outputs"], None),
     ("MEDFormer", ["n_chans", "n_outputs", "n_times"], None),
     (

braindecode-1.5.0.dev176208946/braindecode/version.py

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

{braindecode-1.5.0.dev172791986 → braindecode-1.5.0.dev176208946/braindecode.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: braindecode
-Version: 1.5.0.dev172791986
+Version: 1.5.0.dev176208946
 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>

{braindecode-1.5.0.dev172791986 → braindecode-1.5.0.dev176208946}/docs/api.rst

@@ -157,7 +157,6 @@ interface for all EEG models and can derive variable names when needed.
      FBLightConvNet
      FBMSNet
      IFNet
-     InterpolatedBENDR
      InterpolatedBIOT
      InterpolatedLaBraM
      InterpolatedModel

{braindecode-1.5.0.dev172791986 → braindecode-1.5.0.dev176208946}/docs/whats_new.rst

@@ -48,14 +48,6 @@ Enhancements
   :class:`braindecode.models.InterpolatedSignalJEPA`, and
   :class:`braindecode.models.InterpolatedBIOT` for the corresponding
   pre-trained models. (:gh:`993` by `Pierre Guetschel`_)
-- Add a tutorial walking through the experimental ``Interpolated*`` family
-  (:ref:`channel-interpolation-tutorial`): failure mode of the vanilla
-  backbones on non-canonical channel sets, one-line fix via
-  :class:`braindecode.models.InterpolatedLaBraM` /
-  :class:`braindecode.models.InterpolatedBIOT` /
-  :class:`braindecode.models.InterpolatedSignalJEPA`, side-by-side
-  visualisation of the ``name_match`` vs ``always`` interpolation matrices,
-  and the ``trainable=True`` flag. (:gh:`994` by `Pierre Guetschel`_)
 - Mark deterministic index buffers (:class:`braindecode.models.BIOT` encoder's
   ``index`` and :class:`braindecode.models.REVE`'s position ``embedding`` bank)
   as non-persistent. They are rebuilt from ``__init__`` arguments on every
@@ -70,17 +62,6 @@ API and behavior changes
   convention: boolean masks use ``True`` to **ignore** a position (previously
   ``True`` meant keep). The scaling factor is now ``1/sqrt(head_dim)`` instead of
   ``1/sqrt(emb_size)``. (:gh:`902`)
-- :class:`braindecode.models.BENDR`: remove the ``n_chans_pretrained`` /
-  ``chan_proj_max_norm`` parameters and the ``channel_projection`` layer; hard-code
-  the 20 pre-training channels as ``_BENDR_TARGET_CHS_TUPLES``. The official
-  ``braindecode/braindecode-bendr`` checkpoint has been re-uploaded flat so
-  ``from_pretrained`` now loads its 99 weights (previously 0 of 99 matched
-  silently). Also ships :class:`braindecode.models.InterpolatedBENDR`, the
-  :func:`~braindecode.models.InterpolatedModel` wrapper that accepts arbitrary
-  user ``chs_info`` and projects to the canonical 20 BENDR channels (the
-  ``SCALE`` target has no physical position, so its interpolation row is a
-  spatial spline of the user's EEG — not the dn3 amplitude statistic).
-  (:gh:`992` by `Pierre Guetschel`_)
 - :class:`braindecode.models.Labram` now requires ``chs_info`` to match
   ``LABRAM_CHANNEL_ORDER`` exactly (128 channels, canonical order). The
   ``on_unknown_chs`` parameter and the forward-time ``ch_names`` argument are

braindecode-1.5.0.dev172791986/braindecode/version.py

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