Raise a clear error for a fixed-length window array on a short span

A named/tuple window is regenerated by SciPy at the shrunk nperseg, so short
good-data spans are handled transparently. An explicit ndarray window has a
fixed length and cannot be shortened to match, which previously surfaced as a
cryptic SciPy length-mismatch error. Detect this case and raise an actionable
ValueError pointing the user at passing a shorter window array or reducing
n_per_seg/n_fft. Adds a regression test.

Author: CedricConday

mne/time_frequency/psd.py

@@ -271,12 +271,25 @@ def psd_array_welch(
         # so every span is zero-padded to the same length and shares one frequency
         # grid; short spans simply get coarser spectral resolution. A per-span
         # ``partial`` overrides the nperseg/noverlap baked into ``_func``.
+        # A named/tuple window (e.g. "hamming") is regenerated by SciPy at the
+        # shrunk nperseg, so short spans are handled transparently. An explicit
+        # ndarray/list window has a fixed length and cannot be shortened to match;
+        # rather than let SciPy raise a cryptic length-mismatch error, bail clearly.
+        window_is_array = not isinstance(window, (str, tuple))
         funcs = []
         weights = []
         n_short = 0
         for span in x_splits:
             span_len = span.shape[-1]
             if span_len < n_per_seg:
+                if window_is_array:
+                    raise ValueError(
+                        f"A good data span ({span_len} samples) is shorter than "
+                        f"n_per_seg ({n_per_seg}), but `window` is a fixed-length "
+                        "array that cannot be shortened to match it. Pass a shorter "
+                        "`window` array, or reduce n_per_seg (or n_fft) so that every "
+                        "good data span is at least n_per_seg samples long."
+                    )
                 span_nperseg = span_len
                 span_noverlap = min(n_overlap, span_nperseg - 1)
                 n_short += 1

mne/time_frequency/tests/test_psd.py

@@ -91,6 +91,31 @@ def test_psd_welch_short_span_kept():
     assert np.all(np.isfinite(psds))
 
 
+def test_psd_welch_short_span_array_window_raises():
+    """A fixed-length ndarray window can't shrink for a short span (gh-13039)."""
+    n_fft = 256
+    n_overlap = n_fft // 2
+    n_chan = 2
+    rng = np.random.default_rng(0)
+    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)
+    # Named windows are regenerated by SciPy at the shrunk length, but an explicit
+    # window array is fixed-length and cannot be shortened to fit the 100-sample
+    # span, so we raise a clear error instead of a cryptic SciPy length mismatch.
+    with pytest.raises(ValueError, match="fixed-length array"):
+        psd_array_welch(
+            x, sfreq=100, n_fft=n_fft, n_overlap=n_overlap, window=np.hamming(n_fft)
+        )
+    # A full-length array window on all-long spans still works (guard is scoped).
+    x_ok = np.concatenate((long, np.full((n_chan, 1), np.nan), long), axis=-1)
+    psds, freqs = psd_array_welch(
+        x_ok, sfreq=100, n_fft=n_fft, n_overlap=n_overlap, window=np.hamming(n_fft)
+    )
+    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)