pyprep 0.6.0__tar.gz → 0.7.0__tar.gz

{pyprep-0.6.0 → pyprep-0.7.0}/.gitignore

@@ -1,3 +1,6 @@
+.claude
+CLAUDE.md
+
 .vscode
 .idea/*
 /idea

{pyprep-0.6.0 → pyprep-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyprep
-Version: 0.6.0
+Version: 0.7.0
 Summary: PyPREP: A Python implementation of the preprocessing pipeline (PREP) for EEG data.
 Project-URL: Bug Tracker, https://github.com/sappelhoff/pyprep/issues/
 Project-URL: Documentation, https://pyprep.readthedocs.io/en/latest
@@ -42,6 +42,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering
 Requires-Python: >=3.10
 Requires-Dist: mne>=1.3.0

{pyprep-0.6.0 → pyprep-0.7.0}/pyprep/find_noisy_channels.py

@@ -175,7 +175,7 @@ class NoisyChannels:
         ch_names = np.asarray(self.raw_mne.info["ch_names"])
         self.ch_names_original = ch_names
         self.n_chans_original = len(ch_names)
-        self.n_samples_original = raw.get_data().shape[1]
+        self.n_samples_original = raw.n_times
 
         # Before anything else, flag bad-by-NaNs and bad-by-flats
         self.find_bad_by_nan_flat()
@@ -378,7 +378,9 @@ class NoisyChannels:
 
         This method is run automatically when a ``NoisyChannels`` object is
         initialized, preventing flat or NaN-containing channels from interfering
-        with the detection of other types of bad channels.
+        with the detection of other types of bad channels. The
+        ``reject_by_annotation`` setting of the :class:`NoisyChannels` instance
+        is respected when retrieving the data.
 
         Parameters
         ----------
@@ -388,7 +390,7 @@ class NoisyChannels:
             10e-10 µV in MATLAB PREP).
         """
         # Get all EEG channels from original copy of data
-        EEGData = self.raw_mne.get_data()
+        EEGData = self.raw_mne.get_data(reject_by_annotation=self.reject_by_annotation)
 
         # Detect channels containing any NaN values
         nan_channel_mask = np.isnan(np.sum(EEGData, axis=1))
@@ -638,6 +640,7 @@ class NoisyChannels:
         This is a PyPREP-only method not present in the original MATLAB PREP.
 
         A channel is considered "bad-by-psd" if:
+
         1. Its power in any frequency band (low: 1-15 Hz, mid: 15-30 Hz,
            high: 30-45 Hz) is abnormally HIGH compared to other channels, OR
         2. Its high-frequency band has more power than its low-frequency band

{pyprep-0.6.0 → pyprep-0.7.0}/pyprep/prep_pipeline.py

@@ -3,12 +3,13 @@
 # Authors: The PyPREP developers
 # SPDX-License-Identifier: MIT
 
+import warnings
+
 import mne
 from mne.utils import check_random_state
 
 from pyprep.reference import Reference
 from pyprep.removeTrend import removeTrend
-from pyprep.utils import _set_diff, _union  # noqa: F401
 
 
 class PrepPipeline:
@@ -182,6 +183,18 @@ class PrepPipeline:
         self.filter_kwargs = filter_kwargs
         self.matlab_strict = matlab_strict
 
+        # Initialize attributes to be filled in later
+        self._line_noise_removed = False
+        self.noisy_channels_original = None
+        self.noisy_channels_before_interpolation = None
+        self.noisy_channels_after_interpolation = None
+        self.bad_before_interpolation = None
+        self.EEG_before_interpolation = None
+        self.reference_before_interpolation = None
+        self.reference_after_interpolation = None
+        self.interpolated_channels = None
+        self.still_noisy_channels = None
+
     @property
     def raw(self):
         """Return a version of self.raw_eeg that includes the non-eeg channels."""
@@ -191,39 +204,96 @@ class PrepPipeline:
         else:
             return full_raw.add_channels([self.raw_non_eeg], force_update_info=True)
 
-    def fit(self):
-        """Run the whole PREP pipeline."""
-        # Step 1: 1Hz high pass filtering
-        if len(self.prep_params["line_freqs"]) != 0:
-            self.EEG_new = removeTrend(
-                self.EEG_raw, self.sfreq, matlab_strict=self.matlab_strict
+    def remove_line_noise(self, line_freqs=None):
+        """Remove line noise from all EEG channels.
+
+        Line noise is removed by detrending the signal, applying a notch filter,
+        and adding the slow drifts back. By default the notch filter uses MNE's
+        ``spectrum_fit`` method, which attempts to isolate and remove line noise
+        while preserving unrelated background signal in the same frequency ranges
+        (to minimize distortions in the power-spectral density). The filter can be
+        configured via the ``filter_kwargs`` argument of :class:`PrepPipeline`.
+
+        Parameters
+        ----------
+        line_freqs : {np.ndarray, list, None}, optional
+            A list of the frequencies (in Hz) at which line noise should be removed
+            (e.g., ``np.arange(60, sfreq / 2, 60)`` for a recording with a powerline
+            noise of 60 Hz). If ``None`` (default), the ``"line_freqs"`` entry of the
+            ``prep_params`` passed to :class:`PrepPipeline` is used.
+
+        """
+        if line_freqs is None:
+            line_freqs = self.prep_params["line_freqs"]
+
+        # Remove slow drifts from the recording prior to filtering
+        self.EEG_new = removeTrend(
+            self.EEG_raw, self.sfreq, matlab_strict=self.matlab_strict
+        )
+
+        # Remove line noise. When no filter kwargs are given, fall back to PREP's
+        # default ``spectrum_fit`` settings; otherwise use the provided kwargs as-is.
+        if self.filter_kwargs is None:
+            self.EEG_clean = mne.filter.notch_filter(
+                self.EEG_new,
+                Fs=self.sfreq,
+                freqs=line_freqs,
+                method="spectrum_fit",
+                mt_bandwidth=2,
+                p_value=0.01,
+                filter_length="10s",
+            )
+        else:
+            self.EEG_clean = mne.filter.notch_filter(
+                self.EEG_new,
+                Fs=self.sfreq,
+                freqs=line_freqs,
+                **self.filter_kwargs,
+            )
+
+        # Add the slow drifts back
+        self.EEG = self.EEG_raw - self.EEG_new + self.EEG_clean
+        self.raw_eeg._data = self.EEG
+        self._line_noise_removed = True
+
+    def robust_reference(self, max_iterations=None, interpolate_bads=True):
+        """Perform robust referencing on the EEG signal and detect bad channels.
+
+        This method uses an iterative approach to estimate a robust average
+        reference signal free of contamination from bad channels, as detected
+        automatically using the methods of :class:`~pyprep.NoisyChannels`. Once
+        estimated, the robust average reference is applied to the data and bad
+        channel detection is re-run to flag any noisy or unusable channels
+        post-reference.
+
+        By default, this method will also interpolate the signals of any channels
+        detected as bad following robust referencing, re-reference the data
+        accordingly, and re-detect any remaining bad channels.
+
+        Parameters
+        ----------
+        max_iterations : {int, None}, optional
+            The maximum number of iterations of noisy channel removal to perform
+            during robust referencing. If ``None`` (default), the ``"max_iterations"``
+            entry of the ``prep_params`` passed to :class:`PrepPipeline` is used.
+        interpolate_bads : bool, optional
+            Whether or not any remaining bad channels following robust referencing
+            should be interpolated. Defaults to ``True``.
+
+        """
+        if max_iterations is None:
+            max_iterations = self.prep_params["max_iterations"]
+
+        if not self._line_noise_removed:
+            warnings.warn(
+                "Robust referencing is being performed without prior line-noise "
+                "removal. If this is intentional, you can safely ignore this "
+                "warning; otherwise, call `remove_line_noise` first or use `fit`.",
+                UserWarning,
+                stacklevel=2,
             )
 
-            # Step 2: Removing line noise
-            linenoise = self.prep_params["line_freqs"]
-            if self.filter_kwargs is None:
-                self.EEG_clean = mne.filter.notch_filter(
-                    self.EEG_new,
-                    Fs=self.sfreq,
-                    freqs=linenoise,
-                    method="spectrum_fit",
-                    mt_bandwidth=2,
-                    p_value=0.01,
-                    filter_length="10s",
-                )
-            else:
-                self.EEG_clean = mne.filter.notch_filter(
-                    self.EEG_new,
-                    Fs=self.sfreq,
-                    freqs=linenoise,
-                    **self.filter_kwargs,
-                )
-
-            # Add Trend back
-            self.EEG = self.EEG_raw - self.EEG_new + self.EEG_clean
-            self.raw_eeg._data = self.EEG
-
-        # Step 3: Referencing
+        # Perform robust referencing on the signal
         reference = Reference(
             self.raw_eeg,
             self.prep_params,
@@ -231,7 +301,8 @@ class PrepPipeline:
             matlab_strict=self.matlab_strict,
             **self.ransac_settings,
         )
-        reference.perform_reference(self.prep_params["max_iterations"])
+        reference.perform_reference(max_iterations, interpolate_bads)
+
         self.raw_eeg = reference.raw
         self.noisy_channels_original = reference.noisy_channels_original
         self.noisy_channels_before_interpolation = (
@@ -247,4 +318,17 @@ class PrepPipeline:
         self.interpolated_channels = reference.interpolated_channels
         self.still_noisy_channels = reference.still_noisy_channels
 
+    def fit(self):
+        """Run the whole PREP pipeline."""
+        # Step 1: Adaptive line noise removal
+        if len(self.prep_params["line_freqs"]) != 0:
+            self.remove_line_noise(self.prep_params["line_freqs"])
+        else:
+            # No line noise to remove: mark the stage as deliberately skipped so
+            # that `robust_reference` does not emit a spurious warning.
+            self._line_noise_removed = True
+
+        # Step 2: Robust Referencing
+        self.robust_reference(self.prep_params["max_iterations"])
+
         return self

{pyprep-0.6.0 → pyprep-0.7.0}/pyprep/reference.py

@@ -12,9 +12,6 @@ from pyprep.find_noisy_channels import NoisyChannels
 from pyprep.removeTrend import removeTrend
 from pyprep.utils import _eeglab_interpolate_bads, _set_diff, _union
 
-logging.basicConfig(
-    level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
-)
 logger = logging.getLogger(__name__)
 
 
@@ -102,42 +99,59 @@ class Reference:
             "reject_by_annotation": reject_by_annotation,
         }
         self.random_state = check_random_state(random_state)
-        self._extra_info = {}
         self.matlab_strict = matlab_strict
 
-    def perform_reference(self, max_iterations=4):
+        # Initialize attributes that get filled in during referencing
+        self.bad_before_interpolation = None
+        self.EEG_before_interpolation = None
+        self.noisy_channels_before_interpolation = None
+        self.reference_signal_new = None
+        self.interpolated_channels = None
+        self.still_noisy_channels = None
+        self.noisy_channels_after_interpolation = None
+        self._extra_info = {
+            "initial_bad": None,
+            "interpolated": None,
+            "remaining_bad": None,
+        }
+
+    def perform_reference(self, max_iterations=4, interpolate_bads=True):
         """Estimate the true signal mean and interpolate bad channels.
 
+        This function implements the functionality of the `performReference` function
+        as part of the PREP pipeline on mne raw object.
+
         Parameters
         ----------
         max_iterations : int | None
             The maximum number of iterations of noisy channel removal to perform
             during robust referencing. Defaults to ``4``.
-
-        This function implements the functionality of the `performReference` function
-        as part of the PREP pipeline on mne raw object.
+        interpolate_bads : bool, optional
+            Whether or not any remaining bad channels following robust referencing
+            should be interpolated or left as-is. Defaults to ``True``.
 
         Notes
         -----
         This function calls ``robust_reference`` first.
-        Currently this function only implements the functionality of default
-        settings, i.e., ``doRobustPost``.
 
         """
-        # Phase 1: Estimate the true signal mean with robust referencing
+        # Estimate the true signal mean with robust referencing
         self.robust_reference(max_iterations)
         # If we interpolate the raw here we would be interpolating
         # more than what we later actually account for (in interpolated channels).
         dummy = self.raw.copy()
         dummy.info["bads"] = self.noisy_channels["bad_all"]
-        if self.matlab_strict:
-            _eeglab_interpolate_bads(dummy)
-        else:
-            dummy.interpolate_bads()
+        if len(dummy.info["bads"]) > 0:
+            if self.matlab_strict:
+                _eeglab_interpolate_bads(dummy)
+            else:
+                dummy.interpolate_bads()
         self.reference_signal = np.nanmean(
             dummy.get_data(picks=self.reference_channels), axis=0
         )
         del dummy
+
+        # Re-reference the data using the calculated robust average reference
         rereferenced_index = [
             self.ch_names_eeg.index(ch) for ch in self.rereferenced_channels
         ]
@@ -145,7 +159,7 @@ class Reference:
             self.EEG, self.reference_signal, rereferenced_index
         )
 
-        # Phase 2: Find the bad channels and interpolate
+        # Detect which channels are still bad following robust referencing
         self.raw._data = self.EEG
         noisy_detector = NoisyChannels(
             self.raw,
@@ -154,33 +168,65 @@ class Reference:
             reject_by_annotation=self.ransac_settings.get("reject_by_annotation"),
         )
         noisy_detector.find_all_bads(**self.ransac_settings)
-
-        # Record Noisy channels and EEG before interpolation
         self.bad_before_interpolation = noisy_detector.get_bads(verbose=True)
         self.EEG_before_interpolation = self.EEG.copy()
         self.noisy_channels_before_interpolation = noisy_detector.get_bads(as_dict=True)
         self.noisy_channels_before_interpolation["bad_by_manual"] = self.bads_manual
         self._extra_info["interpolated"] = noisy_detector._extra_info
 
+        # Update bad channels in MNE raw object
         bad_channels = _union(self.bad_before_interpolation, self.unusable_channels)
         self.raw.info["bads"] = bad_channels
-        if self.matlab_strict:
-            _eeglab_interpolate_bads(self.raw)
-        else:
-            self.raw.interpolate_bads()
+
+        # If enabled, interpolate all bad channels and detect any remaining bads
+        if interpolate_bads:
+            self.interpolate_bads()
+
+        return self
+
+    def interpolate_bads(self):
+        """Interpolate any remaining bad channels following robust referencing.
+
+        This method can only be called if :meth:`~.perform_reference` has already
+        been run with the ``interpolate_bads`` parameter set to ``False``. It cannot
+        be run more than once per instance of :class:`~pyprep.Reference`.
+
+        """
+        if self.bad_before_interpolation is None:
+            raise RuntimeError(
+                "Robust referencing must be performed before remaining bad channels "
+                "can be interpolated."
+            )
+        elif self.interpolated_channels is not None:
+            raise RuntimeError(
+                "Bad channel interpolation cannot be performed more than once - "
+                "interpolating signals using other interpolated signals is likely "
+                "to have poor results."
+            )
+
+        # Interpolate any channels flagged as bad following robust referencing
+        bad_channels = self.raw.info["bads"]
+        if len(bad_channels) > 0:
+            if self.matlab_strict:
+                _eeglab_interpolate_bads(self.raw)
+            else:
+                self.raw.interpolate_bads()
+
+        # Calculate and remove the new average reference following interpolation
         reference_correct = np.nanmean(
             self.raw.get_data(picks=self.reference_channels), axis=0
         )
+        rereferenced_index = [
+            self.ch_names_eeg.index(ch) for ch in self.rereferenced_channels
+        ]
         self.EEG = self.raw.get_data()
         self.EEG = self.remove_reference(
             self.EEG, reference_correct, rereferenced_index
         )
-        # reference signal after interpolation
         self.reference_signal_new = self.reference_signal + reference_correct
-        # MNE Raw object after interpolation
-        self.raw._data = self.EEG
+        self.raw._data = self.EEG  # Update the MNE Raw object
 
-        # Still noisy channels after interpolation
+        # Detect any remaining noisy channels following interpolation
         self.interpolated_channels = bad_channels
         noisy_detector = NoisyChannels(
             self.raw,

{pyprep-0.6.0 → pyprep-0.7.0}/pyproject.toml

@@ -15,6 +15,7 @@ classifiers = [
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
   "Programming Language :: Python",
   "Topic :: Scientific/Engineering",
 ]
@@ -86,8 +87,7 @@ exclude = [
   "/.github/**",
   "/docs",
   "/examples",
-  "matprep_artifacts",
-  "matprep_artifacts/**",
+  "/tools",
   "tests/**",
 ]
 
@@ -103,11 +103,6 @@ addopts = """. --cov=pyprep/ --cov-report=xml --cov-config=pyproject.toml --verb
 filterwarnings = [
 ]
 
-[tool.ruff]
-extend-exclude = [
-  "matprep_artifacts/**",
-]
-
 [tool.ruff.lint]
 ignore = ["A002"]
 select = ["A", "D", "E", "F", "I", "UP", "W"]