MRG: Plot label time course with Brain (#8335)

* Follow Brain update

* Upload prototype

* Remove 'tube' borders

* Rename variables

* Update clear_glyphs()

* Use _brain_color

* Fix docstring

* Improve support of traces and update tests

* Introduce _configure_label_time_course

* Add label tool bar

* Add support for max mode

* Refactor _update

* Add support for src

* Remove GFP in label picking mode

* Plot time line

* Fetch src when possible

* Update overview table

* Use only src_vol

* TST: refactor _triage_stc out

* Use _check_stc

* Fix test_brain_init[mayavi]

* Fix test_brain_traces[pyvista-mixed]

* Disable annot traces for volume/mixed

* Uncomment stc ValueError

* Improve testing and fix label_name

* Improve API

* Improve testing

* Improve testing

* Fix add_data parameter

* Improve coverage

* Use dict for label_data

* Prototype with show_traces

* Add _read_annot_cands

* Configure UI for traces mode toggle

* Organize signals, clear memory and update tests

* Switch to simplified interface

* Exclude .ctab files

* Improve coverage

* Update overview table

* Improve coverage

* Remove cruft

* Improve coverage

* Improve coverage

* Improve coverage

* Improve coverage

* Remove cruft

* Improve coverage

* Improve coverage

* TST: Hide app window during testing

* Revert "TST: Hide app window during testing"

This reverts commit f513448.

* Refactor tests

* Fix default annot bug

* Fix renderer bug

* Test GHA skipping [skip ci]

* Synchronize branch

* Fix test_resolution_matrix

* Add _configure_trace_mode

* Improve read_annot_cands

* Simplify annot mode color

* Remove cruft

* Add _check_stc_src

* Cast to int64

* Add support for vec

* Add support for mixed

* Do not show trace mode for volumes

* Update tests

* Fix vec

* Test mixed too

* Update tests

* Cleanup

* Trigger Circle [circle front]

* Cover vol as well

* Update tests

* Add vector to the list

* Fix style

* Restore label name

* Exclude pca_flip

* DRY

* Update _add_vertex_glyph with render parameter

Author: GuillaumeFavelier

mne/label.py

@@ -1880,7 +1880,8 @@ def _read_annot_cands(dir_name):
         raise IOError('Directory for annotation does not exist: %s',
                       dir_name)
     cands = os.listdir(dir_name)
-    cands = sorted(set(c.lstrip('lh.').lstrip('rh.').rstrip('.annot')
+    cands = sorted(set(c.replace('lh.', '').replace('rh.', '').replace(
+                       '.annot', '')
                        for c in cands if '.annot' in c),
                    key=lambda x: x.lower())
     # exclude .ctab files

mne/source_estimate.py

@@ -2860,6 +2860,16 @@ def _temporary_vertices(src, vertices):
             s['vertno'] = v
 
 
+def _check_stc_src(stc, src):
+    if stc is not None and src is not None:
+        for s, v, hemi in zip(src, stc.vertices, ('left', 'right')):
+            n_missing = (~np.in1d(v, s['vertno'])).sum()
+            if n_missing:
+                raise ValueError('%d/%d %s hemisphere stc vertices '
+                                 'missing from the source space, likely '
+                                 'mismatch' % (n_missing, len(v), hemi))
+
+
 def _prepare_label_extraction(stc, labels, src, mode, allow_empty, use_sparse):
     """Prepare indices and flips for extract_label_time_course."""
     # If src is a mixed src space, the first 2 src spaces are surf type and
@@ -2872,18 +2882,8 @@ def _prepare_label_extraction(stc, labels, src, mode, allow_empty, use_sparse):
 
     # if source estimate provided in stc, get vertices from source space and
     # check that they are the same as in the stcs
-    if stc is not None:
-        vertno = stc.vertices
-
-        for s, v, hemi in zip(src, stc.vertices, ('left', 'right')):
-            n_missing = (~np.in1d(v, s['vertno'])).sum()
-            if n_missing:
-                raise ValueError('%d/%d %s hemisphere stc vertices missing '
-                                 'from the source space, likely mismatch'
-                                 % (n_missing, len(v), hemi))
-    else:
-        vertno = [s['vertno'] for s in src]
-
+    _check_stc_src(stc, src)
+    vertno = [s['vertno'] for s in src] if stc is None else stc.vertices
     nvert = [len(vn) for vn in vertno]
 
     # initialization
@@ -3059,15 +3059,30 @@ def _dep_trans(trans):
              'pass it as an argument', DeprecationWarning)
 
 
+def _get_default_label_modes():
+    return sorted(_label_funcs.keys()) + ['auto']
+
+
+def _get_allowed_label_modes(stc):
+    if isinstance(stc, (_BaseVolSourceEstimate,
+                        _BaseVectorSourceEstimate)):
+        return ('mean', 'max', 'auto')
+    else:
+        return _get_default_label_modes()
+
+
 def _gen_extract_label_time_course(stcs, labels, src, mode='mean',
                                    allow_empty=False, trans=None,
                                    mri_resolution=True, verbose=None):
     # loop through source estimates and extract time series
+    if src is None and mode in ['mean', 'max']:
+        kind = 'surface'
+    else:
+        _validate_type(src, SourceSpaces)
+        kind = src.kind
     _dep_trans(trans)
-    _validate_type(src, SourceSpaces)
-    _check_option('mode', mode, sorted(_label_funcs.keys()) + ['auto'])
+    _check_option('mode', mode, _get_default_label_modes())
 
-    kind = src.kind
     if kind in ('surface', 'mixed'):
         if not isinstance(labels, list):
             labels = [labels]
@@ -3082,11 +3097,11 @@ def _gen_extract_label_time_course(stcs, labels, src, mode='mean',
     for si, stc in enumerate(stcs):
         _validate_type(stc, _BaseSourceEstimate, 'stcs[%d]' % (si,),
                        'source estimate')
+        _check_option(
+            'mode', mode, _get_allowed_label_modes(stc),
+            'when using a vector and/or volume source estimate')
         if isinstance(stc, (_BaseVolSourceEstimate,
                             _BaseVectorSourceEstimate)):
-            _check_option(
-                'mode', mode, ('mean', 'max', 'auto'),
-                'when using a vector and/or volume source estimate')
             mode = 'mean' if mode == 'auto' else mode
         else:
             mode = 'mean_flip' if mode == 'auto' else mode

mne/viz/_3d.py

@@ -1789,7 +1789,8 @@ def plot_source_estimates(stc, subject=None, surface='inflated', hemi='lh',
     - https://openwetware.org/wiki/Beauchamp:FreeSurfer
     """  # noqa: E501
     from .backends.renderer import _get_3d_backend, set_3d_backend
-    from ..source_estimate import _BaseSourceEstimate
+    from ..source_estimate import _BaseSourceEstimate, _check_stc_src
+    _check_stc_src(stc, src)
     _validate_type(stc, _BaseSourceEstimate, 'stc', 'source estimate')
     subjects_dir = get_subjects_dir(subjects_dir=subjects_dir,
                                     raise_error=True)
@@ -1989,7 +1990,8 @@ def _plot_stc(stc, subject, surface, hemi, colormap, time_label,
     _check_option('time_viewer', time_viewer, (True, False, 'auto'))
     _validate_type(show_traces, (str, bool, 'numeric'), 'show_traces')
     if isinstance(show_traces, str):
-        _check_option('show_traces', show_traces, ('auto', 'separate'),
+        _check_option('show_traces', show_traces,
+                      ('auto', 'separate', 'vertex', 'label'),
                       extra='when a string')
     if time_viewer == 'auto':
         time_viewer = not using_mayavi