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.16. 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', bg_on_data=False, darkness=1, title=None, output_file=None, axes=None, figure=None, **kwargs)

Plotting ROI 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

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

Hemisphere to display.

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’},

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

threshold: a number or None

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

cmapmatplotlib colormap str or colormap object, default ‘gist_ncar’

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

alphafloat, default is ‘auto’

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.

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. Beware that this non-uniformly changes the stat_map values according to e.g the sulcal depth.

darknessfloat, between 0 and 1, default is 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: Axes instance | None

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.

figure: Figure instance | None

The figure 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.