def test_check_mesh():
mesh = surface._check_mesh('fsaverage5')
assert mesh is surface._check_mesh(mesh)
with pytest.raises(ValueError):
surface._check_mesh('fsaverage2')
mesh.pop('pial_left')
with pytest.raises(ValueError):
surface._check_mesh(mesh)
with pytest.raises(TypeError):
surface._check_mesh(surface.load_surf_mesh(mesh['pial_right']))
def plot_img_on_surf(stat_map,
surf_mesh='fsaverage5',
mask_img=None,
hemispheres=['left', 'right'],
inflate=False,
views=['lateral', 'medial'],
output_file=None,
title=None,
colorbar=True,
vmax=None,
threshold=None,
cmap='cold_hot',
aspect_ratio=1.4,
**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 *views* 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.
Parameters
----------
stat_map : str or 3D Niimg-like object
See http://nilearn.github.io/manipulating_images/input_output.html
surf_mesh : str, dict, or None, optional
If str, either one of the two:
'fsaverage5': the low-resolution fsaverage5 mesh (10242 nodes)
'fsaverage': the high-resolution fsaverage mesh (163842 nodes)
If dict, 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.
Default='fsaverage5'.
mask_img : Niimg-like object or None, optional
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
If True, display images in inflated brain.
If False, display images in pial surface.
Default=False.
views : list of strings, optional
A list containing all views to display.
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.
Default=['lateral', 'medial'].
hemispheres : list of strings, optional
Hemispheres to display. Default=['left', 'right'].
output_file : str, optional
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. Return
value is None.
title : str, optional
Place a title on the upper center of the figure.
colorbar : bool, optional
If *True*, a symmetric colorbar of the statistical map is displayed.
Default=True.
vmax : float, optional
Upper bound for plotting of stat_map values.
threshold : float, optional
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.
cmap : str, optional
The name of a matplotlib or nilearn colormap. Default='cold_hot'.
kwargs : dict, optional
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))
stat_map = check_niimg_3d(stat_map, dtype='auto')
modes = _check_views(views)
hemis = _check_hemispheres(hemispheres)
surf_mesh = _check_mesh(surf_mesh)
mesh_prefix = "infl" if inflate else "pial"
surf = {
'left': surf_mesh[mesh_prefix + '_left'],
'right': surf_mesh[mesh_prefix + '_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)
}
figsize = plt.figaspect(len(modes) / (aspect_ratio * len(hemispheres)))
fig, axes = plt.subplots(nrows=len(modes),
ncols=len(hemis),
figsize=figsize,
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,
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(image.get_data(stat_map),
vmax,
threshold,
kwargs,
cmap=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_img_on_surf(stat_map, surf_mesh='fsaverage5', mask_img=None,
hemispheres=['left', 'right'],
inflate=False,
views=['lateral', 'medial'],
output_file=None, title=None, colorbar=True,
vmax=None, threshold=None,
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 *views* 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.
Parameters
----------
stat_map : str or 3D Niimg-like object
See http://nilearn.github.io/manipulating_images/input_output.html
surf_mesh : str, dict, or None, optional
If str, either one of the two:
'fsaverage5': the low-resolution fsaverage5 mesh (10242 nodes)
'fsaverage': the high-resolution fsaverage mesh (163842 nodes)
If dict, 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.
Default='fsaverage5'.
mask_img : Niimg-like object or None, optional
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
If True, display images in inflated brain.
If False, display images in pial surface.
Default=False.
views : list of strings, optional
A list containing all views to display.
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.
Default=['lateral', 'medial'].
%(hemispheres)s
%(output_file)s
%(title)s
%(colorbar)s
.. note::
This function uses a symmetric colorbar for the statistical map.
Default=True.
%(vmax)s
%(threshold)s
%(cmap)s
Default='cold_hot'.
kwargs : dict, optional
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))
stat_map = check_niimg_3d(stat_map, dtype='auto')
modes = _check_views(views)
hemis = _check_hemispheres(hemispheres)
surf_mesh = _check_mesh(surf_mesh)
mesh_prefix = "infl" if inflate else "pial"
surf = {
'left': surf_mesh[mesh_prefix + '_left'],
'right': surf_mesh[mesh_prefix + '_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)
}
cbar_h = .25
title_h = .25 * (title is not None)
w, h = plt.figaspect((len(modes) + cbar_h + title_h) / len(hemispheres))
fig = plt.figure(figsize=(w, h), constrained_layout=False)
height_ratios = [title_h] + [1.] * len(modes) + [cbar_h]
grid = gridspec.GridSpec(
len(modes) + 2, len(hemis),
left=0., right=1., bottom=0., top=1.,
height_ratios=height_ratios, hspace=0.0, wspace=0.0)
axes = []
for i, (mode, hemi) in enumerate(itertools.product(modes, hemis)):
bg_map = surf_mesh['sulc_%s' % hemi]
ax = fig.add_subplot(grid[i + len(hemis)], projection="3d")
axes.append(ax)
plot_surf_stat_map(surf[hemi], texture[hemi],
view=mode, hemi=hemi,
bg_map=bg_map,
axes=ax,
colorbar=False, # Colorbar created externally.
vmax=vmax,
threshold=threshold,
cmap=cmap,
**kwargs)
# ax.set_facecolor("#e0e0e0")
# We increase this value to better position the camera of the
# 3D projection plot. The default value makes meshes look too small.
ax.dist = 7
if colorbar:
sm = _colorbar_from_array(image.get_data(stat_map),
vmax, threshold, kwargs,
cmap=get_cmap(cmap))
cbar_grid = gridspec.GridSpecFromSubplotSpec(3, 3, grid[-1, :])
cbar_ax = fig.add_subplot(cbar_grid[1])
axes.append(cbar_ax)
fig.colorbar(sm, cax=cbar_ax, orientation='horizontal')
if title is not None:
fig.suptitle(title, y=1. - title_h / sum(height_ratios), va="bottom")
if output_file is not None:
fig.savefig(output_file, bbox_inches="tight")
plt.close(fig)
else:
return fig, axes
