FIX: Add tests

Author: larsoner

mne/datasets/utils.py

@@ -239,7 +239,7 @@ def _data_path(path=None, force_update=False, update_path=True, download=True,
     path = _get_path(path, key, name)
     # To update the testing or misc dataset, push commits, then make a new
     # release on GitHub. Then update the "releases" variable:
-    releases = dict(testing='0.97', misc='0.6')
+    releases = dict(testing='0.98', misc='0.6')
     # And also update the "md5_hashes['testing']" variable below.
 
     # To update any other dataset, update the data archive itself (upload
@@ -326,7 +326,7 @@ def _data_path(path=None, force_update=False, update_path=True, download=True,
         sample='12b75d1cb7df9dfb4ad73ed82f61094f',
         somato='ea825966c0a1e9b2f84e3826c5500161',
         spm='9f43f67150e3b694b523a21eb929ea75',
-        testing='603c3f087c4dbf151c729341342095c7',
+        testing='7c1dcfacaac7759aa40bfb800c791d85',
         multimodal='26ec847ae9ab80f58f204d09e2c08367',
         fnirs_motor='c4935d19ddab35422a69f3326a01fef8',
         opm='370ad1dcfd5c47e029e692c85358a374',

mne/surface.py

@@ -796,7 +796,7 @@ def _read_patch(fname):
 
     # read surrogate surface
     rrs, tris = read_surface(
-        op.join(op.dirname(fname), op.basename(fname)[:3] + 'pial'))
+        op.join(op.dirname(fname), op.basename(fname)[:3] + 'sphere'))
     orig_tris = tris
     is_vert = patch['vertno'] > 0  # negative are edges, ignored for now
     verts = patch['vertno'][is_vert]

mne/tests/test_surface.py

@@ -13,7 +13,7 @@
                  dig_mri_distances)
 from mne.surface import (read_morph_map, _compute_nearest, _tessellate_sphere,
                          fast_cross_3d, get_head_surf, read_curvature,
-                         get_meg_helmet_surf, _normal_orth)
+                         get_meg_helmet_surf, _normal_orth, _read_patch)
 from mne.utils import (_TempDir, requires_vtk, catch_logging,
                        run_tests_if_main, object_diff, requires_freesurfer)
 from mne.io import read_info
@@ -183,6 +183,12 @@ def test_io_surface():
         assert_array_equal(pts, c_pts)
         assert_array_equal(tri, c_tri)
 
+    # reading patches (just a smoke test, let the flatmap viz tests be more
+    # complete)
+    fname_patch = op.join(
+        data_path, 'subjects', 'fsaverage', 'surf', 'rh.cortex.patch.flat')
+    _read_patch(fname_patch)
+
 
 @testing.requires_testing_data
 def test_read_curv():

mne/utils/docs.py

@@ -1058,6 +1058,16 @@
     Can be "vertical" (default) or "horizontal". When using "horizontal" mode,
     the PyVista backend must be used and hemi cannot be "split".
 """
+docdict['views'] = """
+views : str | list
+    View to use. Can be any of::
+
+        ['lateral', 'medial', 'rostral', 'caudal', 'dorsal', 'ventral',
+         'frontal', 'parietal', 'axial', 'sagittal', 'coronal']
+
+    Three letter abbreviations (e.g., ``'lat'``) are also supported.
+    Using multiple views (list) is not supported for mpl backend.
+"""
 
 # STC label time course
 docdict['eltc_labels'] = """

mne/viz/_3d.py

