ENH: support auto and fsaverage for add_trans in report (#13232)

Author: sappelhoff

doc/changes/devel/13232.newfeature.rst

@@ -0,0 +1 @@
+:meth:`mne.Report.add_trans` now accepts ``"auto"`` and ``"fsaverage"`` as arguments for the ``trans`` parameter, by `Stefan Appelhoff`_.

mne/forward/_field_interpolation.py

@@ -21,7 +21,7 @@
 from ..evoked import Evoked, EvokedArray
 from ..fixes import _safe_svd
 from ..surface import get_head_surf, get_meg_helmet_surf
-from ..transforms import _find_trans, _get_trans, transform_surface_to
+from ..transforms import _find_trans, transform_surface_to
 from ..utils import _check_fname, _check_option, _pl, _reg_pinv, logger, verbose
 from ._lead_dots import (
     _do_cross_dots,
@@ -514,10 +514,12 @@ def make_field_map(
             name="subjects_dir",
             need_dir=True,
         )
-    if isinstance(trans, str) and trans == "auto":
-        # let's try to do this in MRI coordinates so they're easy to plot
-        trans = _find_trans(subject, subjects_dir)
-    trans, trans_type = _get_trans(trans, fro="head", to="mri")
+
+    trans, trans_type = _find_trans(
+        trans=trans,
+        subject=subject,
+        subjects_dir=subjects_dir,
+    )
 
     if "eeg" in types and trans_type == "identity":
         logger.info("No trans file available. EEG data ignored.")

mne/report/report.py

@@ -43,7 +43,7 @@
 from ..proj import read_proj
 from ..source_estimate import SourceEstimate, read_source_estimate
 from ..surface import dig_mri_distances
-from ..transforms import Transform, read_trans
+from ..transforms import Transform, _find_trans, read_trans
 from ..utils import (
     _check_ch_locs,
     _check_fname,
@@ -1606,8 +1606,11 @@ def add_trans(
 
         Parameters
         ----------
-        trans : path-like | instance of Transform
-            The ``head -> MRI`` transformation to render.
+        %(trans)s "auto" will load trans from the FreeSurfer directory
+            specified by ``subject`` and ``subjects_dir`` parameters.
+
+            .. versionchanged:: 1.10
+                Support for 'fsaverage' argument.
         info : path-like | instance of Info
             The `~mne.Info` corresponding to ``trans``.
         title : str
@@ -4224,8 +4227,8 @@ def _add_trans(
         replace,
     ):
         """Render trans (only PNG)."""
-        if not isinstance(trans, Transform):
-            trans = read_trans(trans)
+        trans, _ = _find_trans(trans=trans, subject=subject, subjects_dir=subjects_dir)
+
         if not isinstance(info, Info):
             info = read_info(info)
 

mne/report/tests/test_report.py

@@ -1168,6 +1168,11 @@ def test_manual_report_3d(tmp_path, renderer):
     # use of sparse rather than dense head, and also possibly an arg to specify
     # which views to actually show. Both of these could probably be useful to
     # end-users, too.
+    bad_add_kwargs = add_kwargs.copy()
+    bad_add_kwargs.update(dict(trans="auto", subjects_dir=subjects_dir))
+    with pytest.raises(RuntimeError, match="Could not find"):
+        r.add_trans(title="my coreg", **bad_add_kwargs)
+    add_kwargs.update(trans="fsaverage")  # this is wrong but tests fsaverage code path
     r.add_trans(title="my coreg", **add_kwargs)
     r.add_bem(subject="sample", subjects_dir=subjects_dir, title="my bem", decim=100)
     r.add_inverse_operator(

mne/tests/test_transforms.py

@@ -103,11 +103,16 @@ def test_get_trans():
 def test_io_trans(tmp_path):
     """Test reading and writing of trans files."""
     os.mkdir(tmp_path / "sample")
-    pytest.raises(RuntimeError, _find_trans, "sample", subjects_dir=tmp_path)
+    pytest.raises(
+        RuntimeError, _find_trans, trans="auto", subject="sample", subjects_dir=tmp_path
+    )
     trans0 = read_trans(fname)
     fname1 = tmp_path / "sample" / "test-trans.fif"
     trans0.save(fname1)
-    assert fname1 == _find_trans("sample", subjects_dir=tmp_path)
+    trans1, got_fname = _find_trans(
+        trans="auto", subject="sample", subjects_dir=tmp_path
+    )
+    assert fname1 == got_fname
     trans1 = read_trans(fname1)
 
     # check all properties

mne/transforms.py

@@ -227,19 +227,30 @@ def _print_coord_trans(
         )
 
 
-def _find_trans(subject, subjects_dir=None):
-    if subject is None:
-        if "SUBJECT" in os.environ:
-            subject = os.environ["SUBJECT"]
-        else:
-            raise ValueError("SUBJECT environment variable not set")
-
-    trans_fnames = glob.glob(str(subjects_dir / subject / "*-trans.fif"))
-    if len(trans_fnames) < 1:
-        raise RuntimeError(f"Could not find the transformation for {subject}")
-    elif len(trans_fnames) > 1:
-        raise RuntimeError(f"Found multiple transformations for {subject}")
-    return Path(trans_fnames[0])
+def _find_trans(*, trans, subject, subjects_dir=None):
+    if isinstance(trans, str) and trans == "auto":
+        subjects_dir = get_subjects_dir(subjects_dir, raise_error=True)
+        # let's try to do this in MRI coordinates so they're easy to plot
+        if subject is None:
+            if "SUBJECT" in os.environ:
+                subject = os.environ["SUBJECT"]
+            else:
+                raise ValueError(
+                    "subject is None and SUBJECT environment variable not set, cannot "
+                    "use trans='auto'"
+                )
+        glob_str = str(subjects_dir / subject / "*-trans.fif")
+        trans_fnames = glob.glob(glob_str)
+        if len(trans_fnames) < 1:
+            raise RuntimeError(
+                f"Could not find the transformation for {subject} in: {glob_str}"
+            )
+        elif len(trans_fnames) > 1:
+            raise RuntimeError(
+                f"Found multiple transformations for {subject} in: {glob_str}"
+            )
+        trans = Path(trans_fnames[0])
+    return _get_trans(trans, fro="head", to="mri")
 
 
 def apply_trans(trans, pts, move=True):

mne/viz/_3d.py

@@ -720,11 +720,12 @@ def plot_alignment(
                 f'subject ("{subject}") did not match the '
                 f'subject name in src ("{src_subject}")'
             )
-    # configure transforms
-    if isinstance(trans, str) and trans == "auto":
-        subjects_dir = get_subjects_dir(subjects_dir, raise_error=True)
-        trans = _find_trans(subject, subjects_dir)
-    trans, trans_type = _get_trans(trans, fro="head", to="mri")
+
+    trans, trans_type = _find_trans(
+        trans=trans,
+        subject=subject,
+        subjects_dir=subjects_dir,
+    )
 
     picks = pick_types(
         info,