Surface plots

examples/01_plotting/plot_3d_map_to_surface_projection.py

@@ -71,8 +71,18 @@
                             threshold=1., bg_map=big_fsaverage.sulc_right)
 
 
-plotting.show()
+##############################################################################
+# Plot multiple views of the 3D volume on a surface.
+# ---------------------------------------------------
+#
+# `plot_img_on_surf` takes a statistical map and projects it onto a surface. It
+# supports multiple choices of orientations, and can plot either both or any
+# one hemisphere. If no surf_mesh is given, plot_img_on_surf projects the
+# images onto Freesurfer's fsaverage5.
+plotting.plot_img_on_surf(stat_img, display_mode='lateral+medial',
+                          hemisphere='left+right', colorbar=True)
 
+plotting.show()
 
 ##############################################################################
 # 3D visualization in a web browser

nilearn/plotting/__init__.py

@@ -49,7 +49,8 @@ def _set_mpl_backend():
 from .html_surface import view_surf, view_img_on_surf
 from .html_stat_map import view_img
 from .html_connectome import view_connectome, view_markers
-from .surf_plotting import plot_surf, plot_surf_stat_map, plot_surf_roi
+from .surf_plotting import (plot_surf, plot_surf_stat_map, plot_surf_roi,
+                            plot_img_on_surf)
 
 __all__ = ['cm', 'plot_img', 'plot_anat', 'plot_epi',
            'plot_roi', 'plot_stat_map', 'plot_glass_brain',
@@ -58,5 +59,5 @@ def _set_mpl_backend():
            'show', 'plot_matrix', 'view_surf', 'view_img_on_surf',
            'view_img', 'view_connectome', 'view_markers',
            'find_parcellation_cut_coords', 'find_probabilistic_atlas_cut_coords',
-           'plot_surf', 'plot_surf_stat_map', 'plot_surf_roi'
+           'plot_surf', 'plot_surf_stat_map', 'plot_surf_roi', 'plot_img_on_surf'
            ]

nilearn/plotting/html_surface.py

@@ -6,6 +6,7 @@
 from matplotlib import cm as mpl_cm
 
 from .._utils.niimg_conversions import check_niimg_3d
+from .. import surface
 from .. import datasets, surface
 from nilearn.reporting import HTMLDocument
 from . import cm
