MRG: Link brains with _LinkViewer and plot_linked_brains (mne-tools#7227

)

* Build first prototype

* Fix docstring

* Synchronize the slider handle

* Add representation memory to IntSlider and ShowView

* Introduce SmartSlider

* Update time callback

* Update orientation callback

* Change default name of the time slider

* Update smoothing call

* Update fmin/fmid/fmax callbacks

* Update fscale callback

* Improve performance for auto_scaling

* Use local _update_slider_callback

* Improve plot_linked_brains docstring

* Add plot_linked_brains to reference

* Link play and playback speed

* Update docstring

* Add plot_linked_brains to tests

* Add _LinkViewer to tests

* Rename plot_linked_brains into link_brains

* Remove local patch for normalized coordinate system

* Fix double _TimeViewer wrapping

* Fix issue with slider placement

* Fix UI inconsistency

* Change playback speed title to short version

* Update latest and overview table

* Fix name spelling

* Implement reviews

doc/changes/latest.inc

@@ -99,6 +99,7 @@ Changelog
 
 - Add ``border`` argument to :func:`mne.viz.plot_topomap`. ``border`` controls the value of the edge points to which topomap values are extrapolated. ``border='mean'`` sets these points value to the average of their neighbours. By `Mikołaj Magnuski`_
 
+- Add function :func:`mne.viz.link_brains` to link time properties of multiple brain objects interactively by `Guillaume Favelier`_
 
 Bug
 ~~~

doc/python_reference.rst

@@ -261,6 +261,7 @@ Visualization
    plot_sensors_connectivity
    plot_snr_estimate
    plot_source_estimates
+   link_brains
    plot_volume_source_estimates
    plot_vector_source_estimates
    plot_sparse_source_estimates

mne/viz/_3d.py

@@ -16,6 +16,7 @@
 from itertools import cycle
 import os.path as op
 import warnings
+import collections
 from functools import partial
 
 import numpy as np
@@ -1536,6 +1537,35 @@ def _plot_mpl_stc(stc, subject=None, surface='inflated', hemi='lh',
     return fig
 
 
+def link_brains(brains):
+    """Plot multiple SourceEstimate objects with PyVista.
+
+    Parameters
+    ----------
+    brains : list, tuple or np.ndarray
+        The collection of brains to plot.
+    """
+    from .backends.renderer import get_3d_backend
+    if get_3d_backend() != 'pyvista':
+        raise NotImplementedError("Expected 3d backend is pyvista but"
+                                  " {} was given.".format(get_3d_backend()))
+    from ._brain import _Brain, _TimeViewer, _LinkViewer
+    if not isinstance(brains, collections.Iterable):
+        brains = [brains]
+    if len(brains) == 0:
+        raise ValueError("The collection of brains is empty.")
+    for brain in brains:
+        if isinstance(brain, _Brain):
+            # check if the _TimeViewer wrapping is not already applied
+            if not hasattr(brain, 'time_viewer') or brain.time_viewer is None:
+                brain = _TimeViewer(brain)
+        else:
+            raise TypeError("Expected type is Brain but"
+                            " {} was given.".format(type(brain)))
+    # link brains properties
+    _LinkViewer(brains)
+
+
 @verbose
 def plot_source_estimates(stc, subject=None, surface='inflated', hemi='lh',
                           colormap='auto', time_label='auto',

mne/viz/__init__.py

@@ -10,7 +10,8 @@
                   plot_vector_source_estimates, plot_evoked_field,
                   plot_dipole_locations, snapshot_brain_montage,
                   plot_head_positions, plot_alignment, plot_brain_colorbar,
-                  plot_volume_source_estimates, plot_sensors_connectivity)
+                  plot_volume_source_estimates, plot_sensors_connectivity,
+                  link_brains)
 from .misc import (plot_cov, plot_csd, plot_bem, plot_events,
                    plot_source_spectrogram, _get_presser,
                    plot_dipole_amplitudes, plot_ideal_filter, plot_filter,

mne/viz/_brain/__init__.py

@@ -10,6 +10,6 @@
 # License: Simplified BSD
 
 from ._brain import _Brain
-from ._timeviewer import _TimeViewer
+from ._timeviewer import _TimeViewer, _LinkViewer
 
 __all__ = ['_Brain']