Cross-figure event passing system

doc/visualization.rst

@@ -86,3 +86,7 @@ Visualization
    set_browser_backend
    get_browser_backend
    use_browser_backend
+   ui_events.publish
+   ui_events.subscribe
+   ui_events.link
+   ui_events.unlink

examples/visualization/ui_events.py

@@ -0,0 +1,47 @@
+"""
+.. _ex-plot-events:
+
+======================================
+Using the event system to link figures
+======================================
+
+Many of MNE-Python's figures are interactive. For example, you can select channels or
+scroll through time. The event system allows you to link figures together so that
+interacting with one figure will simultaneously update another figure.
+
+In this example, we'll be linking an evoked plot to a source estimate plot, such that
+selecting the time in one will also update the time in the other.
+
+Since the figures on our website don't have any interaction capabilities, this example
+will only work properly when run in an interactive environment.
+"""
+# Author: Marijn van Vliet <w.m.vanvliet@gmail.com>
+#
+# License: BSD-3-Clause
+
+# %%
+# Load some evoked and source data to plot.
+import matplotlib.pyplot as plt
+import mne
+
+data_path = mne.datasets.sample.data_path()
+evoked = mne.read_evokeds(
+    data_path / "MEG" / "sample" / "sample_audvis-ave.fif", condition="Left Auditory"
+)
+evoked.apply_baseline()
+stc = mne.read_source_estimate(data_path / "MEG" / "sample" / "sample_audvis-meg-eeg")
+evoked.crop(0, stc.times[-1])
+
+# %%
+# Enable interactivity. I'm not sure exactly why we need this.
+plt.ion()
+
+# %%
+# Plot both the source estimate plot, with time interaction enabled, and a sensor-level
+# topomap. Then link the figures together, so they can communicate. What kind of
+# information is communicated between figures depends on the figure types. In this case,
+# the information about the currently selected time is shared.
+fig1 = stc.plot("sample", subjects_dir=data_path / "subjects", initial_time=0.1)
+fig1.set_time_interpolation("linear")
+fig2 = evoked.plot_topomap("interactive")
+mne.viz.ui_events.link(fig1, fig2)

mne/utils/docs.py

@@ -1511,6 +1511,8 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75):
     and if absent, falls back to ``'estimated'``.
 """
 
+docdict["figure"] = "matplotlib.figure.Figure | " "MNEFigure | " "Figure3D | " "Brain"
+
 docdict[
     "fig_facecolor"
 ] = """\

mne/viz/__init__.py

@@ -87,3 +87,4 @@
 from ._brain import Brain
 from ._figure import get_browser_backend, set_browser_backend, use_browser_backend
 from ._proj import plot_projs_joint
+from . import ui_events

mne/viz/_brain/_brain.py

@@ -31,6 +31,8 @@
     UpdateColorbarScale,
 )
 
+from .. import ui_events
+
 from ..utils import (
     _show_help_fig,
     _get_color_list,
@@ -729,10 +731,7 @@ def reset(self):
         self.reset_view()
         max_time = len(self._data["time"]) - 1
         if max_time > 0:
-            self.callbacks["time"](
-                self._data["initial_time_idx"],
-                update_widget=True,
-            )
+            ui_events.publish(self, ui_events.TimeChange(time=self.data["time"][0]))
         self._renderer._update()
 
     def set_playback_speed(self, speed):
@@ -759,15 +758,10 @@ def _advance(self):
         delta = this_time - self._last_tick
         self._last_tick = time.time()
         time_data = self._data["time"]
-        times = np.arange(self._n_times)
         time_shift = delta * self.playback_speed
         max_time = np.max(time_data)
         time_point = min(self._current_time + time_shift, max_time)
-        # always use linear here -- this does not determine the data
-        # interpolation mode, it just finds where we are (in time) in
-        # terms of the time indices
-        idx = np.interp(time_point, time_data, times)
-        self.callbacks["time"](idx, update_widget=True)
+        ui_events.publish(self, ui_events.TimeChange(time=time_point))
         if time_point == max_time:
             self.toggle_playback(value=False)
 
@@ -822,12 +816,20 @@ def _configure_dock_playback_widget(self, name):
                 brain=self,
                 callback=self.plot_time_line,
             )
+
+            def publish_time_change_event(time_idx):
+                ui_events.publish(
+                    self,
+                    ui_events.TimeChange(time=self._time_interp_inv(time_idx)),
+                )
+
+            ui_events.subscribe(self, "time_change", self.callbacks["time"])
             self.widgets["time"] = self._renderer._dock_add_slider(
                 name="Time (s)",
                 value=self._data["time_idx"],
                 rng=[0, len_time],
                 double=True,
-                callback=self.callbacks["time"],
+                callback=publish_time_change_event,
                 compact=False,
                 layout=layout,
             )
@@ -1270,10 +1272,8 @@ def save_movie(filename, weakself=weakself):
         )
 
     def _shift_time(self, op):
