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.17. nilearn.plotting.plot_surf

nilearn.plotting.plot_surf(surf_mesh, surf_map=None, bg_map=None, hemi='left', view='lateral', cmap=None, colorbar=False, avg_method='mean', threshold=None, alpha='auto', bg_on_data=False, darkness=1, vmin=None, vmax=None, cbar_vmin=None, cbar_vmax=None, title=None, output_file=None, axes=None, figure=None, **kwargs)

Plotting of surfaces with optional background and data

New in version 0.3.

Parameters:

surf_mesh: str 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.

surf_map: str or numpy.ndarray, optional.

Data 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 .thickness, .curv, .sulc, .annot, .label) or a Numpy array with a value for each vertex of the surf_mesh.

bg_map: Surface data object (to be defined), optional,

Background image to be plotted on the mesh underneath the surf_data in greyscale, most likely a sulcal depth map for realistic shading.

hemi : {‘left’, ‘right’}, default is ‘left’

Hemisphere to display.

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

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

cmap: matplotlib colormap, str or colormap object, default is None

To use for plotting of the stat_map. Either a string which is a name of a matplotlib colormap, or a matplotlib colormap object. If None, matplotlib default will be chosen

colorbar : bool, optional, default is False

If True, a colorbar of surf_map is displayed.

avg_method: {‘mean’, ‘median’}, default is ‘mean’

How to average vertex values to derive the face value, mean results in smooth, median in sharp boundaries.

threshold : a number or None, default is None.

If None is given, the image is not thresholded. If a number is given, it is used to threshold the image, values below the threshold (in absolute value) are plotted as transparent.

alpha: float, alpha level of the mesh (not surf_data), default ‘auto’

If ‘auto’ is chosen, alpha will default to .5 when no bg_map is passed and to 1 if a bg_map is passed.

bg_on_data: bool, default is False

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

darkness: float, 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.

vmin, vmax: lower / upper bound to plot surf_data values

If None , the values will be set to min/max of the data

title : str, 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: instance 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, a new axes is created.

figure: instance of matplotlib figure, None, optional

The figure instance to plot to. If None, 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_roi

For plotting statistical maps on brain surfaces.

nilearn.plotting.plot_surf_stat_map

for plotting statistical maps on brain surfaces.