pyprep 0.5.0__tar.gz → 0.7.0__tar.gz

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

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

{pyprep-0.5.0 → pyprep-0.7.0}/CITATION.cff

@@ -55,6 +55,10 @@ authors:
       family-names: Veillette
       affiliation: 'Department of Psychology, University of Chicago, Chicago, IL, USA'
       orcid: 'https://orcid.org/0000-0002-0332-4372'
+    - given-names: Roy Eric
+      family-names: Wieske
+      affiliation: 'Biopsychology and Neuroergonomics, Technische Universität Berlin, Berlin, Germany'
+      orcid: 'https://orcid.org/0009-0006-2018-1074'
 type: software
 repository-code: 'https://github.com/sappelhoff/pyprep'
 license: MIT

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyprep
-Version: 0.5.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
@@ -38,12 +38,13 @@ Classifier: Operating System :: MacOS
 Classifier: Operating System :: Microsoft :: Windows
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3.9
 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.9
+Requires-Python: >=3.10
 Requires-Dist: mne>=1.3.0
 Requires-Dist: numpy>=1.20.2
 Requires-Dist: psutil>=5.4.3
@@ -134,7 +135,7 @@ for EEG data, working with `MNE-Python <https://mne.tools>`_.
 Installation
 ============
 
-``pyprep`` runs on Python version 3.9 or higher.
+``pyprep`` runs on Python version 3.10 or higher.
 
 We recommend to run ``pyprep`` in a dedicated virtual environment
 (for example using `conda <https://docs.conda.io/en/latest/miniconda.html>`_).

{pyprep-0.5.0 → pyprep-0.7.0}/README.rst

@@ -48,7 +48,7 @@ for EEG data, working with `MNE-Python <https://mne.tools>`_.
 Installation
 ============
 
-``pyprep`` runs on Python version 3.9 or higher.
+``pyprep`` runs on Python version 3.10 or higher.
 
 We recommend to run ``pyprep`` in a dedicated virtual environment
 (for example using `conda <https://docs.conda.io/en/latest/miniconda.html>`_).

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

@@ -29,18 +29,19 @@ class NoisyChannels:
     Parameters
     ----------
     raw : mne.io.Raw
-        An MNE Raw object to check for bad EEG channels.
-    do_detrend : bool, optional
+        An MNE Raw object to check for bad EEG channels. Channels set to bad
+        in ``raw.info["bads"]`` will not be used to find additional bad channels.
+    do_detrend : bool
         Whether or not low-frequency (<1.0 Hz) trends should be removed from the
         EEG signal prior to bad channel detection. This should always be set to
         ``True`` unless the signal has already had low-frequency trends removed.
         Defaults to ``True``.
-    random_state : {int, None, np.random.RandomState}, optional
+    random_state : {int, None, np.random.RandomState} | None
         The seed to use for random number generation within RANSAC. This can be
         ``None``, an integer, or a :class:`~numpy.random.RandomState` object.
         If ``None``, a random seed will be obtained from the operating system.
         Defaults to ``None``.
-    matlab_strict : bool, optional
+    matlab_strict : bool
         Whether or not PyPREP should strictly follow MATLAB PREP's internal
         math, ignoring any improvements made in PyPREP over the original code
         (see :ref:`matlab-diffs` for more details). Defaults to ``False``.
@@ -49,6 +50,21 @@ class NoisyChannels:
         to other methods. RANSAC can detect bad channels that other
         methods are unable to catch, but also slows down noisy channel
         detection considerably. Defaults to ``True``.
+    correlation : bool
+        Whether correlation should be used for bad channel detection, in addition
+        to other methods. Defaults to ``True``.
+    bad_by_manual : list of str | None
+        List of channels that are bad. These channels will be excluded when
+        trying to find additional bad channels. Note that the union of these channels
+        and those declared in ``raw.info["bads"]`` will be used. Defaults to ``None``.
+    reject_by_annotation : {None, 'omit'} | None
+        How to handle BAD-annotated time segments (annotations starting with
+        "BAD" or "bad") during channel quality assessment. If ``'omit'``,
+        annotated segments are excluded from analysis (clean segments are
+        concatenated). If ``None`` (default), annotations are ignored and the
+        full recording is used. This is useful when recordings contain breaks
+        or movement artifacts that shouldn't influence channel rejection
+        decisions.
 
     References
     ----------
@@ -66,13 +82,17 @@ class NoisyChannels:
         matlab_strict=False,
         *,
         ransac=True,
+        correlation=True,
+        bad_by_manual=None,
+        reject_by_annotation=None,
     ):
         # Make sure that we got an MNE object
         assert isinstance(raw, mne.io.BaseRaw)
 
         raw.load_data()
         self.raw_mne = raw.copy()
-        self.bad_by_manual = raw.info["bads"]
+        bad_by_manual = bad_by_manual if bad_by_manual else []
+        self.bad_by_manual = list(set(bad_by_manual + raw.info["bads"]))
         self.raw_mne.pick("eeg")  # excludes bads
         self.sample_rate = raw.info["sfreq"]
         if do_detrend:
@@ -81,15 +101,59 @@ class NoisyChannels:
             )
         self.matlab_strict = matlab_strict
 
-        assert isinstance(ransac, bool), f"ransac must be boolean, got: {ransac}"
+        msg = f"ransac must be boolean, got: {ransac}"
+        assert isinstance(ransac, bool), msg
         self.ransac = ransac
 
+        msg = f"correlation must be boolean, got: {correlation}"
+        assert isinstance(correlation, bool), msg
+        self.correlation = correlation
+
+        # Validate reject_by_annotation parameter
+        if reject_by_annotation is not None and reject_by_annotation != "omit":
+            raise ValueError(
+                f"reject_by_annotation must be None or 'omit', "
+                f"got: {reject_by_annotation}"
+            )
+        # reject_by_annotation is not available in MATLAB PREP
+        if matlab_strict and reject_by_annotation is not None:
+            logger.warning(
+                "reject_by_annotation is not available in MATLAB PREP. "
+                f"Setting reject_by_annotation to None (was '{reject_by_annotation}')."
+            )
+            reject_by_annotation = None
+        self.reject_by_annotation = reject_by_annotation
+
+        # Warn if many small BAD segments are present (potential edge effects)
+        if reject_by_annotation is not None:
+            bad_annots = [
+                a
+                for a in raw.annotations
+                if a["description"].startswith(("BAD", "bad"))
+            ]
+            n_bad_segments = len(bad_annots)
+            if n_bad_segments > 0:
+                total_bad_time = sum(a["duration"] for a in bad_annots)
+                recording_length = raw.times[-1]
+                bad_percentage = (total_bad_time / recording_length) * 100
+                mean_duration = total_bad_time / n_bad_segments
+                if bad_percentage > 15 and mean_duration < 5.0:
+                    logger.warning(
+                        f"Found {n_bad_segments} BAD segments covering "
+                        f"{bad_percentage:.1f}% of the recording with mean duration "
+                        f"{mean_duration:.1f}s. Using reject_by_annotation with many "
+                        "short segments may introduce edge effects from concatenation. "
+                        "This feature is intended for excluding a small number of "
+                        "longer segments (e.g., recording breaks)."
+                    )
+
         # Extra data for debugging
         self._extra_info = {
             "bad_by_deviation": {},
             "bad_by_hf_noise": {},
             "bad_by_correlation": {},
             "bad_by_dropout": {},
+            "bad_by_psd": {},
             "bad_by_ransac": {},
         }
 
@@ -104,21 +168,29 @@ class NoisyChannels:
         self.bad_by_correlation = []
         self.bad_by_SNR = []
         self.bad_by_dropout = []
+        self.bad_by_psd = []
         self.bad_by_ransac = []
 
         # Get original EEG channel names, channel count & samples
         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 = 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()
         bads_by_nan_flat = self.bad_by_nan + self.bad_by_flat
 
+        # unusable channels are also those manually marked as bad
+        bads_unusable = self.bad_by_manual + bads_by_nan_flat
+
         # Make a subset of the data containing only usable EEG channels
-        self.usable_idx = np.isin(ch_names, bads_by_nan_flat, invert=True)
-        self.EEGData = self.raw_mne.get_data(picks=ch_names[self.usable_idx])
+        self.usable_idx = np.isin(ch_names, bads_unusable, invert=True)
+        self.EEGData = self.raw_mne.get_data(
+            picks=ch_names[self.usable_idx],
+            reject_by_annotation=self.reject_by_annotation,
+        )
+        self.n_samples = self.EEGData.shape[1]
         self.EEGFiltered = None
 
         # Get usable EEG channel names & channel counts
@@ -154,10 +226,10 @@ class NoisyChannels:
 
         Parameters
         ----------
-        verbose : bool, optional
+        verbose : bool | None
             If ``True``, a summary of the channels currently flagged as by bad per
             category is printed. Defaults to ``False``.
-        as_dict: bool, optional
+        as_dict: bool | None
             If ``True``, this method will return a dict of the channels currently
             flagged as bad by each individual bad channel type. If ``False``, this
             method will return a list of all unique bad channels detected so far.
@@ -178,6 +250,7 @@ class NoisyChannels:
             "bad_by_correlation": self.bad_by_correlation,
             "bad_by_SNR": self.bad_by_SNR,
             "bad_by_dropout": self.bad_by_dropout,
+            "bad_by_psd": self.bad_by_psd,
             "bad_by_ransac": self.bad_by_ransac,
             "bad_by_manual": self.bad_by_manual,
         }
@@ -186,7 +259,12 @@ class NoisyChannels:
         for bad_chs in bads.values():
             all_bads.update(bad_chs)
 
