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.

nilearn.plotting.plot_surf_contours

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

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

Parameters:
surf_meshstr or list of two numpy.ndarray or a InMemoryMesh, or a PolyMesh, or None, default=None

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 InMemoryMesh object with “coordinates” and “faces” attributes, or a PolyMesh object, or None. If None is passed, then roi_map must be a SurfaceImage instance and the mesh from that SurfaceImage instance will be used.

roi_mapstr or numpy.ndarray or SurfaceImage or None, default=None

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. If None is passed for surf_mesh then roi_map must be a SurfaceImage instance and its the mesh will be used for plotting.

When specified roi_map is of type numpy.ndarray, to have a correct view, hemi should have a value corresponding to roi_map data.

hemi{“left”, “right”, “both”}, default=”left”

Hemisphere to display. It is only used if roi_map is SurfaceImage and / or surf_mesh is PolyMesh. Otherwise a warning will be displayed.

Added in version 0.11.0.

levelslist of int, or None, default=None

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 str or None, or None, default=None

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,

default=None Colors to be used.

legendbool, 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 pathlib.Path 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.

axesinstance of matplotlib axes or None, default=None

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.

kwargsextra keyword arguments, optional

Extra keyword arguments passed to plot_surf.

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_stat_map

for plotting statistical maps on brain surfaces.

nilearn.surface.vol_to_surf

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