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.


nilearn.plotting.plot_surf_contours(surf_mesh, roi_map, axes=None, figure=None, levels=None, labels=None, colors=None, legend=False, cmap='tab20', title=None, output_file=None, **kwargs)[source]

Plot contours of ROIs on a surface, optionally over a statistical map.

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, 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. The value at each vertex one inside the ROI and zero inside ROI, or an integer giving the label number for atlases.

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, uses axes from figure if available, else creates new axes.

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

Matplotlib figure used or its number. If None is given, a new figure is created.

levelslist of integers, or None, optional

A list of indices of the regions that are to be outlined. Every index needs to correspond to one index in roi_map. If None, all regions in roi_map are used.

labelslist of strings or None, or None, optional

A list of labels for the individual regions of interest. Provide None as list entry to skip showing the label of that region. If None no labels are used.

colorslist of matplotlib color names or RGBA values, or None, optional

Colors to be used.

legendboolean, optional, default=False

Whether to plot a legend of region’s labels.

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=’tab20’.

titlestr, or None, default=None

The title displayed on the figure.

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.

kwargs: extra keyword arguments, optional

Extra keyword arguments passed to plot_surf.

See also


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


for plotting statistical maps on brain surfaces.


For info on the generation of surfaces.

Examples using nilearn.plotting.plot_surf_contours

Making a surface plot of a 3D statistical map

Making a surface plot of a 3D statistical map