ENH: Add plot_kwargs to report.add_trans (#13234)

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

Author: sappelhoff

doc/changes/devel/13234.newfeature.rst

@@ -0,0 +1 @@
+Add a new parameter ``plot_kwargs`` to :meth:`mne.Report.add_trans`, to control low level properties of the visualization, by `Stefan Appelhoff`_.

mne/defaults.py

@@ -265,6 +265,7 @@
         nasion_color=(0.0, 1.0, 0.0),
         rpa_color=(0.0, 0.0, 1.0),
     ),
+    report_coreg=dict(dig=True, meg=("helmet", "sensors"), show_axes=True),
     noise_std=dict(grad=5e-13, mag=20e-15, eeg=0.2e-6),
     eloreta_options=dict(eps=1e-6, max_iter=20, force_equal=False),
     depth_mne=dict(

mne/report/report.py

@@ -518,9 +518,10 @@ def _iterate_trans_views(function, alpha, **kwargs):
 
     try:
         try:
-            return _itv(function, fig, surfaces={"head-dense": alpha}, **kwargs)
+            return _itv(function, fig, **kwargs)
         except OSError:
-            return _itv(function, fig, surfaces={"head": alpha}, **kwargs)
+            kwargs["surfaces"] = {"head": alpha}
+            return _itv(function, fig, **kwargs)
     finally:
         backend._close_3d_figure(fig)
 
@@ -1597,9 +1598,10 @@ def add_trans(
         subject=None,
         subjects_dir=None,
         alpha=None,
+        coord_frame="mri",
+        plot_kwargs=None,
         tags=("coregistration",),
         section=None,
-        coord_frame="mri",
         replace=False,
     ):
         """Add a coregistration visualization to the report.
@@ -1625,13 +1627,23 @@ def add_trans(
         alpha : float | None
             The level of opacity to apply to the head surface. If a float, must
             be between 0 and 1 (inclusive), where 1 means fully opaque. If
-            ``None``, will use the MNE-Python default value.
+            ``None``, will use the MNE-Python default value. See also ``plot_kwargs``.
+        coord_frame : 'auto' | 'head' | 'meg' | 'mri'
+            Coordinate frame used for plotting. See :func:`mne.viz.plot_alignment`
+            and ``plot_kwargs``.
+        plot_kwargs : dict | None
+            Plotting arguments to be passed to :func:`mne.viz.plot_alignment`.
+            If ``alpha`` is not ``None``, it will override a potential
+            ``plot_kwargs["alpha"]``. The ``coord_frame`` key word argument always
+            overrides a potential ``plot_kwargs["coord_frame"]``. If ``None``,
+            this defaults to
+            ``dict(dig=True, meg=("helmet", "sensors"), show_axes=True)``.
+
+            .. versionadded:: 1.10
         %(tags_report)s
         %(section_report)s
 
             .. versionadded:: 1.9
-        coord_frame : 'auto' | 'head' | 'meg' | 'mri'
-            Coordinate frame used for plotting. See :func:`mne.viz.plot_alignment`.
         %(replace_report)s
 
         Notes
@@ -1645,6 +1657,7 @@ def add_trans(
             subject=subject,
             subjects_dir=subjects_dir,
             alpha=alpha,
+            plot_kwargs=plot_kwargs,
             title=title,
             section=section,
             tags=tags,
@@ -4220,6 +4233,7 @@ def _add_trans(
         subject,
         subjects_dir,
         alpha,
+        plot_kwargs,
         title,
         section,
         tags,
@@ -4232,22 +4246,40 @@ def _add_trans(
         if not isinstance(info, Info):
             info = read_info(info)
 
-        kwargs = dict(
-            info=info,
-            trans=trans,
-            subject=subject,
-            subjects_dir=subjects_dir,
-            dig=True,
-            meg=["helmet", "sensors"],
-            show_axes=True,
-            coord_frame=coord_frame,
+        plot_kwargs = _handle_default("report_coreg", plot_kwargs)
+
+        plot_kwargs.update(
+            dict(
+                info=info,
+                trans=trans,
+                subject=subject,
+                subjects_dir=subjects_dir,
+            )
         )
+
+        # This potentially overwrites information
+        plot_kwargs["coord_frame"] = coord_frame
+
+        if alpha is not None:
+            # if not available, fall back to plot_alignment default: 'auto'
+            surfaces = plot_kwargs.get("surfaces", "auto")
+            if isinstance(surfaces, dict):
+                surfaces = list(surfaces.keys())
+            elif isinstance(surfaces, list):
+                pass
+            elif isinstance(surfaces, str) and surfaces != "auto":
+                surfaces = [surfaces]
+            else:
+                surfaces = ["head-dense"]  # "auto"
+
+            surfaces = {surf: alpha for surf in surfaces}
+
         img, caption = _iterate_trans_views(
             function=plot_alignment,
             alpha=alpha,
             max_width=self.img_max_width,
             max_res=self.img_max_res,
-            **kwargs,
+            **plot_kwargs,
         )
         self._add_image(
             img=img,

mne/report/tests/test_report.py

@@ -1155,7 +1155,11 @@ def test_manual_report_3d(tmp_path, renderer):
     with info._unlock():
         dig, info["dig"] = info["dig"], []
     add_kwargs = dict(
-        trans=trans_fname, info=info, subject="sample", subjects_dir=subjects_dir
+        trans=trans_fname,
+        info=info,
+        subject="sample",
+        subjects_dir=subjects_dir,
+        alpha=0.75,
     )
     with (
         _record_warnings(),
@@ -1173,6 +1177,7 @@ def test_manual_report_3d(tmp_path, renderer):
     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
+    add_kwargs.update(plot_kwargs=dict(dig="fiducials"))  # test additional plot kwargs
     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(