-        self.callbacks["time"](
-            value=(op(self._current_time, self.playback_speed)),
-            time_as_index=False,
-            update_widget=True,
+        ui_events.publish(
+            self, ui_events.TimeChange(time=op(self._current_time, self.playback_speed))
         )
 
     def _rotate_azimuth(self, value):
@@ -3149,6 +3149,7 @@ def add_annotation(
 
     def close(self):
         """Close all figures and cleanup data structure."""
+        print("Closing abstract brain")
         self._closed = True
         self._renderer.close()
 
@@ -3490,7 +3491,7 @@ def set_data_smoothing(self, n_steps):
                         warn=False,
                     )
                 self._data[hemi]["smooth_mat"] = smooth_mat
-        self.set_time_point(self._data["time_idx"])
+        self._update_current_time_idx(self._data["time_idx"])
         self._data["smoothing_steps"] = n_steps
 
     @property
@@ -3532,8 +3533,8 @@ def set_time_interpolation(self, interpolation):
                     )
             self._time_interp_inv = _safe_interp1d(idx, self._times)
 
-    def set_time_point(self, time_idx):
-        """Set the time point shown (can be a float to interpolate).
+    def _update_current_time_idx(self, time_idx):
+        """Update all widgets in the figure to reflect a new time point.
 
         Parameters
         ----------
@@ -3604,6 +3605,27 @@ def set_time_point(self, time_idx):
         self._data["time_idx"] = time_idx
         self._renderer._update()
 
+    def set_time_point(self, time_idx):
+        """Set the time point to display (can be a float to interpolate).
+
+        Parameters
+        ----------
+        time_idx : int | float
+            The time index to use. Can be a float to use interpolation
+            between indices.
+        """
+        if self._times is None:
+            raise ValueError("Cannot set time when brain has no defined times.")
+        elif 0 <= time_idx <= len(self._times):
+            ui_events.publish(
+                self, ui_events.TimeChange(time=self._time_interp_inv(time_idx))
+            )
+        else:
+            raise ValueError(
+                f"Requested time point ({time_idx}) is outside the range of "
+                f"available time points (0-{len(self._times)})."
+            )
+
     def set_time(self, time):
         """Set the time to display (in seconds).
 
@@ -3615,9 +3637,7 @@ def set_time(self, time):
         if self._times is None:
             raise ValueError("Cannot set time when brain has no defined times.")
         elif min(self._times) <= time <= max(self._times):
-            self.set_time_point(
-                np.interp(float(time), self._times, np.arange(self._n_times))
-            )
+            ui_events.publish(self, ui_events.TimeChange(time=time))
         else:
             raise ValueError(
                 f"Requested time ({time} s) is outside the range of "
@@ -3987,7 +4007,7 @@ def _iter_time(self, time_idx, callback):
         Used by movie and image sequence saving functions.
         """
         if self.time_viewer:
-            func = partial(self.callbacks["time"], update_widget=True)
+            func = partial(self.callbacks["time"])
         else:
             func = self.set_time_point
         current_time_idx = self._data["time_idx"]

mne/viz/_brain/_linkviewer.py

@@ -116,7 +116,7 @@ def set_fmax(self, value):
 
     def set_time_point(self, value):
         for brain in self.brains:
-            brain.callbacks["time"](value, update_widget=True)
+            brain.callbacks["time"](value)
 
     def set_playback_speed(self, value):
         for brain in self.brains:

mne/viz/_brain/callback.py

@@ -22,18 +22,20 @@ def __init__(self, brain=None, callback=None):
         else:
             self.time_label = None
 
-    def __call__(self, value, update_widget=False, time_as_index=True):
+    def __call__(self, event):
         """Update the time slider."""
-        if not time_as_index:
-            value = self.brain._to_time_index(value)
-        self.brain.set_time_point(value)
+        if event.time == self.brain._current_time:
+            return
+
+        time_idx = self.brain._to_time_index(event.time)
+        self.brain._update_current_time_idx(time_idx)
         if self.label is not None:
             current_time = self.brain._current_time
             self.label.set_value(f"{current_time: .3f}")
         if self.callback is not None:
             self.callback()
-        if self.widget is not None and update_widget:
-            self.widget.set_value(int(value))
+        if self.widget is not None:
+            self.widget.set_value(int(time_idx))
 
 
 class UpdateColorbarScale:

mne/viz/backends/_abstract.py

@@ -10,6 +10,7 @@
 from contextlib import nullcontext
 import warnings
 
+from .. import ui_events
 from ..utils import tight_layout
 
 
@@ -1415,7 +1416,7 @@ def __init__(self, brain, width, height, dpi):
         """Initialize the MplCanvas."""
         super().__init__(width, height, dpi)
         self.brain = brain
-        self.time_func = brain.callbacks["time"]
+        # self.time_func = brain.callbacks["time"]
 
     def update_plot(self):
         """Update the plot."""
@@ -1434,7 +1435,7 @@ def on_button_press(self, event):
         # left click (and maybe drag) in progress in axes
         if event.inaxes != self.axes or event.button != 1:
             return
-        self.time_func(event.xdata, update_widget=True, time_as_index=False)
+        ui_events.publish(self.brain, ui_events.TimeChange(time=event.xdata))
 
     on_motion_notify = on_button_press  # for now they can be the same
 

mne/viz/backends/_pyvista.py

@@ -813,6 +813,7 @@ def show(self):
         self.plotter.show()
 
     def close(self):
+        print("PyvistaQT close")
         _close_3d_figure(figure=self.figure)
 
     def get_camera(self):