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.18. nilearn.plotting.plot_surf_roi

nilearn.plotting.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', cbar_tick_format='%i', bg_on_data=False, darkness=1, title=None, output_file=None, axes=None, figure=None, **kwargs)[source]

Plotting ROI on a surface mesh with optional background

New in version 0.3.

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.

roi_mapstr or numpy.ndarray or list of numpy.ndarray

ROI 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 .annot or .label), or a Numpy array with a value for each vertex of the surf_mesh. The value at each vertex one inside the ROI and zero inside ROI, or an integer giving the label number for atlases.

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

Hemisphere to display. Default=’left’.

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.

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

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

thresholda number or None, optional

Threshold regions that are labelled 0. If you want to use 0 as a label, set threshold to None. Default=1e-14.

cmapmatplotlib.colors.Colormap, or str, optional

The colormap to use. Either a string which is a name of a matplotlib colormap, or a matplotlib colormap object. Default=’gist_ncar’.

cbar_tick_formatstr, optional

Controls how to format the tick labels of the colorbar. Ex: use “%%.2g” to display using scientific notation. Default=’%i’ for integers.

alphafloat or ‘auto’, optional

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

bg_on_databool, optional

If True, and a bg_map is specified, the surf_data data is multiplied by the background image, so that e.g. sulcal depth is visible beneath the surf_data.


This non-uniformly changes the surf_data values according to e.g the sulcal depth.


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 that the background values are reduced by half before being applied.


titlestr, or None, optional

The title displayed on the figure. Default=None.

output_filestr, or None, optional

The name of an image file to export the 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.

axesAxes instance or None, optional

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

figureint, or matplotlib.figure.Figure, or None, optional

Matplotlib figure used or its number. If None is given, 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.


For info on the generation of surfaces.