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.

7.10.17. 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)

Plotting a stats map on a surface mesh with optional background

New in version 0.3.

surf_meshstr or list of two numpy.ndarray

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

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, .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’}, default is ‘left’

Hemispere to display.

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

default is ‘lateral’ View of the surface that is rendered.

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

cmapmatplotlib colormap in str or colormap object, default ‘cold_hot’

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

colorbarbool, optional, default is False

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

alphafloat, alpha level of the mesh (not the stat_map), default ‘auto’

If ‘auto’ is chosen, alpha will default to .5 when no bg_map is passed and to 1 if a bg_map is passed.

vmaxupper bound for plotting of stat_map values.
symmetric_cbarbool 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.

bg_on_databool, default is False

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.

darkness: float, between 0 and 1, default 1

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.

titlestr, optional

Figure title.

output_file: str, or None, 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.

axes: instance 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.

figure: instance of matplotlib figure, None, optional

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

See also


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


For brain surface visualization.