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

Parameters
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.

Note

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

Default=False.

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.

Default=1.

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

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.

nilearn.surface.vol_to_surf

For info on the generation of surfaces.