ADD: bad_by_PSD method

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

docs/authors.rst

@@ -11,3 +11,4 @@
 .. _Victor Xiang: https://github.com/Nick3151
 .. _Yorguin Mantilla: https://github.com/yjmantilla
 .. _John Veillette: https://github.com/john-veillette
+.. _Roy Eric Wieske: https://github.com/Randomidous

docs/changelog.rst

@@ -26,6 +26,8 @@ Version 0.6.0 (unreleased)
 
 Changelog
 ~~~~~~~~~
+- Added :meth:`~pyprep.NoisyChannels.find_bad_by_PSD` method for detecting channels with abnormally high or low power spectral density. This is a PyPREP-only feature not present in MATLAB PREP, by `Roy Eric Wieske`_ (:gh:`145`)
+- Added ``reject_by_annotation`` parameter to :class:`~pyprep.PrepPipeline`, :class:`~pyprep.Reference`, and :class:`~pyprep.NoisyChannels` to exclude BAD-annotated time segments from channel quality assessment, by `Roy Eric Wieske`_ (:gh:`180`)
 - Users can now determine whether or not to use ``correlation`` as a method for finding bad channels in :meth:`~pyprep.NoisyChannels.find_all_bads` (defaults to True), by `Stefan Appelhoff`_ (:gh:`169`)
 - Manually marked bad channels are ignored for finding further bads (just like NaN and flat channels) in :meth:`~pyprep.NoisyChannels.find_all_bads`, by `Stefan Appelhoff`_ (:gh:`168`)
 

docs/matlab_differences.rst

@@ -233,6 +233,72 @@ MATLAB PREP, PyPREP will use a Python reimplementation of ``eeg_interp`` instead
 when the ``matlab_strict`` parameter is set to ``True``.
 
 
+Annotation-Based Segment Rejection
+----------------------------------
+
+PyPREP supports the ``reject_by_annotation`` parameter in
+:class:`~pyprep.PrepPipeline`, :class:`~pyprep.Reference`, and
+:class:`~pyprep.NoisyChannels`, which allows excluding BAD-annotated time
+segments from channel quality assessment. BAD segments are any MNE annotations
+with descriptions starting with "BAD" or "bad" (see
+:ref:`mne:tut-reject-data-spans` for details). This is useful when recordings
+contain breaks, movement artifacts, or other periods that shouldn't influence
+channel rejection decisions.
+
+MATLAB PREP does not have this feature. In fact, MATLAB PREP explicitly warns
+against using PREP on data with discontinuities (such as boundary markers from
+paused/resumed recordings). However, the ``reject_by_annotation`` feature in
+PyPREP is designed for a different use case: temporarily excluding known-bad
+segments (e.g., participant movement during breaks) from *statistical analysis*
+while preserving the original continuous data structure in the output.
+
+When ``reject_by_annotation`` is set to ``'omit'``, MNE's
+:meth:`~mne.io.Raw.get_data` is used to concatenate non-BAD segments for
+computing channel quality metrics. The final processed output retains the
+original continuous structure with all time points intact.
+
+.. note::
+
+   This feature is intended for excluding a small number of longer segments
+   (e.g., recording breaks). Using it with many short BAD segments (e.g., from
+   automated muscle artifact detection via
+   :func:`mne.preprocessing.annotate_muscle_zscore`) may introduce edge effects
+   at concatenation boundaries, particularly for methods that apply filtering
+   to the concatenated data. PyPREP will emit a warning if many small BAD
+   segments are detected.
+
+This parameter has no equivalent in MATLAB PREP. When ``matlab_strict`` is set
+to ``True``, ``reject_by_annotation`` is automatically set to ``None``.
+
+
+PyPREP-Only Features
+--------------------
+
+The following features are available in PyPREP but are not present in the
+original MATLAB PREP implementation.
+
+
+Bad channel detection by PSD
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :meth:`~pyprep.NoisyChannels.find_bad_by_PSD` method detects channels with
+abnormally high or low power spectral density (PSD) compared to other channels.
+This method is not part of the original MATLAB PREP pipeline, but can be
+considered a refinement of the ``bad_by_hfnoise`` detection in MATLAB PREP,
+which flags channels based on the ratio of high-frequency power (>50 Hz) to
+total power.
+
+A channel is considered "bad-by-PSD" if its total PSD (computed using Welch's
+method over a configurable frequency range, defaulting to 1-45 Hz to exclude
+line noise) deviates considerably from the median channel PSD. The deviation
+is calculated using robust Z-scoring based on the median absolute deviation
+(MAD).
+
+This method is called by :meth:`~pyprep.NoisyChannels.find_all_bads` by default,
+but is skipped when ``matlab_strict=True`` to maintain equivalence with the
+original MATLAB PREP pipeline.
+
+
 References
 ----------