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)

Plotting a stats map on a surface mesh with optional background

New in version 0.3.

Parameters:

surf_mesh : str 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_map : str 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_map : Surface 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.

threshold : a 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.

cmap : matplotlib 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.

colorbar : bool, optional, default is False

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

alpha : float, 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.

vmax : upper bound for plotting of stat_map values.

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.

bg_on_data : bool, 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.

title : str, 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

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.