Braindecode 1.3.2.dev172702163__tar.gz → 1.3.2.dev173417708__tar.gz

{braindecode-1.3.2.dev172702163/braindecode.egg-info → braindecode-1.3.2.dev173417708}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: braindecode
-Version: 1.3.2.dev172702163
+Version: 1.3.2.dev173417708
 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.3.2.dev172702163 → braindecode-1.3.2.dev173417708}/braindecode/datasets/mne.py

@@ -100,6 +100,11 @@ def create_from_mne_epochs(
     window_size_samples: int,
     window_stride_samples: int,
     drop_last_window: bool,
+    descriptions: list[dict | pd.Series] | None = None,
+    mapping: dict[str | int, int] | None = None,
+    preload: bool = False,
+    picks: str | list | slice | None = None,
+    drop_bad_windows: bool = True,
 ) -> BaseConcatDataset:
     """Create WindowsDatasets from mne.Epochs.
 
@@ -114,6 +119,25 @@ def create_from_mne_epochs(
     drop_last_window : bool
         whether or not have a last overlapping window, when
         windows do not equally divide the continuous signal
+    descriptions : array-like | None
+        list of dicts or pandas.Series with additional information about
+        the epochs. If None, no description is added. Length must match
+        ``list_of_epochs``. Each description is applied to all windows
+        generated from the corresponding Epochs object.
+    mapping : dict(str | int: int) | None
+        Mapping from event description to target value. Keys can be
+        integers (matching ``epochs.events[:, 2]``) or their string
+        representations. If None, targets are set to the raw integer
+        event codes. If a mapping is provided and an event code is not
+        found in the mapping, the original event code is kept as-is.
+    preload : bool
+        if True, preload the data of the Epochs objects.
+    picks : str | list | slice | None
+        channels to include. If None, all available channels are used.
+    drop_bad_windows : bool
+        If True, call `.drop_bad()` on the resulting mne.Epochs object.
+        This allows identifying windows that fall outside of the valid
+        signal range. Defaults to True.
 
     Returns
     -------
@@ -126,8 +150,15 @@ def create_from_mne_epochs(
 
     _check_windowing_arguments(0, 0, window_size_samples, window_stride_samples)
 
+    if descriptions is not None:
+        if len(descriptions) != len(list_of_epochs):
+            raise ValueError(
+                f"length of 'list_of_epochs' ({len(list_of_epochs)}) and "
+                f"'descriptions' ({len(descriptions)}) has to match"
+            )
+
     list_of_windows_ds = []
-    for epochs in list_of_epochs:
+    for i, epochs in enumerate(list_of_epochs):
         event_descriptions = epochs.events[:, 2]
         original_trial_starts = epochs.events[:, 0]
         stop = len(epochs.times) - window_size_samples
@@ -142,6 +173,15 @@ def create_from_mne_epochs(
         fake_events = [[start, window_size_samples, -1] for start in starts]
 
         for trial_i, trial in enumerate(epochs):
+            # resolve target using mapping if provided
+            event_code = event_descriptions[trial_i]
+            if mapping is not None:
+                target = mapping.get(
+                    event_code, mapping.get(str(event_code), event_code)
+                )
+            else:
+                target = event_code
+
             metadata = pd.DataFrame(
                 {
                     "i_window_in_trial": np.arange(len(fake_events)),
@@ -149,7 +189,7 @@ def create_from_mne_epochs(
                     "i_stop_in_trial": starts
                     + original_trial_starts[trial_i]
                     + window_size_samples,
-                    "target": len(fake_events) * [event_descriptions[trial_i]],
+                    "target": len(fake_events) * [target],
                 }
             )
             # window size - 1, since tmax is inclusive
@@ -160,11 +200,15 @@ def create_from_mne_epochs(
                 tmin=0,
                 tmax=(window_size_samples - 1) / epochs.info["sfreq"],
                 metadata=metadata,
+                preload=preload,
+                picks=picks,
             )
 
-            mne_epochs.drop_bad(reject=None, flat=None)
+            if drop_bad_windows:
+                mne_epochs.drop_bad(reject=None, flat=None)
 
-            windows_ds = WindowsDataset(mne_epochs)
+            desc = descriptions[i] if descriptions is not None else None
+            windows_ds = WindowsDataset(mne_epochs, description=desc)
             list_of_windows_ds.append(windows_ds)
 
     return BaseConcatDataset(list_of_windows_ds)

{braindecode-1.3.2.dev172702163 → braindecode-1.3.2.dev173417708}/braindecode/preprocessing/windowers.py

@@ -12,6 +12,7 @@
 #          Mohammed Fattouh <mo.fattouh@gmail.com>
 #          Robin Schirrmeister <robintibor@gmail.com>
 #          Matthew Chen <matt.chen42601@gmail.com>
+#          Sarthak Tayal <sarthaktayal2@gmail.com>
 #
 # License: BSD (3-clause)
 
@@ -417,6 +418,7 @@ def create_fixed_length_windows(
     drop_last_window: bool | None = None,
     mapping: dict[str, int] | None = None,
     preload: bool = False,
+    drop_bad_windows: bool | None = None,
     picks: str | ArrayLike | slice | None = None,
     reject: dict[str, float] | None = None,
     flat: dict[str, float] | None = None,
@@ -424,9 +426,10 @@ def create_fixed_length_windows(
     last_target_only: bool = True,
     lazy_metadata: bool = False,
     on_missing: str = "error",
+    use_mne_epochs: bool | None = None,
     n_jobs: int = 1,
     verbose: bool | str | int | None = "error",
-) -> BaseConcatDataset[EEGWindowsDataset]:
+) -> BaseConcatDataset[WindowsDataset | EEGWindowsDataset]:
     """Windower that creates sliding windows.
 
     Parameters
