Note

This page is a reference documentation. It only explains the function signature, and not how to use it. Please refer to the user guide for the big picture.

8.10.20. nilearn.plotting.plot_surf_stat_map

nilearn.plotting.plot_surf_stat_map(surf_mesh, stat_map, bg_map=None, hemi='left', view='lateral', threshold=None, alpha='auto', vmax=None, cmap='cold_hot', colorbar=True, symmetric_cbar='auto', bg_on_data=False, darkness=1, title=None, output_file=None, axes=None, figure=None, **kwargs)[source]

Plotting a stats map on a surface mesh with optional background

New in version 0.3.

Parameters
surf_meshstr or list of two numpy.ndarray or Mesh

Surface mesh geometry, can be a file (valid formats are .gii or Freesurfer specific files such as .orig, .pial, .sphere, .white, .inflated) or a list of two Numpy arrays, the first containing the x-y-z coordinates of the mesh vertices, the second containing the indices (into coords) of the mesh faces, or a Mesh object with “coordinates” and “faces” attributes.

stat_mapstr or numpy.ndarray

Statistical map to be displayed on the surface mesh, can be a file (valid formats are .gii, .mgz, .nii, .nii.gz, or Freesurfer specific files such as .thickness, .area, .curv, .sulc, .annot, .label) or a Numpy array with a value for each vertex of the surf_mesh.

bg_mapSurface data object (to be defined), optional

Background image to be plotted on the mesh underneath the stat_map in greyscale, most likely a sulcal depth map for realistic shading.

hemi{‘left’, ‘right’}, optional

Hemispere to display. Default=’left’.

view{‘lateral’, ‘medial’, ‘dorsal’, ‘ventral’, ‘anterior’, ‘posterior’}, optional

View of the surface that is rendered. Default=’lateral’.

thresholda number or None, 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.

cmapmatplotlib colormap in str or colormap object, optional

To use for plotting of the stat_map. Either a string which is a name of a matplotlib colormap, or a matplotlib colormap object. Default=’cold_hot’.

colorbarbool, optional

If True, a symmetric colorbar of the statistical map is displayed. Default=True.

alphafloat or ‘auto’, optional

Alpha level of the mesh (not the stat_map). If ‘auto’ is chosen, alpha will default to .5 when no bg_map is passed and to 1 if a bg_map is passed. Default=’auto’.

vmaxfloat, optional

Upper bound for plotting of stat_map values.

symmetric_cbarbool or ‘auto’, optional

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. Default=’auto’.

bg_on_databool, optional

If True, and a bg_map is specified, the stat_map data is multiplied by the background image, so that e.g. sulcal depth is visible beneath the stat_map. NOTE: that this non-uniformly changes the stat_map values according to e.g the sulcal depth. Default=False.

darknessfloat between 0 and 1, optional

Specifying the darkness of the background image. 1 indicates that the original values of the background are used. .5 indicates the background values are reduced by half before being applied. Default=1.

titlestr, optional

Figure title.

output_filestr, 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.

axesinstance of matplotlib axes, None, optional

The axes instance to plot to. The projection must be ‘3d’ (e.g., figure, axes = plt.subplots(subplot_kw={‘projection’: ‘3d’}), where axes should be passed.). If None, a new axes is created.

figureinstance of matplotlib figure, None, optional

The figure instance to plot to. If None, a new figure is created.

See also

nilearn.datasets.fetch_surf_fsaverage

For surface data object to be used as background map for this plotting function.

nilearn.plotting.plot_surf

For brain surface visualization.

nilearn.surface.vol_to_surf

For info on the generation of surfaces.