ENH: Improve report plotting and animate_topomap (#13905)

Author: larsoner

.circleci/config.yml

@@ -222,7 +222,7 @@ jobs:
           keys:
             - data-cache-ds004388
       - run:
-          name: Get data
+          name: Get data and triage examples to run
           # This limit could be increased, but this is helpful for finding slow ones
           # (even ~2GB datasets should be downloadable in this time from good
           # providers)

doc/changes/dev/13905.apichange.rst

@@ -0,0 +1 @@
+In :meth:`mne.Evoked.animate_topomap` the ``vmin`` and ``vmax`` keyword arguments have been deprecated in favor of ``vlim``, by `Eric Larson`_.

doc/changes/dev/13905.newfeature.rst

@@ -0,0 +1,7 @@
+Improved :class:`mne.Report` by:
+
+- Using ``"agg"`` backend for 2D plots to avoid windows unnecessarily popping up
+- Improving :meth:`~mne.Report.add_stc` by using direct capture of brain images, allowing direct control of image size using ``stc_plot_kwargs["size"]``
+- Improving :meth:`~mne.Report.add_evokeds` evoked topomap plotting by using :meth:`mne.Evoked.animate_topomap` with ``butterfly=True`` rather than re-plotting each topomap in a loop
+
+Also improved :meth:`mne.Evoked.animate_topomap` by deduplicating code with :meth:`mne.Evoked.plot_topomap`. Changes by `Eric Larson`_.

examples/visualization/evoked_topomap.py

@@ -192,4 +192,4 @@
 
 # sphinx_gallery_thumbnail_number = 9
 times = np.arange(0.05, 0.151, 0.01)
-fig, anim = evoked.animate_topomap(times=times, ch_type="mag", frame_rate=2, blit=False)
+fig, anim = evoked.animate_topomap(times=times, ch_type="mag", frame_rate=2)

mne/evoked.py

@@ -791,21 +791,40 @@ def plot_joint(
             topomap_args=topomap_args,
         )
 
-    @fill_doc
+    @verbose
     def animate_topomap(
         self,
-        ch_type=None,
-        times=None,
-        frame_rate=None,
         *,
+        times=None,
+        average=None,
+        ch_type=None,
+        scalings=None,
+        proj=False,
+        sensors=True,
+        show_names=False,
+        mask=None,
+        mask_params=None,
+        contours=6,
+        outlines="head",
+        sphere=None,
+        image_interp=_INTERPOLATION_DEFAULT,
+        extrapolate=_EXTRAPOLATE_DEFAULT,
+        border=_BORDER_DEFAULT,
+        res=64,
+        size=1.0,
         cmap=None,
+        vlim=(None, None),
+        cnorm=None,
+        colorbar=True,
+        cbar_fmt="%3.1f",
+        units=None,
+        axes=None,
+        time_unit="s",
+        time_format=None,
+        frame_rate=None,
         butterfly=False,
         blit=True,
         show=True,
-        time_unit="s",
-        sphere=None,
-        image_interp=_INTERPOLATION_DEFAULT,
-        extrapolate=_EXTRAPOLATE_DEFAULT,
         vmin=None,
         vmax=None,
         verbose=None,
@@ -818,23 +837,44 @@ def animate_topomap(
 
         Parameters
         ----------
-        ch_type : str | None
-            Channel type to plot. Accepted data types: 'mag', 'grad', 'eeg',
-            'hbo', 'hbr', 'fnirs_cw_amplitude',
-            'fnirs_fd_ac_amplitude', 'fnirs_fd_phase', and 'fnirs_od'.
-            If None, first available channel type from the above list is used.
-            Defaults to None.
         times : array of float | None
-            The time points to plot. If None, 10 evenly spaced samples are
-            calculated over the evoked time series. Defaults to None.
+            The time points to plot. If None (default), 10 evenly spaced samples are
+            calculated over the evoked time series.
+        %(average_plot_evoked_topomap)s
+        %(ch_type_topomap)s
+        %(scalings_topomap)s
+        %(proj_plot)s
+        %(sensors_topomap)s
+        %(show_names_topomap)s
+        %(mask_evoked_topomap)s
+        %(mask_params_topomap)s
+        %(contours_topomap)s
+        %(outlines_topomap)s
+        %(sphere_topomap_auto)s
+        %(image_interp_topomap)s
+        %(extrapolate_topomap)s
+        %(border_topomap)s
+        %(res_topomap)s
+        %(size_topomap)s
+        %(cmap_topomap)s
+        %(vlim_plot_topomap_psd)s
+        %(cnorm)s
+        %(colorbar_topomap)s
+        %(cbar_fmt_topomap)s
+        %(units_topomap_evoked)s
+        axes : list of matplotlib.axes.Axes | None
+            The axes to use for plotting. Must have one axis for the topomap,
+            then one for the colorbar (if ``colorbar=True``), then one for the
+            butterfly axes (if ``butterfly=True``).
+        time_unit : str
+            The units for the time axis, can be "ms" or "s" (default).
+        time_format : str | None
+            String format for topomap values. Defaults (None) to "%%01d ms" if
+            ``time_unit='ms'``, "%%0.3f s" if ``time_unit='s'``, and
+            "%%g" otherwise. Can be an empty string to omit the time label.
         frame_rate : int | None
             Frame rate for the animation in Hz. If None,
             frame rate = sfreq / 10. Defaults to None.
-        cmap : matplotlib colormap | None
-            Colormap to use. If None, 'Reds' is used for all positive data,
-            otherwise defaults to 'RdBu_r'.
-
-            .. versionadded:: 1.12.0
         butterfly : bool
             Whether to plot the data as butterfly plot under the topomap.
             Defaults to False.
@@ -845,19 +885,10 @@ def animate_topomap(
             Defaults to True.
         show : bool
             Whether to show the animation. Defaults to True.
-        time_unit : str
-            The units for the time axis, can be "ms" (default in 0.16)
-            or "s" (will become the default in 0.17).
-
-            .. versionadded:: 0.16
-        %(sphere_topomap_auto)s
-        %(image_interp_topomap)s
-        %(extrapolate_topomap)s
-
-            .. versionadded:: 0.22
-        %(vmin_vmax_topomap)s
-
-            .. versionadded:: 1.1.0
+        vmin : float | None
+            Deprecated, use ``vlim=(vmin, vmax)`` instead.
+        vmax : float | None
+            Deprecated, use ``vlim=(vmin, vmax)`` instead.
         %(verbose)s
 
         Returns
@@ -869,24 +900,46 @@ def animate_topomap(
 
         Notes
         -----
+        .. versionchanged:: 1.13.0
+           The ``vmin`` and ``vmax`` parameters were deprecated in favor of a single
+           ``vlim`` parameter, and parameters were added and reordered to follow
+           :meth:`~mne.Evoked.plot_topomap`.
         .. versionadded:: 0.12.0
         """
         return _topomap_animation(
-            self,
-            ch_type=ch_type,
+            evoked=self,
             times=times,
-            frame_rate=frame_rate,
-            butterfly=butterfly,
-            blit=blit,
-            show=show,
-            time_unit=time_unit,
+            average=average,
+            ch_type=ch_type,
+            scalings=scalings,
+            proj=proj,
+            sensors=sensors,
+            show_names=show_names,
+            mask=mask,
+            mask_params=mask_params,
+            contours=contours,
+            outlines=outlines,
             sphere=sphere,
             image_interp=image_interp,
             extrapolate=extrapolate,
+            border=border,
+            res=res,
+            size=size,
+            cmap=cmap,
+            vlim=vlim,
+            cnorm=cnorm,
+            colorbar=colorbar,
+            cbar_fmt=cbar_fmt,
+            units=units,
+            axes=axes,
+            time_unit=time_unit,
+            time_format=time_format,
+            frame_rate=frame_rate,
+            butterfly=butterfly,
+            blit=blit,
             vmin=vmin,
             vmax=vmax,
-            verbose=verbose,
-            cmap=cmap,
+            show=show,
         )
 
     def as_type(self, ch_type="grad", mode="fast"):