@@ -452,6 +455,12 @@ def create_fixed_length_windows(
         Mapping from event description to target value.
     preload: bool
         If True, preload the data of the Epochs objects.
+    drop_bad_windows: bool | None
+        If True, call `.drop_bad()` on the resulting mne.Epochs object. This
+        step allows identifying e.g., windows that fall outside of the
+        continuous recording. It is suggested to run this step here as otherwise
+        the BaseConcatDataset has to be updated as well. Only has an effect if
+        mne Epochs are created (i.e. ``use_mne_epochs=True``).
     picks: str | list | slice | None
         Channels to include. If None, all available channels are used. See
         mne.Epochs.
@@ -463,10 +472,20 @@ def create_fixed_length_windows(
         rejection based on flatness is done. See mne.Epochs.
     lazy_metadata: bool
         If True, metadata is not computed immediately, but only when accessed
-        by using the _LazyDataFrame (experimental).
+        by using the _LazyDataFrame (experimental). Cannot be used together
+        with ``use_mne_epochs=True``.
     on_missing: str
         What to do if one or several event ids are not found in the recording.
         Valid keys are ‘error' | ‘warning' | ‘ignore'. See mne.Epochs.
+    use_mne_epochs: bool | None
+        If False, return EEGWindowsDataset objects.
+        If True, return mne.Epochs objects encapsulated in WindowsDataset
+        objects, which is substantially slower than EEGWindowsDataset.
+        If None, it will be inferred from the other parameters: True if any
+        of ``reject``, ``picks``, or ``flat`` is set, or if
+        ``drop_bad_windows`` is True; False otherwise. If ``use_mne_epochs``
+        is inferred as True and ``drop_bad_windows`` is None, it is treated
+        as True.
     n_jobs: int
         Number of jobs to use to parallelize the windowing.
     verbose: bool | str | int | None
@@ -474,8 +493,10 @@ def create_fixed_length_windows(
 
     Returns
     -------
-    windows_datasets: BaseConcatDataset[EEGWindowsDataset]
-        Concatenated datasets of WindowsDataset containing the extracted windows.
+    windows_datasets: BaseConcatDataset[WindowsDataset | EEGWindowsDataset]
+        Concatenated dataset containing either WindowsDataset or
+        EEGWindowsDataset objects with the extracted windows, depending on
+        the value of ``use_mne_epochs``.
     """
     stop_offset_samples, drop_last_window = (
         _check_and_set_fixed_length_window_arguments(
@@ -488,6 +509,20 @@ def create_fixed_length_windows(
         )
     )
 
+    if drop_bad_windows is not None:
+        warnings.warn(
+            "Drop bad windows only has an effect if mne epochs are created, "
+            "and this argument may be removed in the future."
+        )
+
+    use_mne_epochs = _get_use_mne_epochs(
+        use_mne_epochs, reject, picks, flat, drop_bad_windows
+    )
+    if use_mne_epochs and drop_bad_windows is None:
+        drop_bad_windows = True
+    if use_mne_epochs and lazy_metadata:
+        raise ValueError("Cannot use lazy_metadata=True with use_mne_epochs=True.")
+
     # check if recordings are of different lengths
     lengths = np.array([ds.raw.n_times for ds in concat_ds.datasets])
     if (np.diff(lengths) != 0).any() and window_size_samples is None:
@@ -507,6 +542,7 @@ def create_fixed_length_windows(
             drop_last_window,
             mapping,
             preload,
+            drop_bad_windows,
             picks,
             reject,
             flat,
@@ -514,6 +550,7 @@ def create_fixed_length_windows(
             last_target_only,
             lazy_metadata,
             on_missing,
+            use_mne_epochs,
             verbose,
         )
         for ds in concat_ds.datasets
@@ -805,6 +842,7 @@ def _create_fixed_length_windows(
     drop_last_window,
     mapping=None,
     preload=False,
+    drop_bad_windows=True,
     picks=None,
     reject=None,
     flat=None,
@@ -812,6 +850,7 @@ def _create_fixed_length_windows(
     last_target_only=True,
     lazy_metadata=False,
     on_missing="error",
+    use_mne_epochs=False,
     verbose="error",
 ):
     """Create WindowsDataset from RawDataset with sliding windows.
@@ -894,19 +933,52 @@ def _create_fixed_length_windows(
             }
         )
 
-    window_kwargs.append(
-        (
-            EEGWindowsDataset.__name__,
-            {"targets_from": targets_from, "last_target_only": last_target_only},
+    if use_mne_epochs:
+        # Construct synthetic events for mne.Epochs
+        events = np.column_stack(
+            [
+                starts + ds.raw.first_samp,
+                np.zeros(len(starts), dtype=int),
+                np.ones(len(starts), dtype=int),
+            ]
+        )
+        events_id = {"window": 1}
+        # window size - 1, since tmax is inclusive
+        mne_epochs = mne.Epochs(
+            ds.raw,
+            events,
+            events_id,
+            baseline=None,
+            tmin=0,
+            tmax=(window_size_samples - 1) / ds.raw.info["sfreq"],
+            metadata=metadata,
+            preload=preload,
+            picks=picks,
+            reject=reject,
+            flat=flat,
+            on_missing=on_missing,
+            verbose=verbose,
+        )
+        if drop_bad_windows:
+            mne_epochs.drop_bad()
+        windows_ds = WindowsDataset(
+            mne_epochs,
+            ds.description,
+        )
+    else:
+        window_kwargs.append(
+            (
+                EEGWindowsDataset.__name__,
+                {"targets_from": targets_from, "last_target_only": last_target_only},
+            )
+        )
+        windows_ds = EEGWindowsDataset(
+            ds.raw,
+            metadata=metadata,
+            description=ds.description,
+            targets_from=targets_from,
+            last_target_only=last_target_only,
         )
-    )
-    windows_ds = EEGWindowsDataset(
-        ds.raw,
-        metadata=metadata,
-        description=ds.description,
-        targets_from=targets_from,
-        last_target_only=last_target_only,
-    )
     # add window_kwargs and raw_preproc_kwargs to windows dataset
     setattr(windows_ds, "window_kwargs", window_kwargs)
     kwargs_name = "raw_preproc_kwargs"
@@ -974,8 +1046,12 @@ def _create_windows_from_target_channels(
     stop = ds.raw.n_times + ds.raw.first_samp
 
     target = ds.raw.get_data(picks="misc")
-    # TODO: handle multi targets present only for some events
-    stops = np.nonzero((~np.isnan(target[0, :])))[0] + 1
+
+    # check all misc channels for valid targets, not just the first one.
+    # when multiple target channels exist, some may have values at timepoints
+    # where others are nan. using any() across channels catches all of them.
+    has_target = np.any(~np.isnan(target), axis=0)
+    stops = np.nonzero(has_target)[0] + 1
     stops = stops[(stops < stop) & (stops >= window_size_samples)]
     stops = stops.astype(int)
     metadata = pd.DataFrame(

braindecode-1.3.2.dev173417708/braindecode/version.py

@@ -0,0 +1 @@
+__version__ = "1.3.2.dev173417708"

{braindecode-1.3.2.dev172702163 → braindecode-1.3.2.dev173417708}/braindecode/visualization/gradients.py

@@ -1,4 +1,5 @@
 # Authors: Robin Schirrmeister <robintibor@gmail.com>
+#          Sarthak Tayal <sarthaktayal2@gmail.com>
 #
 # License: BSD (3-clause)
 
@@ -35,18 +36,17 @@ def compute_amplitude_gradients_for_X(model, X):
     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)
 
-    try:
-        complex_fft_coefs = torch.view_as_complex(fft_coefs)
-        iffted = torch.fft.irfft(complex_fft_coefs, n=X.shape[2], dim=2)
-    except AttributeError:
-        iffted = torch.irfft(  # Deprecated since 1.7
-            fft_coefs, signal_ndim=1, signal_sizes=(X.shape[2],)
-        )
+    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)
 

{braindecode-1.3.2.dev172702163 → braindecode-1.3.2.dev173417708/braindecode.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: braindecode
-Version: 1.3.2.dev172702163
+Version: 1.3.2.dev173417708
 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.3.2.dev172702163 → braindecode-1.3.2.dev173417708}/docs/whats_new.rst

@@ -48,7 +48,12 @@ Enhancements
   frequency, duration/window size, channel names, description summary, and
   epoch-level metadata including target distribution and extra metadata columns
   (signal-level details marked ``*`` are taken from the first recording).
+- Add ``mapping``, ``preload``, ``picks``, ``drop_bad_windows``, and ``descriptions``
+  parameters to :func:`braindecode.datasets.mne.create_from_mne_epochs` to bring it to
+  parity with :func:`braindecode.datasets.mne.create_from_mne_raw`
+  (:gh:`941` by `Aman Srivastava`_).
 - Per-event-type windowing parameters in :func:`braindecode.preprocessing.windowers.create_windows_from_events` (:gh:`942` by `Pierre Guetschel`_)
+- Add ``use_mne_epochs`` support to :func:`braindecode.preprocessing.windowers.create_fixed_length_windows` (:gh:`943` by `Pierre Guetschel`_)
 
 API changes
 ============
@@ -60,6 +65,9 @@ Requirements
 
 Bugs
 =====
+- Fix multi-target channel windowing in :func:`braindecode.preprocessing.windowers.create_windows_from_target_channels`
+  to use the union of valid target positions across all misc channels instead of only the first channel
+  (by `Sarthak Tayal`_)
 - Fix :func:`braindecode.preprocessing.preprocess.filterbank` to preserve info fields
   (``description``, ``line_freq``, ``device_info``, etc.) when creating filtered copies,
   avoiding merge conflicts in MNE when adding channels (:gh:`928` by `Bruno Aristimunha`_)
@@ -71,7 +79,9 @@ Bugs
 
 Code health
 ============
-- None yet.
+- Remove deprecated ``torch.irfft`` fallback in :func:`braindecode.visualization.gradients.compute_amplitude_gradients_for_X`,
+  now uses ``torch.fft.irfft`` directly since braindecode requires ``torch>=2.2``
+  (by `Sarthak Tayal`_)
 
 
 Current 1.3.2 (stable)
@@ -818,3 +828,5 @@ Authors
 .. _Thorir Mar Ingolfsson: https://github.com/Thoriri
 .. _Aniela Bulicz: https://github.com/AryaDro
 .. _Mattew Chew: https://github.com/MatthewChen37
+.. _Aman Srivastava: https://github.com/aman-coder03
+.. _Sarthak Tayal: https://github.com/tayal-sarthak

braindecode-1.3.2.dev172702163/braindecode/version.py

@@ -1 +0,0 @@
-__version__ = "1.3.2.dev172702163"