-        name_map = {"nan": "NaN", "hf_noise": "HF noise", "ransac": "RANSAC"}
+        name_map = {
+            "nan": "NaN",
+            "hf_noise": "HF noise",
+            "psd": "PSD",
+            "ransac": "RANSAC",
+        }
         if verbose:
             out = f"Found {len(all_bads)} uniquely bad channels:\n"
             for bad_type, bad_chs in bads.items():
@@ -203,7 +281,15 @@ class NoisyChannels:
 
         return bads
 
-    def find_all_bads(self, ransac=None, channel_wise=False, max_chunk_size=None):
+    def find_all_bads(
+        self,
+        *,
+        ransac=None,
+        channel_wise=False,
+        max_chunk_size=None,
+        correlation=None,
+        reject_by_annotation=None,
+    ):
         """Call all the functions to detect bad channels.
 
         This function calls all the bad-channel detecting functions.
@@ -217,7 +303,7 @@ class NoisyChannels:
             detection considerably. If ``None`` (default), then the value at
             instantiation of the ``NoisyChannels`` class is taken (defaults
             to ``True``), else the instantiation value is overwritten.
-        channel_wise : bool, optional
+        channel_wise : bool | None
             Whether RANSAC should predict signals for chunks of channels over the
             entire signal length ("channel-wise RANSAC", see `max_chunk_size`
             parameter). If ``False``, RANSAC will instead predict signals for all
@@ -227,28 +313,57 @@ class NoisyChannels:
             (especially if `max_chunk_size` is ``None``), but can be faster on
             systems with lots of RAM to spare. Has no effect if not using RANSAC.
             Defaults to ``False``.
-        max_chunk_size : {int, None}, optional
+        max_chunk_size : {int, None} | None
             The maximum number of channels to predict at once during
             channel-wise RANSAC. If ``None``, RANSAC will use the largest chunk
             size that will fit into the available RAM, which may slow down
             other programs on the host system. If using window-wise RANSAC
             (the default) or not using RANSAC at all, this parameter has no
             effect. Defaults to ``None``.
+        correlation : bool | None
+            Whether correlation should be used for bad channel detection, in addition
+            to the other methods. If ``None`` (default), then the value at
+            instantiation of the ``NoisyChannels`` class is taken (defaults
+            to ``True``), else the instantiation value is overwritten.
+        reject_by_annotation : {None, 'omit'} | None
+            This parameter is accepted for compatibility but is ignored here.
+            Annotation rejection is applied during ``NoisyChannels`` initialization,
+            not during ``find_all_bads``. To use annotation rejection, pass
+            ``reject_by_annotation`` to the ``NoisyChannels`` constructor.
 
         """
+        # Note: reject_by_annotation is accepted but ignored here - it's applied
+        # during __init__ when data is extracted. This parameter exists only for
+        # compatibility with ransac_settings dict unpacking.
+        del reject_by_annotation  # unused, applied in __init__
         if ransac is not None and ransac != self.ransac:
-            assert isinstance(ransac, bool), f"ransac must be boolean, got: {ransac}"
+            msg = f"ransac must be boolean, got: {ransac}"
+            assert isinstance(ransac, bool), msg
             logger.warning(
-                f"Overwriting `ransac` value. Was `{self.ransac}` at instantiation "
+                "Overwriting `ransac` value. "
+                f"Was `{self.ransac}` at instantiation "
                 f"of NoisyChannels. Now setting to `{ransac}`."
             )
             self.ransac = ransac
 
+        if correlation is not None and correlation != self.correlation:
+            msg = f"correlation must be boolean, got: {correlation}"
+            assert isinstance(correlation, bool), msg
+            logger.warning(
+                "Overwriting `correlation` value. "
+                f"Was `{self.correlation}` at instantiation "
+                f"of NoisyChannels. Now setting to `{correlation}`."
+            )
+            self.correlation = correlation
+
         # NOTE: Bad-by-NaN/flat is already run during init, no need to re-run here
         self.find_bad_by_deviation()
         self.find_bad_by_hfnoise()
-        self.find_bad_by_correlation()
+        if self.correlation:
+            self.find_bad_by_correlation()
         self.find_bad_by_SNR()
+        if not self.matlab_strict:
+            self.find_bad_by_PSD()
         if self.ransac:
             self.find_bad_by_ransac(
                 channel_wise=channel_wise, max_chunk_size=max_chunk_size
@@ -263,17 +378,19 @@ 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
         ----------
-        flat_threshold : float, optional
+        flat_threshold : float | None
             The lowest standard deviation or MAD value for a channel to be
             considered bad-by-flat. Defaults to ``1e-15`` volts (corresponds to
             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))
@@ -304,7 +421,7 @@ class NoisyChannels:
 
         Parameters
         ----------
-        deviation_threshold : float, optional
+        deviation_threshold : float | None
             The minimum absolute z-score of a channel for it to be considered
             bad-by-deviation. Defaults to ``5.0``.
 
@@ -350,7 +467,7 @@ class NoisyChannels:
 
         Parameters
         ----------
