Add sourcespace to Report (#12848)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Eric Larson <larson.eric.d@gmail.com>

Author: 3 people

doc/changes/devel/12848.newfeature.rst

@@ -0,0 +1 @@
+Add source space(s) visualization(s) in :func:`mne.Report.add_forward`, by `Victor Ferat`_.

mne/report/report.py

@@ -475,7 +475,17 @@ def _fig_to_img(
 
 
 def _get_bem_contour_figs_as_arrays(
-    *, sl, n_jobs, mri_fname, surfaces, orientation, src, show, show_orientation, width
+    *,
+    sl,
+    n_jobs,
+    mri_fname,
+    surfaces,
+    orientation,
+    src,
+    trans,
+    show,
+    show_orientation,
+    width,
 ):
     """Render BEM surface contours on MRI slices.
 
@@ -494,6 +504,7 @@ def _get_bem_contour_figs_as_arrays(
             surfaces=surfaces,
             orientation=orientation,
             src=src,
+            trans=trans,
             show=show,
             show_orientation=show_orientation,
             width=width,
@@ -507,6 +518,21 @@ def _get_bem_contour_figs_as_arrays(
     return out
 
 
+def _iterate_alignment_views(function, alpha, **kwargs):
+    """Auxiliary function to iterate over views in trans fig."""
+    from ..viz.backends.renderer import MNE_3D_BACKEND_TESTING
+
+    # TODO: Eventually maybe we should expose the size option?
+    size = (80, 80) if MNE_3D_BACKEND_TESTING else (800, 800)
+    fig = create_3d_figure(size, bgcolor=(0.5, 0.5, 0.5))
+    from ..viz.backends.renderer import backend
+
+    try:
+        return _itv(function, fig, **kwargs)
+    finally:
+        backend._close_3d_figure(fig)
+
+
 def _iterate_trans_views(function, alpha, **kwargs):
     """Auxiliary function to iterate over views in trans fig."""
     from ..viz.backends.renderer import MNE_3D_BACKEND_TESTING
@@ -531,7 +557,18 @@ def _itv(function, fig, *, max_width=MAX_IMG_WIDTH, max_res=MAX_IMG_RES, **kwarg
 
     function(fig=fig, **kwargs)
 
-    views = ("frontal", "lateral", "medial", "axial", "rostral", "coronal")
+    views = (
+        "right_lateral",
+        "right_anterolateral",
+        "anterior",
+        "left_anterolateral",
+        "left_lateral",
+        "superior",
+        "right_posterolateral",
+        "posterior",
+        "left_posterolateral",
+        "inferior",
+    )
 
     images = []
     for view in views:
@@ -544,7 +581,7 @@ def _itv(function, fig, *, max_width=MAX_IMG_WIDTH, max_res=MAX_IMG_RES, **kwarg
         images.append(im)
 
     images = np.concatenate(
-        [np.concatenate(images[:3], axis=1), np.concatenate(images[3:], axis=1)], axis=0
+        [np.concatenate(images[:5], axis=1), np.concatenate(images[5:], axis=1)], axis=0
     )
 
     try:
@@ -2655,6 +2692,8 @@ def add_bem(
         self._add_bem(
             subject=subject,
             subjects_dir=subjects_dir,
+            src=None,
+            trans=None,
             decim=decim,
             n_jobs=n_jobs,
             width=width,
@@ -3245,6 +3284,8 @@ def _render_one_bem_axis(
         surfaces,
         image_format,
         orientation,
+        src=None,
+        trans=None,
         decim=2,
         n_jobs=None,
         width=512,
@@ -3265,7 +3306,8 @@ def _render_one_bem_axis(
             mri_fname=mri_fname,
             surfaces=surfaces,
             orientation=orientation,
-            src=None,
+            src=src,
+            trans=trans,
             show=False,
             show_orientation="always",
             width=width,
@@ -3574,6 +3616,89 @@ def _add_forward(
             replace=replace,
         )
 
+        if subject:
+            src = forward["src"]
+            trans = forward["mri_head_t"]
+            # Alignment
+            kwargs = dict(
+                info=forward["info"],
+                trans=trans,
+                src=src,
+                subject=subject,
+                subjects_dir=subjects_dir,
+                meg=["helmet", "sensors"],
+                show_axes=True,
+                eeg=dict(original=0.2, projected=0.8),
+                coord_frame="mri",
+            )
+            img, _ = _iterate_trans_views(
+                function=plot_alignment,
+                alpha=0.5,
+                max_width=self.img_max_width,
+                max_res=self.img_max_res,
+                **kwargs,
+            )
+            self._add_image(
+                img=img,
+                title="Alignment",
+                section=section,
+                caption=None,
+                image_format="png",
+                tags=tags,
+                replace=replace,
+            )
+            # Source space
+            kwargs = dict(
+                trans=trans,
+                subjects_dir=subjects_dir,
+            )
+
+            self._add_bem(
+                subject=subject,
+                subjects_dir=subjects_dir,
+                src=src,
+                trans=trans,
+                decim=1,
+                n_jobs=1,
+                width=512,
+                image_format=image_format,
+                title="Source space(s) (BEM view)",
+                section=section,
+                tags=tags,
+                replace=replace,
+            )
+
+            if src.kind == "surface" or src.kind == "mixed":
+                surfaces = dict(head=0.1, white=0.5)
+            else:
+                surfaces = dict(head=0.1)
+
+            kwargs = dict(
+                trans=trans,
+                src=src,
+                subject=subject,
+                subjects_dir=subjects_dir,
+                show_axes=False,
+                coord_frame="mri",
+                surfaces=surfaces,
+            )
+            img, _ = _iterate_alignment_views(
+                function=plot_alignment,
+                alpha=0.5,
+                max_width=self.img_max_width,
+                max_res=self.img_max_res,
+                **kwargs,
+            )
+            self._add_image(
+                img=img,
+                title="Source space(s) (3D view)",
+                section=section,
+                caption=None,
+                image_format="png",
+                tags=tags,
+                replace=replace,
+            )
+
     def _add_inverse_operator(
         self,
         *,
@@ -4440,13 +4565,15 @@ def _add_bem(
         *,
         subject,
         subjects_dir,
+        src,
+        trans,
         decim,
         n_jobs,
         width=512,
         image_format,
         title,
-        tags,
         section,
+        tags,
         replace,
     ):
         """Render mri+bem (only PNG)."""
@@ -4472,6 +4599,8 @@ def _add_bem(
                 mri_fname=mri_fname,
                 surfaces=surfaces,
                 orientation=orientation,
+                src=src,
+                trans=trans,
                 decim=decim,
                 n_jobs=n_jobs,
                 width=width,

mne/report/tests/test_report.py

@@ -514,6 +514,29 @@ def test_add_bem_n_jobs(n_jobs, monkeypatch):
     assert 0.778 < corr < 0.80
 
 
+@pytest.mark.filterwarnings("ignore:Distances could not be calculated.*:RuntimeWarning")
+@pytest.mark.slowtest
+@testing.requires_testing_data
+def test_add_forward(renderer_interactive_pyvistaqt):
+    """Test add_forward."""
+    report = Report(subjects_dir=subjects_dir, image_format="png")
+    report.add_forward(
+        forward=fwd_fname,
+        subject="sample",
+        subjects_dir=subjects_dir,
+        title="Forward solution",
+    )
+    assert len(report.html) == 4
+
+    report = Report(subjects_dir=subjects_dir, image_format="png")
+    report.add_forward(
+        forward=fwd_fname,
+        subjects_dir=subjects_dir,
+        title="Forward solution",
+    )
+    assert len(report.html) == 1
+
+
 @testing.requires_testing_data
 def test_render_mri_without_bem(tmp_path):
     """Test rendering MRI without BEM for mne report."""
@@ -882,7 +905,8 @@ def test_survive_pickle(tmp_path):
 
 @pytest.mark.slowtest  # ~30 s on Azure Windows
 @testing.requires_testing_data
-def test_manual_report_2d(tmp_path, invisible_fig):
+@pytest.mark.filterwarnings("ignore:Distances could not be calculated.*:RuntimeWarning")
+def test_manual_report_2d(tmp_path, invisible_fig, renderer_pyvistaqt):
     """Simulate user manually creating report by adding one file at a time."""
     pytest.importorskip("sklearn")
     pytest.importorskip("pandas")

mne/source_space/_source_space.py

@@ -329,6 +329,8 @@ def plot(
         skull=None,
         subjects_dir=None,
         trans=None,
+        *,
+        fig=None,
         verbose=None,
     ):
         """Plot the source space.
@@ -358,6 +360,11 @@ def plot(
             produced during coregistration. If trans is None, an identity
             matrix is assumed. This is only needed when the source space is in
             head coordinates.
+        fig : Figure3D | None
+            PyVista scene in which to plot the alignment.
+            If ``None``, creates a new 600x600 pixel figure with black background.
+
+            .. versionadded:: 1.10
         %(verbose)s
 
         Returns
@@ -427,6 +434,7 @@ def plot(
             ecog=False,
             bem=bem,
             src=self,
+            fig=fig,
         )
 
     def __getitem__(self, *args, **kwargs):

mne/tests/test_epochs.py

@@ -591,7 +591,7 @@ def my_reject_2(epoch_data):
         for kwarg in ("reject", "flat"):
             with pytest.raises(
                 TypeError,
-                match=r".* must be an instance of .* got <class '.*'> instead.",
+                match=r".* must be an instance of .* got .* instead.",
             ):
                 epochs = Epochs(
                     raw,

mne/transforms.py

@@ -439,7 +439,7 @@ def translation(x=0, y=0, z=0):
     return m
 
 
-def _ensure_trans(trans, fro="mri", to="head"):
+def _ensure_trans(trans, fro="mri", to="head", *, extra=""):
     """Ensure we have the proper transform."""
     if isinstance(fro, str):
         from_str = fro
@@ -455,7 +455,8 @@ def _ensure_trans(trans, fro="mri", to="head"):
         to_str = _frame_to_str[to]
         to_const = to
     del to
-    err_str = f"trans must be a Transform between {from_str}<->{to_str}, got"
+    extra = f" {extra}" if extra else ""
+    err_str = f"trans must be a Transform between {from_str}<->{to_str}{extra}, got"
     if not isinstance(trans, list | tuple):
         trans = [trans]
     # Ensure that we have exactly one match
@@ -481,12 +482,12 @@ def _ensure_trans(trans, fro="mri", to="head"):
     return trans
 
 
-def _get_trans(trans, fro="mri", to="head", allow_none=True):
+def _get_trans(trans, fro="mri", to="head", allow_none=True, *, extra=""):
     """Get mri_head_t (from=mri, to=head) from mri filename."""
     types = (Transform, "path-like")
     if allow_none:
         types += (None,)
-    _validate_type(trans, types, "trans")
+    _validate_type(trans, types, "trans", extra=extra)
     if _path_like(trans):
         if trans == "fsaverage":
             trans = Path(__file__).parent / "data" / "fsaverage" / "fsaverage-trans.fif"
@@ -510,7 +511,7 @@ def _get_trans(trans, fro="mri", to="head", allow_none=True):
         fro_to_t = Transform(fro, to)
         trans = "identity"
     # it's usually a head->MRI transform, so we probably need to invert it
-    fro_to_t = _ensure_trans(fro_to_t, fro, to)
+    fro_to_t = _ensure_trans(fro_to_t, fro, to, extra=extra)
     return fro_to_t, trans
 
 

mne/utils/check.py

@@ -641,9 +641,10 @@ def _validate_type(item, types=None, item_name=None, type_name=None, *, extra=""
                 type_name[-1] = "or " + type_name[-1]
                 type_name = ", ".join(type_name)
         _item_name = "Item" if item_name is None else item_name
+        _item_type = type(item) if item is not None else item
         raise TypeError(
             f"{_item_name} must be an instance of {type_name}{extra}, "
-            f"got {type(item)} instead."
+            f"got {_item_type} instead."
         )
 
 

mne/viz/_brain/view.py

@@ -49,6 +49,40 @@
     rh_views_dict["flat"] = dict(
         azimuth=0, elevation=0, focalpoint=ORIGIN, roll=0, distance=DIST
     )
+
+both_views_dict = lh_views_dict.copy()
+both_views_dict["right_lateral"] = dict(
+    azimuth=180.0, elevation=90.0, focalpoint=ORIGIN, distance=DIST
+)
+both_views_dict["right_anterolateral"] = dict(
+    azimuth=120.0, elevation=90.0, focalpoint=ORIGIN, distance=DIST
+)
+both_views_dict["anterior"] = dict(
+    azimuth=90.0, elevation=90.0, focalpoint=ORIGIN, distance=DIST
+)
+both_views_dict["left_anterolateral"] = dict(
+    azimuth=60.0, elevation=90.0, focalpoint=ORIGIN, distance=DIST
+)
+both_views_dict["left_lateral"] = dict(
+    azimuth=180.0, elevation=-90.0, focalpoint=ORIGIN, distance=DIST
+)
+both_views_dict["right_posterolateral"] = dict(
+    azimuth=-120.0, elevation=90.0, focalpoint=ORIGIN, distance=DIST
+)
+both_views_dict["posterior"] = dict(
+    azimuth=90.0, elevation=-90.0, focalpoint=ORIGIN, distance=DIST
+)
+both_views_dict["left_posterolateral"] = dict(
+    azimuth=-60.0, elevation=90.0, focalpoint=ORIGIN, distance=DIST
+)
+both_views_dict["superior"] = dict(
+    azimuth=180.0, elevation=0.0, focalpoint=ORIGIN, distance=DIST
+)
+both_views_dict["inferior"] = dict(
+    azimuth=180.0, elevation=180.0, focalpoint=ORIGIN, distance=DIST
+)
+
+
 views_dicts = dict(
-    lh=lh_views_dict, vol=lh_views_dict, both=lh_views_dict, rh=rh_views_dict
+    lh=lh_views_dict, vol=lh_views_dict, both=both_views_dict, rh=rh_views_dict
 )