Skip to content

FIX: Reject averaged complex Welch coefficients - #14498

Merged
tsbinns merged 12 commits into
mne-tools:mainfrom
iis-MarkKuang:fix/welch-complex-average
Nov 6, 2026
Merged

tsbinns merged 12 commits into
mne-tools:mainfrom
iis-MarkKuang:fix/welch-complex-average

Conversation

@iis-MarkKuang

@iis-MarkKuang iis-MarkKuang commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Reference issue

Fixes #14495.

What does this implement/fix?

Welch output="complex" with average="mean" or "median" averages the Fourier coefficients across segments. Their phases do not line up, so the power formed from the average is not the average of the power. normalization is not involved: the one-sided factor of 2 already makes unaveraged coefficients match output="power" after squaring and then averaging. average=None and average=False still return one coefficient per segment. output="power" is unchanged.

Additional information

AI assistance: Grok 4.7 in Cursor drafted the guard, the regression test, and this description, after I asked it to fix this issue the same way as #14493.

Averaging Fourier coefficients across Welch segments mixes their phases,
so the power recovered from them no longer matches output="power".

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

@tsbinns tsbinns left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the PR @iis-MarkKuang!

A couple comments and suggestions.

Comment thread mne/time_frequency/psd.py Resolved
Comment thread mne/time_frequency/psd.py Resolved
Comment thread mne/time_frequency/tests/test_psd.py Resolved
Comment thread doc/changes/dev/14498.bugfix.rst Resolved
Keep the docstring to the new restriction, and check phase on each segment.

Co-authored-by: Cursor <cursoragent@cursor.com>
@iis-MarkKuang

Copy link
Copy Markdown
Contributor Author

Shortened the average note and added versionchanged:: 1.14. Phase is checked on each segment, and both mean and median power are recovered from those coefficients.

@tsbinns tsbinns left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @iis-MarkKuang! Just some tiny suggestions.

Comment thread doc/changes/dev/14498.bugfix.rst Resolved
Comment thread mne/time_frequency/tests/test_psd.py Resolved
Comment thread mne/time_frequency/tests/test_psd.py Resolved
Comment thread mne/time_frequency/psd.py Resolved
Comment thread mne/time_frequency/psd.py Resolved

@tsbinns tsbinns left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@iis-MarkKuang Don't worry if you can't find a solution for the failing autofix check. I can look into this later today if it's still failing.

@iis-MarkKuang

Copy link
Copy Markdown
Contributor Author

Thanks. The test jobs on this PR are green. The remaining failure is Autofix and style (prek), not the new tests. Happy for you to look at that one.

@drammock

drammock commented Nov 6, 2026

Copy link
Copy Markdown
Member

@iis-MarkKuang it would actually be really helpful to us if you could try to solve the autofix error yourself. The message is:

mne/time_frequency/psd.py:95 psd_array_welch: docstring differs from docdict['average_psd'], but neither changed since git HEAD, so which one is out of date cannot be told; edit whichever side is wrong to match the other (an edit to docdict is propagated)

if you can't tell what needs to be done from the message (and looking at the docstring and the docdict), that is helpful for us to know so that we can make the error message more clear/explicit.

@tsbinns

tsbinns commented Nov 6, 2026

Copy link
Copy Markdown
Member

Sorry for the back-and-forth @iis-MarkKuang. The fix ended up being a bit different to usual, so we have just pushed it.

@tsbinns tsbinns left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @iis-MarkKuang! Marking for merge when green.

@tsbinns
tsbinns enabled auto-merge (squash) November 6, 2026 17:32
@tsbinns
tsbinns merged commit 256f27d into mne-tools:main Nov 6, 2026
25 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

output="complex" for Welch method should only allow average=None

3 participants