-        HF_zscore_threshold : float, optional
+        HF_zscore_threshold : float | None
             The minimum noisiness z-score of a channel for it to be considered
             bad-by-high-frequency-noise. Defaults to ``5.0``.
 
@@ -415,12 +532,12 @@ class NoisyChannels:
 
         Parameters
         ----------
-        correlation_secs : float, optional
+        correlation_secs : float | None
             The length (in seconds) of each correlation window. Defaults to ``1.0``.
-        correlation_threshold : float, optional
+        correlation_threshold : float | None
             The lowest maximum inter-channel correlation for a channel to be
             considered "bad" within a given window. Defaults to ``0.4``.
-        frac_bad : float, optional
+        frac_bad : float | None
             The minimum proportion of bad windows for a channel to be considered
             "bad-by-correlation" or "bad-by-dropout". Defaults to ``0.01`` (1% of
             all windows).
@@ -509,7 +626,7 @@ class NoisyChannels:
         # Get names of bad-by-HF-noise and bad-by-correlation channels
         if not len(self._extra_info["bad_by_hf_noise"]) > 1:
             self.find_bad_by_hfnoise()
-        if not len(self._extra_info["bad_by_correlation"]):
+        if not len(self._extra_info["bad_by_correlation"]) and self.correlation:
             self.find_bad_by_correlation()
         bad_by_hf = set(self.bad_by_hf_noise)
         bad_by_corr = set(self.bad_by_correlation)
@@ -517,6 +634,151 @@ class NoisyChannels:
         # Flag channels bad by both HF noise and low correlation as bad by low SNR
         self.bad_by_SNR = list(bad_by_corr.intersection(bad_by_hf))
 