@@ -91,7 +92,7 @@ def full_brain_info(volume_img, mesh='fsaverage5', threshold=None,
 
     """
     info = {}
-    mesh = _check_mesh(mesh)
+    mesh = surface.check_mesh(mesh)
     surface_maps = {
         h: surface.vol_to_surf(volume_img, mesh['pial_{}'.format(h)],
                                **vol_to_surf_kwargs)

nilearn/plotting/surf_plotting.py

@@ -12,7 +12,8 @@
 from matplotlib.cm import ScalarMappable, get_cmap
 from matplotlib.colors import Normalize, LinearSegmentedColormap
 
-from ..surface import load_surf_data, load_surf_mesh
+from ..surface import load_surf_data, load_surf_mesh, vol_to_surf, check_mesh
+from .._utils import check_niimg_3d
 from .img_plotting import _get_colorbar_and_data_ranges, _crop_colorbar
 
 
@@ -422,6 +423,264 @@ def plot_surf_stat_map(surf_mesh, stat_map, bg_map=None,
     return display
 
 
+def _check_display_mode(display_mode):
+    """Checks whether the display_mode string passed to plot_img_on_surf
+    is meaningful.
+
+    display_mode: str
+        Any combination of 'lateral', 'medial', 'dorsal', 'ventral',
+        'anterior', 'posterior', united by a '+'. Ex.: 'dorsal+lateral'
+    """
+
+    available_modes = {'lateral', 'medial',
+                       'dorsal', 'ventral',
+                       'anterior', 'posterior'}
+
+    desired_modes = display_mode.split('+')
+
+    wrong_modes = set(desired_modes).difference(available_modes)
+    if wrong_modes:
+        msg = 'display_mode given: {}, available modes: {}'
+        msg = msg.format(wrong_modes, available_modes)
+        raise ValueError(msg)
+
+    return desired_modes
+
+
+def _check_hemisphere(hemisphere):
+    """Checks whether the hemisphere in plot_img_on_surf is correct.
+
+    display_mode: str
+        Any combination of 'left', 'right'
+    """
+    desired_hemispheres = hemisphere.split('+')
+    wrong_hemisphere = set(desired_hemispheres).difference({'left', 'right'})
+    if wrong_hemisphere:
+        raise ValueError('hemisphere only accepts left and right.')
+    if len(desired_hemispheres) > 2:
+        raise ValueError('Currently only supports plotting 2 hemispheres.')
+
+    return desired_hemispheres
+
+
+def _colorbar_from_array(array, vmax,
+                         threshold, symmetric_cbar,
+                         kwargs,
+                         cmap='cold_hot'):
+    """ Generate a custom colorbar for an array.
+
+    Internal function used by plot_img_on_surf
+
+    array: Any 3D array
+
+    vmax : float, optional (default=None)
+        upper bound for plotting of stat_map values.
+
+    threshold : float, optional (default=None)
+        If None is given, the colorbar is not thresholded.
+        If a number is given, it is used to threshold the colorbar.
+        Absolute values lower than threshold are shown in gray.
+
+    symmetric_cbar : bool or 'auto', optional, default 'auto'
+         Specifies whether the colorbar should range from -vmax to vmax
+         or from vmin to vmax. Setting to 'auto' will select the latter
+         if the range of the whole image is either positive or negative.
+         Note: The colormap will always range from -vmax to vmax.
+
+    kwargs: extra arguments passed to _get_colorbar_and_data_ranges
+
+    cmap: str, optional (default='cold_hot')
+        the name of a matplotlib or nilearn colormap.
+    """
+
+    cbar_vmin, cbar_vmax, vmin, vmax = _get_colorbar_and_data_ranges(
+        array, vmax, symmetric_cbar, kwargs)
+
+    norm = Normalize(vmin=vmin, vmax=vmax)
+    cmaplist = [cmap(i) for i in range(cmap.N)]
+
+    if threshold is None:
+        threshold = 0.
+
+    # set colors to grey for absolute values < threshold
+    istart = int(norm(-threshold, clip=True) * (cmap.N - 1))
+    istop = int(norm(threshold, clip=True) * (cmap.N - 1))
+    for i in range(istart, istop):
+        cmaplist[i] = (0.5, 0.5, 0.5, 1.)
+    our_cmap = LinearSegmentedColormap.from_list('Custom cmap',
+                                                 cmaplist, cmap.N)
+    sm = plt.cm.ScalarMappable(cmap=our_cmap,
+                               norm=plt.Normalize(vmin=vmin, vmax=vmax))
+    # fake up the array of the scalar mappable.
+    sm._A = []
+
+    return sm
+
+
+def plot_img_on_surf(stat_map, surf_mesh=None, mask_img=None,
+                     hemisphere='left+right',
+                     inflate=False, display_mode='lateral+medial',
+                     output_file=None, title=None, colorbar=True,
+                     vmax=None, threshold=None, symmetric_cbar='auto',
+                     cmap='cold_hot', **kwargs):
+    """Convenience function to plot multiple views of plot_surf_stat_map
+    in a single figure. It projects stat_map into meshes and plots views of
+    left and right hemispheres. The display_mode argument defines the views
+    that are shown. This function returns the fig, axes elements from
+    matplotlib unless kwargs sets and output_file, in which case nothing
+    is returned.
+
+    stat_map : str or Niimg-like object, 3d.
+        See http://nilearn.github.io/manipulating_images/input_output.html
+
+    surf_mesh: str, dictionary, or None, optional (default=None)
+        If str, either one of the two:
+        'fsaverage5': the low-resolution fsaverage5 mesh (10242 nodes)
+        'fsaverage': the high-resolution fsaverage mesh (163842 nodes)
+        If dictionary, a dictionary with keys:
+                               ['infl_left', 'infl_right',
+                                'pial_left', 'pial_right',
+                                'sulc_left', 'sulc_right'],
+       where values are surface mesh geometries as accepted
+       by plot_surf_stat_map.
+       If None, plot_img_on_surf will use Freesurfer's 'fsaverage5'.
+
+    mask_img : Niimg-like object or None, optional (default=None)
+        The mask is passed to vol_to_surf.
+        Samples falling out of this mask or out of the image are ignored
+        during projection of the volume to the surface.
+        If ``None``, don't apply any mask.
+
+    inflate: bool, optional (default=False)
+        If True, display images in inflated brain.
+        If False, display images in pial surface.
+
+    display_mode: str, optional (default='lateral+medial')
+        A string containing all views to display, separated by '+'.
+        Available views: {'lateral', 'medial',
+                           'dorsal', 'ventral',
+                           'anterior', 'posterior'}
+        The montage will contain as many rows as views specified by
+        display mode. Order is preserved, and left and right hemispheres
+        are shown on the left and right sides of the figure.
+
+    output_file: str, optional (default=None)
+        The name of an image file to export plot to. Valid extensions
+        are .png, .pdf, .svg. If output_file is not None, the plot
+        is saved to a file, and the display is closed.
+        Plot_img_to_surf then returns None.
+
+    title: str, optional (default=None)
+        Place a title on the upper center of the figure.
+
+    colorbar : bool, optional (default=True)
+        If True, a symmetric colorbar of the statistical map is displayed.
+
+    vmax : float, optional (default=None)
+        upper bound for plotting of stat_map values.
+
+    threshold : float, optional (default=None)
+        If None is given, the image is not thresholded.
+        If a number is given, it is used to threshold the image,
+        values below the threshold (in absolute value) are plotted
+        as transparent.
+
+    symmetric_cbar : bool or 'auto', optional, default 'auto'
+         Specifies whether the colorbar should range from -vmax to vmax
+         or from vmin to vmax. Setting to 'auto' will select the latter
+         if the range of the whole image is either positive or negative.
+         Note: The colormap will always range from -vmax to vmax.
+
+    cmap: str, optional (default='cold_hot')
+        the name of a matplotlib or nilearn colormap.
+
+    kwargs: keyword arguments passed to plot_surf_stat_map
+
+    See Also
+    --------
+    nilearn.datasets.fetch_surf_fsaverage : For surface data object to be
+        used as the default background map for this plotting function.
+
+    nilearn.surface.vol_to_surf : For info on the generation of surfaces.
+
+    nilearn.plotting.plot_surf_stat_map : For info on kwargs options
+    accepted by plot_img_on_surf.
+    """
+    for arg in ('figure', 'axes'):
+        if arg in kwargs:
+            raise ValueError(('plot_img_on_surf does not'
+                              ' accept %s as an argument' % arg))
+
+    if surf_mesh is None:
+        surf_mesh = 'fsaverage5'
+
+    stat_map = check_niimg_3d(stat_map, dtype='auto')
+    modes = _check_display_mode(display_mode)
+    hemis = _check_hemisphere(hemisphere)
+    surf_mesh = check_mesh(surf_mesh)
+
+    surf = {
+        'left':
+        surf_mesh['infl_left'] if inflate else surf_mesh['pial_left'],
+        'right':
+        surf_mesh['infl_right'] if inflate else surf_mesh['pial_right']
+    }
+
+    texture = {
+        'left': vol_to_surf(stat_map, surf_mesh['pial_left'],
+                            mask_img=mask_img),
+        'right': vol_to_surf(stat_map, surf_mesh['pial_right'],
+                             mask_img=mask_img)
+    }
+
+    fig, axes = plt.subplots(nrows=len(modes), ncols=len(hemis),
+                             figsize=plt.figaspect(len(modes) / 2.),
+                             subplot_kw={'projection': '3d'})
+
+    axes = np.atleast_2d(axes)
+
+    if len(hemis) == 1:
+        axes = axes.T
+
+    for index_mode, mode in enumerate(modes):
+        for index_hemi, hemi in enumerate(hemis):
+            bg_map = surf_mesh['sulc_%s' % hemi]
+            plot_surf_stat_map(surf[hemi], texture[hemi],
+                               view=mode, hemi=hemi,
+                               bg_map=bg_map,
+                               axes=axes[index_mode, index_hemi],
+                               colorbar=False,  # Colorbar created externally.
+                               vmax=vmax,
+                               threshold=threshold,
+                               symmetric_cbar=symmetric_cbar,
+                               cmap=cmap,
+                               **kwargs)
+
+    for ax in axes.flatten():
+        # We increase this value to better position the camera of the
+        # 3D projection plot. The default value makes meshes look too small.
+        ax.dist = 6
+
+    if colorbar:
+        sm = _colorbar_from_array(stat_map.get_data(),
+                                  vmax, threshold, symmetric_cbar, kwargs,
+                                  get_cmap(cmap))
+
+        cbar_ax = fig.add_subplot(32, 1, 32)
+        fig.colorbar(sm, cax=cbar_ax, orientation='horizontal')
+
+    fig.subplots_adjust(wspace=-0.02, hspace=0.0)
+
+    if title is not None:
+        fig.suptitle(title)
+
+    if output_file is not None:
+        fig.savefig(output_file)
+        plt.close(fig)
+    else:
+        return fig, axes
+
+
 def plot_surf_roi(surf_mesh, roi_map, bg_map=None,
                   hemi='left', view='lateral', threshold=1e-14,
                   alpha='auto', vmin=None, vmax=None, cmap='gist_ncar',