@@ -1630,10 +1630,14 @@ def plot_source_estimates(stc, subject=None, surface='inflated', hemi='lh',
         length. If int is provided it will be used to identify the Mayavi
         figure by it's id or create a new figure with the given id. If an
         instance of matplotlib figure, mpl backend is used for plotting.
-    views : str | list
-        View to use. See `surfer.Brain`. Supported views: ['lat', 'med', 'ros',
-        'cau', 'dor' 'ven', 'fro', 'par']. Using multiple views is not
-        supported for mpl backend.
+    %(views)s
+
+        When plotting a standard SourceEstimate (not volume, mixed, or vector)
+        and using the PyVista backend, ``views='flat'`` is also supported to
+        plot cortex as a flatmap.
+
+        .. versionchanged:: 0.21.0
+           Support for flatmaps.
     colorbar : bool
         If True, display colorbar on scene.
     %(clim)s
@@ -1684,6 +1688,17 @@ def plot_source_estimates(stc, subject=None, surface='inflated', hemi='lh',
     figure : instance of surfer.Brain | matplotlib.figure.Figure
         An instance of :class:`surfer.Brain` from PySurfer or
         matplotlib figure.
+
+    Notes
+    -----
+    Flatmaps are available by default for ``fsaverage`` but not for other
+    subjects reconstructed by FreeSurfer. We recommend using
+    :func:`mne.compute_source_morph` to morph source estimates to ``fsaverage``
+    for flatmap plotting. If you want to construct your own flatmap for a given
+    subject, these links might help:
+
+    - https://surfer.nmr.mgh.harvard.edu/fswiki/FreeSurferOccipitalFlattenedPatch
+    - https://openwetware.org/wiki/Beauchamp:FreeSurfer
     """  # noqa: E501
     from .backends.renderer import _get_3d_backend, set_3d_backend
     from ..source_estimate import _BaseSourceEstimate
@@ -1740,7 +1755,7 @@ def _plot_stc(stc, subject, surface, hemi, colormap, time_label,
         _require_version('surfer', 'stc.plot', '0.9')
     else:  # PyVista
         from ._brain import _Brain as Brain
-
+    views = _check_views(surface, views, hemi, stc, backend)
     _check_option('hemi', hemi, ['lh', 'rh', 'split', 'both'])
     _check_option('view_layout', view_layout, ('vertical', 'horizontal'))
     time_label, times = _handle_time(time_label, time_unit, stc.times)
@@ -2347,6 +2362,29 @@ def _check_pysurfer_antialias(Brain):
     return kwargs
 
 
+def _check_views(surf, views, hemi, stc=None, backend=None):
+    from ..source_estimate import SourceEstimate
+    _validate_type(views, (list, tuple, str), 'views')
+    views = [views] if isinstance(views, str) else list(views)
+    if surf == 'flat':
+        _check_option('views', views, (['auto'], ['flat']))
+        views = ['flat']
+    elif len(views) == 1 and views[0] == 'auto':
+        views = ['lat']
+    if views == ['flat']:
+        if stc is not None:
+            _validate_type(stc, SourceEstimate, 'stc',
+                           'SourceEstimate when a flatmap is used')
+        if backend is not None:
+            if backend != 'pyvista':
+                raise RuntimeError('The PyVista 3D backend must be used to '
+                                   'plot a flatmap')
+    if (views == ['flat']) ^ (surf == 'flat'):  # exactly only one of the two
+        raise ValueError('surface="flat" must be used with views="flat", got '
+                         f'surface={repr(surf)} and views={repr(views)}')
+    return views
+
+
 @verbose
 def plot_vector_source_estimates(stc, subject=None, hemi='lh', colormap='hot',
                                  time_label='auto', smoothing_steps=10,
@@ -2407,8 +2445,7 @@ def plot_vector_source_estimates(stc, subject=None, hemi='lh', colormap='hot',
         split view is requested, this must be a list of the appropriate
         length. If int is provided it will be used to identify the Mayavi
         figure by it's id or create a new figure with the given id.
-    views : str | list
-        View to use. See `surfer.Brain`.
+    %(views)s
     colorbar : bool
         If True, display colorbar on scene.
     %(clim_onesided)s

mne/viz/_brain/_brain.py

@@ -17,7 +17,7 @@
 from .surface import Surface
 from .view import views_dicts
 
-from .._3d import _process_clim, _handle_time
+from .._3d import _process_clim, _handle_time, _check_views
 
 from ...defaults import _handle_default
 from ...surface import mesh_edges
@@ -198,7 +198,7 @@ def __init__(self, subject_id, hemi, surf, title=None,
 
         if isinstance(views, str):
             views = [views]
-        views = _check_views_hemi_flat(surf, views, hemi)
+        views = _check_views(surf, views, hemi)
         col_dict = dict(lh=1, rh=1, both=1, split=2)
         shape = (len(views), col_dict[hemi])
         if self._view_layout == 'horizontal':
@@ -1737,14 +1737,3 @@ def _update_limits(fmin, fmid, fmax, center, array):
                            % (fmid, fmax))
 
     return fmin, fmid, fmax
-
-
-def _check_views_hemi_flat(surf, views, hemi):
-    if surf == 'flat':
-        if len(views) != 1 or views[0] != 'auto':
-            raise ValueError(
-                f'views must be "auto" for flat maps, got {views}')
-        views = ['flat']
-    elif len(views) == 1 and views[0] == 'auto':
-        views = ['lat']
-    return views

mne/viz/_brain/surface.py

@@ -9,7 +9,7 @@
 from os import path as path
 
 import numpy as np
-from ...utils import _check_option, get_subjects_dir
+from ...utils import _check_option, get_subjects_dir, _check_fname
 from ...surface import (complete_surface_info, read_surface, read_curvature,
                         _read_patch)
 
@@ -110,9 +110,11 @@ def load_geometry(self):
         None
         """
         if self.surf == 'flat':  # special case
-            coords, faces, orig_faces = _read_patch(
-                path.join(self.data_path, 'surf',
-                          '%s.%s' % (self.hemi, 'cortex.patch.flat')))
+            fname = path.join(self.data_path, 'surf',
+                              '%s.%s' % (self.hemi, 'cortex.patch.flat'))
+            _check_fname(fname, overwrite='read', must_exist=True,
+                         name='flatmap surface file')
+            coords, faces, orig_faces = _read_patch(fname)
         else:
             coords, faces = read_surface(
                 path.join(self.data_path, 'surf',

mne/viz/tests/test_3d.py

@@ -705,9 +705,10 @@ def test_plot_source_estimates(renderer_interactive, all_src_types_inv_evoked,
     with pytest.warns(None):  # PCA mag
         stc = apply_inverse(evoked, inv, pick_ori=pick_ori)
     stc.data[1] *= -1  # make it signed
-    meth = 'plot_3d' if isinstance(stc, _BaseVolSourceEstimate) else 'plot'
-    meth = getattr(stc, meth)
-    kwargs = dict(subject='sample', subjects_dir=subjects_dir,
+    meth_key = 'plot_3d' if isinstance(stc, _BaseVolSourceEstimate) else 'plot'
+    stc.subject = 'sample'
+    meth = getattr(stc, meth_key)
+    kwargs = dict(subjects_dir=subjects_dir,
                   time_viewer=False, show_traces=False,  # for speed
                   smoothing_steps=1, verbose='error', src=inv['src'],
                   volume_options=dict(resolution=None),  # for speed
@@ -740,6 +741,31 @@ def test_plot_source_estimates(renderer_interactive, all_src_types_inv_evoked,
         with pytest.raises(ValueError, match='view_layout must be'):
             meth(view_layout='horizontal', **kwargs)
 
+    # flatmaps (mostly a lot of error checking)
+    these_kwargs = kwargs.copy()
+    these_kwargs.update(surface='flat', views='auto')
+    if kind == 'surface' and pick_ori != 'vector' and is_pyvista:
+        with pytest.raises(FileNotFoundError, match='flatmap'):
+            meth(**these_kwargs)  # sample does not have them
+    fs_stc = stc.copy()
+    fs_stc.subject = 'fsaverage'  # this is wrong, but don't have to care
+    flat_meth = getattr(fs_stc, meth_key)
+    these_kwargs.pop('src')
+    if pick_ori == 'vector':
+        pass  # can't even pass "surface" variable
+    elif kind != 'surface':
+        with pytest.raises(TypeError, match='SourceEstimate when a flatmap'):
+            flat_meth(**these_kwargs)
+    elif not is_pyvista:
+        with pytest.raises(RuntimeError, match='PyVista 3D backend.*flatmap'):
+            flat_meth(**these_kwargs)
+    else:
+        brain = flat_meth(**these_kwargs)
+        brain.close()
+        these_kwargs.update(surface='inflated', views='flat')
+        with pytest.raises(ValueError, match='surface="flat".*views="flat"'):
+            flat_meth(**these_kwargs)
+
     # just test one for speed
     if kind != 'mixed':
         return

tutorials/source-modeling/plot_visualize_stc.py

@@ -53,7 +53,7 @@
                  clim=dict(kind='value', lims=[3, 6, 9]))
 
 ###############################################################################
-# You can also morph it to fsaverage and visualize it using a flat map:
+# You can also morph it to fsaverage and visualize it using a flatmap:
 
 # sphinx_gallery_thumbnail_number = 2