+    def find_bad_by_PSD(self, zscore_threshold=3.0, fmin=1.0, fmax=45.0):
+        """Detect channels with abnormally high or low power spectral density.
+
+        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
+           (violating the typical 1/f spectral profile of EEG).
+
+        Note: Only excess power (positive z-scores) is flagged, as abnormally
+        low power could reflect normal topographic variation.
+
+        PSD is computed using Welch's method over the specified frequency range.
+        The default range (1-45 Hz) excludes line noise frequencies (50/60 Hz).
+
+        Parameters
+        ----------
+        zscore_threshold : float, optional
+            The minimum absolute z-score of a channel for it to be considered
+            bad-by-psd. Defaults to ``3.0``.
+        fmin : float, optional
+            The lower frequency bound (in Hz) for PSD computation.
+            Defaults to ``1.0``.
+        fmax : float, optional
+            The upper frequency bound (in Hz) for PSD computation. The default
+            of ``45.0`` excludes 50/60 Hz line noise from the analysis.
+
+        """
+        MAD_TO_SD = 1.4826  # Scales units of MAD to units of SD, assuming normality
+        # Reference: https://stat.ethz.ch/R-manual/R-devel/library/stats/html/mad.html
+
+        # Define frequency bands (in Hz)
+        BAND_LOW = (fmin, 15.0)  # ~ delta, theta, alpha
+        BAND_MID = (15.0, 30.0)  # ~ beta
+        BAND_HIGH = (30.0, fmax)  # ~ gamma
+
+        if self.EEGFiltered is None:
+            self.EEGFiltered = self._get_filtered_data()
+
+        # Create a temporary Raw object from filtered data for PSD computation
+        info = mne.create_info(
+            ch_names=self.ch_names_new.tolist(),
+            sfreq=self.sample_rate,
+            ch_types="eeg",
+        )
+        raw_filtered = mne.io.RawArray(self.EEGFiltered, info, verbose=False)
+
+        # Compute PSD using Welch method and convert to log scale (dB)
+        psd = raw_filtered.compute_psd(
+            method="welch", fmin=fmin, fmax=fmax, verbose=False
+        )
+        psd_data = psd.get_data()
+        freqs = psd.freqs
+        log_psd = 10 * np.log10(psd_data)
+
+        # Get frequency indices for each band
+        idx_low = (freqs >= BAND_LOW[0]) & (freqs < BAND_LOW[1])
+        idx_mid = (freqs >= BAND_MID[0]) & (freqs < BAND_MID[1])
+        idx_high = (freqs >= BAND_HIGH[0]) & (freqs <= BAND_HIGH[1])
+
+        # Compute band power (sum of log PSD within each band) for each channel
+        band_power_low = np.sum(log_psd[:, idx_low], axis=1)
+        band_power_mid = np.sum(log_psd[:, idx_mid], axis=1)
+        band_power_high = np.sum(log_psd[:, idx_high], axis=1)
+
+        def robust_zscore(values):
+            """Compute robust z-scores using MAD."""
+            median = np.median(values)
+            mad = np.median(np.abs(values - median))
+            sd = mad * MAD_TO_SD
+            if sd > 0:
+                return (values - median) / sd
+            return np.zeros_like(values)
+
+        # Criterion 1: Outlier with abnormally HIGH power in any band
+        # Note: Only positive z-scores (excess power) are flagged, as low power
+        # could reflect normal topographic variation rather than a bad channel
+        zscore_low = robust_zscore(band_power_low)
+        zscore_mid = robust_zscore(band_power_mid)
+        zscore_high = robust_zscore(band_power_high)
+
+        bad_by_band = (
+            (zscore_low > zscore_threshold)
+            | (zscore_mid > zscore_threshold)
+            | (zscore_high > zscore_threshold)
+        )
+
+        # Criterion 2: 1/f violation (high freq band has more power than low freq band)
+        # This is unusual for normal EEG and suggests muscle artifact or bad contact
+        bad_by_1f_violation = band_power_high > band_power_low
+
+        # Criterion 3: Abnormal band ratios compared to other channels
+        # Use small epsilon to avoid division by zero
+        eps = np.finfo(float).eps
+        ratio_low_mid = band_power_low / (band_power_mid + eps)
+        ratio_low_high = band_power_low / (band_power_high + eps)
+        ratio_mid_high = band_power_mid / (band_power_high + eps)
+
+        zscore_ratio_low_mid = robust_zscore(ratio_low_mid)
+        zscore_ratio_low_high = robust_zscore(ratio_low_high)
+        zscore_ratio_mid_high = robust_zscore(ratio_mid_high)
+
+        bad_by_ratio = (
+            (np.abs(zscore_ratio_low_mid) > zscore_threshold)
+            | (np.abs(zscore_ratio_low_high) > zscore_threshold)
+            | (np.abs(zscore_ratio_mid_high) > zscore_threshold)
+        )
+
+        # Combine criteria (bad if ANY criterion is met)
+        # Note: bad_by_ratio is computed for diagnostics but not used in final
+        # decision as it tends to be overly sensitive and theoretically debatable
+        bad_by_psd_usable = bad_by_band | bad_by_1f_violation
+
+        # Map back to original channel indices
+        psd_channel_mask = np.zeros(self.n_chans_original, dtype=bool)
+        psd_channel_mask[self.usable_idx] = bad_by_psd_usable
+        abnormal_psd_channels = self.ch_names_original[psd_channel_mask]
+
+        # Compute combined z-score for reporting (max absolute z-score across bands)
+        psd_zscore = np.zeros(self.n_chans_original)
+        max_band_zscore = np.maximum(
+            np.abs(zscore_low), np.maximum(np.abs(zscore_mid), np.abs(zscore_high))
+        )
+        psd_zscore[self.usable_idx] = max_band_zscore
+
+        # Update names of bad channels by abnormal PSD & save additional info
+        self.bad_by_psd = abnormal_psd_channels.tolist()
+        self._extra_info["bad_by_psd"].update(
+            {
+                "psd_zscore": psd_zscore,
+                "band_power_low": band_power_low,
+                "band_power_mid": band_power_mid,
+                "band_power_high": band_power_high,
+                "zscore_low": zscore_low,
+                "zscore_mid": zscore_mid,
+                "zscore_high": zscore_high,
+                "bad_by_band": bad_by_band,
+                "bad_by_1f_violation": bad_by_1f_violation,
+                "bad_by_ratio": bad_by_ratio,
+            }
+        )
+
     def find_bad_by_ransac(
         self,
         n_samples=50,
@@ -559,26 +821,26 @@ class NoisyChannels:
 
         Parameters
         ----------
-        n_samples : int, optional
+        n_samples : int | None
             Number of random channel samples to use for RANSAC. Defaults
             to ``50``.
-        sample_prop : float, optional
+        sample_prop : float | None
             Proportion of total channels to use for signal prediction per RANSAC
             sample. This needs to be in the range [0, 1], where 0 would mean no
             channels would be used and 1 would mean all channels would be used
             (neither of which would be useful values). Defaults to ``0.25``
             (e.g., 16 channels per sample for a 64-channel dataset).
-        corr_thresh : float, optional
+        corr_thresh : float | None
             The minimum predicted vs. actual signal correlation for a channel to
             be considered good within a given RANSAC window. Defaults
             to ``0.75``.
-        frac_bad : float, optional
+        frac_bad : float | None
             The minimum fraction of bad (i.e., below-threshold) RANSAC windows
             for a channel to be considered bad-by-RANSAC. Defaults to ``0.4``.
-        corr_window_secs : float, optional
+        corr_window_secs : float | None
             The duration (in seconds) of each RANSAC correlation window. Defaults
             to 5 seconds.
-        channel_wise : bool, optional
+        channel_wise : bool | None
             Whether RANSAC should predict signals for chunks of channels over the
             entire signal length ("channel-wise RANSAC", see `max_chunk_size`
             parameter). If ``False``, RANSAC will instead predict signals for all
@@ -587,7 +849,7 @@ class NoisyChannels:
             RANSAC generally has higher RAM demands than window-wise RANSAC
             (especially if `max_chunk_size` is ``None``), but can be faster on
             systems with lots of RAM to spare. Defaults to ``False``.
-        max_chunk_size : {int, None}, optional
+        max_chunk_size : {int, None} | None
             The maximum number of channels to predict at once during
             channel-wise RANSAC. If ``None``, RANSAC will use the largest chunk
             size that will fit into the available RAM, which may slow down
@@ -622,7 +884,9 @@ class NoisyChannels:
             self.EEGFiltered,
             self.sample_rate,
             self.ch_names_new,
-            self.raw_mne._get_channel_positions()[self.usable_idx, :],
+            self.raw_mne._get_channel_positions(self.raw_mne.ch_names)[
+                self.usable_idx, :
+            ],
             exclude_from_ransac,
             n_samples,
             sample_prop,

{pyprep-0.5.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:
@@ -39,15 +40,15 @@ class PrepPipeline:
               For example, for 60Hz you may specify
               ``np.arange(60, sfreq / 2, 60)``. Specify an empty list to
               skip the line noise removal step.
-        - max_iterations : int, optional
+        - max_iterations : int | None
             - The maximum number of iterations of noisy channel removal to
               perform during robust referencing. Defaults to ``4``.
     montage : mne.channels.DigMontage
         Digital montage of EEG data.
-    ransac : bool, optional
+    ransac : bool | None
         Whether or not to use RANSAC for noisy channel detection in addition to
         the other methods in :class:`~pyprep.NoisyChannels`. Defaults to True.
-    channel_wise : bool, optional
+    channel_wise : bool | None
         Whether RANSAC should predict signals for chunks of channels over the
         entire signal length ("channel-wise RANSAC", see `max_chunk_size`
         parameter). If ``False``, RANSAC will instead predict signals for all
@@ -57,24 +58,32 @@ class PrepPipeline:
         (especially if `max_chunk_size` is ``None``), but can be faster on
         systems with lots of RAM to spare. Has no effect if not using RANSAC.
         Defaults to ``False``.
-    max_chunk_size : {int, None}, optional
+    max_chunk_size : {int, None} | None
         The maximum number of channels to predict at once during channel-wise
         RANSAC. If ``None``, RANSAC will use the largest chunk size that will
         fit into the available RAM, which may slow down other programs on the
         host system. If using window-wise RANSAC (the default) or not using
         RANSAC at all, this parameter has no effect. Defaults to ``None``.
-    random_state : {int, None, np.random.RandomState}, optional
+    random_state : {int, None, np.random.RandomState} | None
         The random seed at which to initialize the class. If random_state is
         an int, it will be used as a seed for RandomState.
         If None, the seed will be obtained from the operating system
         (see RandomState for details). Default is None.
-    filter_kwargs : {dict, None}, optional
+    filter_kwargs : {dict, None} | None
         Optional keywords arguments to be passed on to mne.filter.notch_filter.
         Do not set the "x", Fs", and "freqs" arguments via the filter_kwargs
         parameter, but use the "raw" and "prep_params" parameters instead.
         If None is passed, the pyprep default settings for filtering are used
         instead.
-    matlab_strict : bool, optional
+    reject_by_annotation : {None, 'omit'} | None
+        How to handle BAD-annotated time segments (annotations starting with
+        "BAD" or "bad") during channel quality assessment. If ``'omit'``,
+        annotated segments are excluded from analysis (clean segments are
+        concatenated). If ``None`` (default), annotations are ignored and the
+        full recording is used. This is useful when recordings contain breaks
+        or movement artifacts that shouldn't influence channel rejection
+        decisions.
+    matlab_strict : bool | None
         Whether or not PyPREP should strictly follow MATLAB PREP's internal
         math, ignoring any improvements made in PyPREP over the original code
         (see :ref:`matlab-diffs` for more details). Defaults to False.
@@ -128,6 +137,7 @@ class PrepPipeline:
         max_chunk_size=None,
         random_state=None,
         filter_kwargs=None,
+        reject_by_annotation=None,
         matlab_strict=False,
     ):
         """Initialize PREP class."""
@@ -167,11 +177,24 @@ class PrepPipeline:
             "ransac": ransac,
             "channel_wise": channel_wise,
             "max_chunk_size": max_chunk_size,
+            "reject_by_annotation": reject_by_annotation,
         }
         self.random_state = check_random_state(random_state)
         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."""
@@ -181,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,
@@ -221,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 = (
@@ -237,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.5.0 → pyprep-0.7.0}/pyprep/ransac.py

@@ -60,24 +60,24 @@ def find_bad_by_ransac(
     exclude : list
         Labels of channels to exclude as signal predictors during RANSAC
         (i.e., channels already flagged as bad by metrics other than HF noise).
-    n_samples : int, optional
+    n_samples : int | None
         Number of random channel samples to use for RANSAC. Defaults to ``50``.
-    sample_prop : float, optional
+    sample_prop : float | None
         Proportion of total channels to use for signal prediction per RANSAC
         sample. This needs to be in the range [0, 1], where 0 would mean no
         channels would be used and 1 would mean all channels would be used
         (neither of which would be useful values). Defaults to ``0.25`` (e.g.,
         16 channels per sample for a 64-channel dataset).
-    corr_thresh : float, optional
+    corr_thresh : float | None
         The minimum predicted vs. actual signal correlation for a channel to
         be considered good within a given RANSAC window. Defaults to ``0.75``.
-    frac_bad : float, optional
+    frac_bad : float | None
         The minimum fraction of bad (i.e., below-threshold) RANSAC windows for a
         channel to be considered bad-by-RANSAC. Defaults to ``0.4``.
-    corr_window_secs : float, optional
+    corr_window_secs : float | None
         The duration (in seconds) of each RANSAC correlation window. Defaults to
         5 seconds.
-    channel_wise : bool, optional
+    channel_wise : bool | None
         Whether RANSAC should predict signals for chunks of channels over the
         entire signal length ("channel-wise RANSAC", see `max_chunk_size`
         parameter). If ``False``, RANSAC will instead predict signals for all
@@ -86,18 +86,18 @@ def find_bad_by_ransac(
         RANSAC generally has higher RAM demands than window-wise RANSAC
         (especially if `max_chunk_size` is ``None``), but can be faster on
         systems with lots of RAM to spare. Defaults to ``False``.
-    max_chunk_size : {int, None}, optional
+    max_chunk_size : {int, None} | None
         The maximum number of channels to predict at once during channel-wise
         RANSAC. If ``None``, RANSAC will use the largest chunk size that will
         fit into the available RAM, which may slow down other programs on the
         host system. If using window-wise RANSAC (the default), this parameter
         has no effect. Defaults to ``None``.
-    random_state : {int, None, np.random.RandomState}, optional
+    random_state : {int, None, np.random.RandomState} | None
         The random seed with which to generate random samples of channels during
         RANSAC. If random_state is an int, it will be used as a seed for RandomState.
         If ``None``, the seed will be obtained from the operating system
         (see RandomState for details). Defaults to ``None``.
-    matlab_strict : bool, optional
+    matlab_strict : bool | None
         Whether or not RANSAC should strictly follow MATLAB PREP's internal
         math, ignoring any improvements made in PyPREP over the original code
         (see :ref:`matlab-diffs` for more details). Defaults to ``False``.

{pyprep-0.5.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__)
 
 
@@ -32,10 +29,10 @@ class Reference:
         Parameters of PREP which include at least the following keys:
         - ``ref_chs``
         - ``reref_chs``
-    ransac : bool, optional
+    ransac : bool | None
         Whether or not to use RANSAC for noisy channel detection in addition to
         the other methods in :class:`~pyprep.NoisyChannels`. Defaults to True.
-    channel_wise : bool, optional
+    channel_wise : bool | None
         Whether RANSAC should predict signals for chunks of channels over the
         entire signal length ("channel-wise RANSAC", see `max_chunk_size`
         parameter). If ``False``, RANSAC will instead predict signals for all
@@ -45,18 +42,22 @@ class Reference:
         (especially if `max_chunk_size` is ``None``), but can be faster on
         systems with lots of RAM to spare. Has no effect if not using RANSAC.
         Defaults to ``False``.
-    max_chunk_size : {int, None}, optional
+    max_chunk_size : {int, None} | None
         The maximum number of channels to predict at once during channel-wise
         RANSAC. If ``None``, RANSAC will use the largest chunk size that will
         fit into the available RAM, which may slow down other programs on the
         host system. If using window-wise RANSAC (the default) or not using
         RANSAC at all, this parameter has no effect. Defaults to ``None``.
-    random_state : {int, None, np.random.RandomState}, optional
+    random_state : {int, None, np.random.RandomState} | None
         The random seed at which to initialize the class. If random_state is
         an int, it will be used as a seed for RandomState.
         If None, the seed will be obtained from the operating system
         (see RandomState for details). Default is None.
-    matlab_strict : bool, optional
+    reject_by_annotation : {None, 'omit'} | None
+        How to handle BAD-annotated time segments (annotations starting with
+        "BAD" or "bad") during channel quality assessment. If ``'omit'``,
+        annotated segments are excluded. Defaults to ``None`` (ignore).
+    matlab_strict : bool | None
         Whether or not PyPREP should strictly follow MATLAB PREP's internal
         math, ignoring any improvements made in PyPREP over the original code.
         Defaults to False.
@@ -77,6 +78,7 @@ class Reference:
         channel_wise=False,
         max_chunk_size=None,
         random_state=None,
+        reject_by_annotation=None,
         matlab_strict=False,
     ):
         """Initialize the class."""
@@ -94,44 +96,62 @@ class Reference:
             "ransac": ransac,
             "channel_wise": channel_wise,
             "max_chunk_size": max_chunk_size,
+            "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, optional
+        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
         ]
@@ -139,42 +159,80 @@ 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, random_state=self.random_state, matlab_strict=self.matlab_strict
+            self.raw,
+            random_state=self.random_state,
+            matlab_strict=self.matlab_strict,
+            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, random_state=self.random_state, matlab_strict=self.matlab_strict
+            self.raw,
+            random_state=self.random_state,
+            matlab_strict=self.matlab_strict,
+            reject_by_annotation=self.ransac_settings.get("reject_by_annotation"),
         )
         noisy_detector.find_all_bads(**self.ransac_settings)
         self.still_noisy_channels = noisy_detector.get_bads()
@@ -192,7 +250,7 @@ class Reference:
 
         Parameters
         ----------
-        max_iterations : int, optional
+        max_iterations : int | None
             The maximum number of iterations of noisy channel removal to perform
             during robust referencing. Defaults to ``4``.
 
@@ -216,6 +274,7 @@ class Reference:
             do_detrend=False,
             random_state=self.random_state,
             matlab_strict=self.matlab_strict,
+            reject_by_annotation=self.ransac_settings.get("reject_by_annotation"),
         )
         noisy_detector.find_all_bads(**self.ransac_settings)
         self.noisy_channels_original = noisy_detector.get_bads(as_dict=True)
@@ -238,6 +297,7 @@ class Reference:
             "bad_by_correlation": [],
             "bad_by_SNR": [],
             "bad_by_dropout": [],
+            "bad_by_psd": [],
             "bad_by_ransac": [],
             "bad_by_manual": self.bads_manual,
             "bad_all": [],
@@ -265,6 +325,7 @@ class Reference:
                 do_detrend=False,
                 random_state=self.random_state,
                 matlab_strict=self.matlab_strict,
+                reject_by_annotation=self.ransac_settings.get("reject_by_annotation"),
             )
             # Detrend applied at the beginning of the function.
 
@@ -338,7 +399,7 @@ class Reference:
             The original EEG signal.
         reference : np.ndarray, shape(times,)
             The reference signal.
-        index : {list, None}, optional
+        index : {list, None} | None
             A list of channel indices from which the reference signal should be
             subtracted. Defaults to all channels in `signal`.
 

{pyprep-0.5.0 → pyprep-0.7.0}/pyprep/removeTrend.py

@@ -27,16 +27,16 @@ def removeTrend(
         A 2-D array of EEG data to detrend.
     sample_rate : float
         The sample rate (in Hz) of the input EEG data.
-    detrendType : str, optional
+    detrendType : str | None
         Type of detrending to be performed: must be one of 'high pass',
         'high pass sinc, or 'local detrend'. Defaults to 'high pass'.
-    detrendCutoff : float, optional
+    detrendCutoff : float | None
         The high-pass cutoff frequency (in Hz) to use for detrending. Defaults
         to 1.0 Hz.
-    detrendChannels : {list, None}, optional
+    detrendChannels : {list, None} | None
         List of the indices of all channels that require detrending/filtering.
         If ``None``, all channels are used (default).
-    matlab_strict : bool, optional
+    matlab_strict : bool | None
         Whether or not detrending should strictly follow MATLAB PREP's internal
         math, ignoring any improvements made in PyPREP over the original code
         (see :ref:`matlab-diffs` for more details). Defaults to ``False``.

{pyprep-0.5.0 → pyprep-0.7.0}/pyprep/utils.py

@@ -56,7 +56,7 @@ def _mat_quantile(arr, q, axis=None):
     q : float
         The quantile to calculate for the input data. Must be between 0 and 1,
         inclusive.
-    axis : {int, tuple of int, None}, optional
+    axis : {int, tuple of int, None} | None
         Axis along which quantile values should be calculated. Defaults to
         calculating the value at the given quantile for the entire array.
 
@@ -130,7 +130,7 @@ def _mat_iqr(arr, axis=None):
     ----------
     arr : np.ndarray
         Input array containing samples from the distribution to summarize.
-    axis : {int, tuple of int, None}, optional
+    axis : {int, tuple of int, None} | None
         Axis along which IQRs should be calculated. Defaults to calculating the
         IQR for the entire array.
 
@@ -435,7 +435,7 @@ def _correlate_arrays(a, b, matlab_strict=False):
         A 2-D array to correlate with `a`.
     b : np.ndarray
         A 2-D array to correlate with `b`.
-    matlab_strict : bool, optional
+    matlab_strict : bool | None
         Whether or not correlations should be calculated identically to MATLAB
         PREP (i.e., without mean subtraction) instead of by traditional Pearson
         product-moment correlation (see Notes for details). Defaults to

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

@@ -14,7 +14,8 @@ classifiers = [
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
-  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
   "Programming Language :: Python",
   "Topic :: Scientific/Engineering",
 ]
@@ -43,7 +44,7 @@ maintainers = [
 ]
 name = "pyprep"
 readme = {content-type = "text/x-rst", file = "README.rst"}
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 
 [project.optional-dependencies]
 dev = ["ipykernel", "ipython", "pyprep[test,docs]"]
@@ -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"]