Fix psd_array_welch for good spans shorter than n_overlap (mne-tools#13039)

When good data spans (between bad annotations) are shorter than n_per_seg,
SciPy reduces nperseg to the span length but leaves noverlap unchanged, so a
span shorter than n_overlap raised 'noverlap must be less than nperseg'.
Reduce noverlap per-span to stay < nperseg (nfft unchanged so frequency bins
match across spans). Adds a regression test.

Author: CedricConday

doc/changes/dev/13039.bugfix.rst

@@ -0,0 +1 @@
+Fix :func:`mne.time_frequency.psd_array_welch` (and Welch-method ``compute_psd``) so that good data spans shorter than ``n_overlap`` no longer raise ``noverlap must be less than nperseg``; such spans now reduce ``noverlap`` to fit, by :newcontrib:`Cedric Conday`.

doc/changes/names.inc

@@ -52,6 +52,7 @@
 .. _Carina Forster: https://github.com/CarinaFo
 .. _Carlos de la Torre-Ortiz: https://github.com/c-torre
 .. _Cathy Nangini: https://github.com/KatiRG
+.. _Cedric Conday: https://github.com/CedricConday
 .. _Chetan Gohil: https://github.com/cgohil8
 .. _Chris Bailey: https://github.com/cjayb
 .. _Chris Holdgraf: https://chrisholdgraf.com

mne/time_frequency/psd.py

@@ -281,6 +281,20 @@ def psd_array_welch(
             )
 
         def func(*args, **kwargs):
+            # A good data span shorter than n_per_seg makes SciPy reduce nperseg to
+            # the span length; reduce noverlap to match so it stays < nperseg.
+            # Otherwise, a span shorter than n_overlap raises "noverlap must be less
+            # than nperseg". nfft is left unchanged so every span yields the same
+            # frequency bins (the spans are then combined by weighted average).
+            # See #13039.
+            epoch = args[0]
+            if epoch.shape[-1] < n_per_seg:
+                span_len = epoch.shape[-1]
+                kwargs = {
+                    **kwargs,
+                    "nperseg": span_len,
+                    "noverlap": min(n_overlap, max(span_len - 1, 0)),
+                }
             # swallow SciPy warnings caused by short good data spans
             with warnings.catch_warnings():
                 warnings.filterwarnings(

mne/time_frequency/tests/test_psd.py

@@ -58,6 +58,23 @@ def test_bad_annot_handling():
     np.testing.assert_allclose(got[0], want[0], rtol=1e-15, atol=0)
 
 
+def test_psd_welch_short_span_with_overlap():
+    """Good spans shorter than n_overlap must not crash (gh-13039)."""
+    n_fft = 256
+    n_overlap = n_fft // 2  # 128
+    n_chan = 2
+    rng = np.random.default_rng(0)
+    # A good span (100 samples) shorter than n_overlap, then a bad-annotation
+    # (aligned NaN), then a long span. Previously raised from SciPy:
+    # "noverlap must be less than nperseg".
+    short = rng.standard_normal((n_chan, 100))
+    long = rng.standard_normal((n_chan, 5 * n_fft))
+    x = np.concatenate((short, np.full((n_chan, 1), np.nan), long), axis=-1)
+    psds, freqs = psd_array_welch(x, sfreq=100, n_fft=n_fft, n_overlap=n_overlap)
+    assert psds.shape == (n_chan, len(freqs))
+    assert np.all(np.isfinite(psds))
+
+
 def _make_psd_data():
     """Make noise data with sinusoids in 2 out of 7 channels."""
     rng = np.random.default_rng(0)