FIX: correct mode parameter in get_point_spread and get_cross_talk

[Famous077]

Fixed issue #13128

What does this implement/fix?

Found a bug where the mode parameter in get_point_spread() and
get_cross_talk() wasn't working as documented. The public API says
'max' and 'svd' are valid modes, but the internal helper function
_summarise_psf_ctf uses different names ('maxnorm' and 'pca'),
so passing 'max' or 'svd' just silently returned all vertices
without any summarisation — no error, no warning.

Changes made:

• added validation so invalid mode values now raise a ValueError
• map public names to internal ones before calling _summarise_psf_ctf
• updated existing tests to use the correct public mode names

Additional information

Verified the fix works correctly with both individual vertex indices and labels.
All 3 existing tests pass after the changes.

[nordme]

Hi @Famous077 ! Thanks for the PR!

I took a quick look at your code here. Good catch on the mismatch between parameter names passed to mne.minimum_norm.get_cross_talk and mne.minimum_norm.get_point_spread public functions to parameter names used in the internal code. It makes sense to me to remap the internal names to the external ones based on their description: pca -> svd, maxnorm -> max.

With that said, the internal function _summarize_psf_ctf (here) includes additional functionality for maxval and sum options. Rather than eliminating that functionality, I think it would make sense to add those parameter options to the public function documentation. They're valid, so they may as well get used.

Cheers.

[Famous077]

Hi @Famous077 ! Thanks for the PR!

I took a quick look at your code here. Good catch on the mismatch between parameter names passed to mne.minimum_norm.get_cross_talk and mne.minimum_norm.get_point_spread public functions to parameter names used in the internal code. It makes sense to me to remap the internal names to the external ones based on their description: pca -> svd, maxnorm -> max.

With that said, the internal function _summarize_psf_ctf (here) includes additional functionality for maxval and sum options. Rather than eliminating that functionality, I think it would make sense to add those parameter options to the public function documentation. They're valid, so they may as well get used.

Cheers.

Hi @nordme , thanks for the suggestion. I've added 'sum' and 'maxval' to the public API - they now map through to the internal function correctly, the validation and n_comp guard are updated, and all 3 tests pass locally. Please take a look and let me know if anything needs to be updated.

[nordme]

Ok, function code looks good to me, but I think we need to add a doc update. The public won't know we've got the "sum" and "maxval" options available unless we update the "mode" parameter description in the docstrings of mne.minimum_norm.get_point_spread and mne.minimum_norm.get_cross_talk on the website. Note in the source code for these functions, the mode parameter description calls in pre-written text, %(mode_pctf)s. To change that parameter description, we need to touch another file, mne/utils/docs.py, which contains a docdict dictionary where we store parameter descriptions for parameters that get used in multiple functions. You can use the info already there as a guide to add extra information about "sum" and "maxval" options to the docdict["mode_pctf"] item. This will get pulled in to all the functions that use this parameter.