FIX: correct mode parameter in get_point_spread and get_cross_talk (#13754)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: Famous077

doc/changes/dev/13754.bugfix.rst

@@ -0,0 +1 @@
+Fix ``mode`` parameter in :func:`~mne.minimum_norm.get_point_spread` and :func:`~mne.minimum_norm.get_cross_talk` to correctly map public mode names (``'max'``, ``'svd'``) to internal names, expose previously hidden modes ``'sum'`` and ``'maxval'`` in the public API, and raise :class:`ValueError` for invalid mode values, by :newcontrib:`Famous077`.

mne/minimum_norm/resolution_matrix.py

@@ -155,8 +155,16 @@ def _get_psf_ctf(
         # summarise PSFs/CTFs across vertices if requested
         pca_var = None  # variances computed only if return_pca_vars=True
         if mode is not None:
+            # mapping public mode names to internal names
+            _mode_map = {
+                "max": "maxnorm",
+                "svd": "pca",
+                "mean": "mean",
+                "sum": "sum",
+                "maxval": "maxval",
+            }
             funcs, pca_var = _summarise_psf_ctf(
-                funcs, mode, n_comp, return_pca_vars, nn
+                funcs, _mode_map[mode], n_comp, return_pca_vars, nn
             )
 
         if not vector:  # if one value per vertex requested
@@ -193,11 +201,14 @@ def _get_psf_ctf(
 
 def _check_get_psf_ctf_params(mode, n_comp, return_pca_vars):
     """Check input parameters of _get_psf_ctf() for consistency."""
-    if mode in [None, "sum", "mean"] and n_comp > 1:
+    valid_modes = (None, "mean", "max", "svd", "sum", "maxval")
+    if mode not in valid_modes:
+        raise ValueError(f"mode must be one of {valid_modes}, got {mode!r} instead.")
+    if mode in [None, "mean", "sum"] and n_comp > 1:
         msg = f"n_comp must be 1 for mode={mode}."
         raise ValueError(msg)
-    if mode != "pca" and return_pca_vars:
-        msg = "SVD variances can only be returned if mode=pca."
+    if mode != "svd" and return_pca_vars:
+        msg = "SVD variances can only be returned if mode='svd'."
         raise ValueError(msg)
 
 

mne/minimum_norm/tests/test_resolution_matrix.py

@@ -68,9 +68,9 @@ def test_resolution_matrix_free(src_type, fwd_volume_small):
     )
     assert_array_almost_equal(rm_mne_free, rm_mne_free.T)
     # check various summary and normalisation options
-    for mode in [None, "sum", "mean", "maxval", "maxnorm", "pca"]:
+    for mode in [None, "mean", "max", "svd", "sum", "maxval"]:
         n_comps = [1, 3]
-        if mode in [None, "sum", "mean"]:
+        if mode in [None, "mean", "sum"]:
             n_comps = [1]
         for n_comp in n_comps:
             for norm in [None, "max", "norm", True]:
@@ -114,7 +114,7 @@ def test_resolution_matrix_free(src_type, fwd_volume_small):
                 # There is an ambiguity in the sign flip from the PCA here.
                 # Ideally we would use the normals to fix it, but it's not
                 # trivial.
-                if mode == "pca" and n_comp == 3:
+                if mode == "svd" and n_comp == 3:
                     stc_psf_free = abs(stc_psf_free)
                     stc_ctf_free = abs(stc_psf_free)
                 assert_array_almost_equal(
@@ -184,9 +184,9 @@ def test_resolution_matrix_fixed():
     # Some arbitrary vertex numbers
     idx = [1, 100, 400]
     # check various summary and normalisation options
-    for mode in [None, "sum", "mean", "maxval", "maxnorm", "pca"]:
+    for mode in [None, "mean", "max", "svd", "sum", "maxval"]:
         n_comps = [1, 3]
-        if mode in [None, "sum", "mean"]:
+        if mode in [None, "mean", "sum"]:
             n_comps = [1]
         for n_comp in n_comps:
             for norm in [None, "max", "norm", True]:
@@ -217,7 +217,7 @@ def test_resolution_matrix_fixed():
         rm_mne,
         forward_fxd["src"],
         idx,
-        mode=mode,
+        mode="svd",
         n_comp=n_comp,
         norm="norm",
         return_pca_vars=True,
@@ -226,7 +226,7 @@ def test_resolution_matrix_fixed():
         rm_mne,
         forward_fxd["src"],
         idx,
-        mode=mode,
+        mode="svd",
         n_comp=n_comp,
         norm="norm",
         return_pca_vars=True,

mne/utils/docs.py

@@ -2723,7 +2723,7 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75):
 """
 
 docdict["mode_pctf"] = """
-mode : None | 'mean' | 'max' | 'svd'
+mode : None | 'mean' | 'max' | 'svd' | 'maxval' | 'sum'
     Compute summary of PSFs/CTFs across all indices specified in 'idx'.
     Can be:
 
@@ -2734,6 +2734,9 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75):
       n_comp largest PSFs/CTFs.
     * 'svd' : SVD components across PSFs/CTFs across vertices. Returns the
       n_comp first SVD components.
+    * 'maxval' : PSFs/CTFs with maximum absolute value across vertices.
+      Returns the n_comp largest PSFs/CTFs.
+    * 'sum' : Sum of PSFs/CTFs across vertices.
 """
 
 docdict["mode_tfr_plot"] = """