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

nilearn.plotting.plot_surf(surf_mesh=None, surf_map=None, bg_map=None, hemi='left', view=None, engine='matplotlib', cmap=None, symmetric_cmap=None, colorbar=True, avg_method=None, threshold=None, alpha=None, bg_on_data=False, vmin=None, vmax=None, cbar_vmin=None, cbar_vmax=None, cbar_tick_format='auto', title=None, title_font_size=None, output_file=None, axes=None, figure=None)[source]

Plot surfaces with optional background and data.

Added in Nilearn 0.3.

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 surf_map must be a SurfaceImage instance and the mesh from that SurfaceImage instance will be used.

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

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, .area, .curv, .sulc, .annot, .label) or a Numpy array with a value for each vertex of the surf_mesh, or a SurfaceImage instance. If None is passed for surf_mesh, then surf_map must be a SurfaceImage instance and its mesh will be used for plotting.

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

bg_mapstr or pathlib.Path or numpy.ndarray or SurfaceImage or None, default=None

Background image to be plotted on the mesh underneath the surf_data in grayscale, most likely a sulcal depth map for realistic shading. If the map contains values outside [0, 1], it will be rescaled such that all values are in [0, 1]. Otherwise, it will not be modified. If a str or pathlib.Path is passed, it should be loadable to a numpy.ndarray by load_surf_data. If a numpy.ndarray is passed, if should have a shape (n_vertices, ), with n_vertices matching that of the underlying mesh used for plotting.

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

Hemisphere to display.

viewstr, or a pair of float or int, default=”lateral” if hemi is “left” or “right”, if hemi is “both” “dorsal”

If a string, and hemi is “left” or “right” must be in {“lateral”, “medial”, “dorsal”, “ventral”, “anterior”, “posterior”}. If hemi is “both”, must be in {“left”, “right”, “dorsal”, “ventral”, “anterior”, “posterior”}. If a sequence, must be a pair (elev, azim) of float or int angles in degrees that will manually set a custom view. E.g., view=[270.0, 90] or view=(0, -180.0). View of the surface that is rendered.

engine{‘matplotlib’, ‘plotly’}, default=’matplotlib’

Added in Nilearn 0.9.0.

Selects which plotting engine will be used by plot_surf. Currently, only matplotlib and plotly are supported.

Note

To use the plotly engine, you need to have plotly installed.

Note

To be able to save figures to disk with the plotly engine, you need to have kaleido installed.

Warning

The plotly engine is new and experimental. Please report bugs that you may encounter.

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. If None, matplotlib default will be chosen.

symmetric_cmapbool, default=None

Whether to use a symmetric colormap or not.

Note

This option is currently only implemented for the plotly engine.

When using plotly as engine, symmetric_cmap will default to False if None is passed.

Added in Nilearn 0.9.0.

Changed in Nilearn 0.12.0: Default value changed to None.

colorbarbool, optional

If True, display a colorbar on the right of the plots. Default=True.

avg_method{“mean”, “median”, “min”, “max”, custom function, None}, default=None

How to average vertex values to derive the face value:

  • "mean": results in smooth boundaries

  • "median": results in sharp boundaries

  • "min" or "max": for sparse matrices

  • custom function: You can also pass a custom function which will be executed though numpy.apply_along_axis. Here is an example of a custom function:

    def custom_function(vertices):
    return vertices[0] * vertices[1] * vertices[2]

Note

This option is currently only implemented for the matplotlib engine.

When using matplotlib as engine, avg_method will default to "mean" if None is passed.

thresholdint or float, None, or ‘auto’, optional

If None is given, the image is not thresholded. If number is given, it must be non-negative. The specified value is used to threshold the image: values below the threshold (in absolute value) are plotted as transparent. If “auto” is given, the threshold is determined based on the score obtained using percentile value “80%” on the absolute value of the image data. Default=None

alphafloat or None, default=None

Alpha level of the mesh (not surf_data).

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

Note

This option is currently only implemented for the matplotlib engine.

When using matplotlib as engine, alpha will default to “auto” if None is passed.

bg_on_databool, default=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 jointly visible with surf_data. Otherwise, the background image will only be visible where there is no surface data (either because surf_data contains nans or because is was thresholded).

Note

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

vminfloat or obj:int or None, optional

Lower bound of the colormap. The values below vmin are masked. If None, the min of the image is used. Passed to matplotlib.pyplot.imshow.

vmaxfloat or obj:int or None, optional

Upper bound of the colormap. The values above vmax are masked. If None, the max of the image is used. Passed to matplotlib.pyplot.imshow.

cbar_vminfloat or None, default=None

Lower bound for the colorbar. If None, the value will be set from the data.

Note

This option is currently only implemented for the matplotlib engine.

cbar_vmaxfloat or None, default=None

Upper bound for the colorbar. If None, the value will be set from the data.

Note

This option is currently only implemented for the matplotlib engine.

cbar_tick_formatstr, optional

Controls how to format the tick labels of the colorbar. Ex: use “%%.2g” to display using scientific notation. Default=”auto” which will select:

  • ‘%.2g’ (scientific notation) with matplotlib engine.

  • ‘.1f’ (rounded floats) with plotly engine.

Added in Nilearn 0.7.1.

titlestr, or None, default=None

The title displayed on the figure.

title_font_sizeint, default=None

Size of the title font

Note

This option is currently only implemented for the plotly engine.

When using plotly as engine, title_font_size will default to 18 if None is passed.

Added in Nilearn 0.9.0.

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, a new axes is created.

Note

This option is currently only implemented for the matplotlib engine.

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

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

Note

This option is currently only implemented for the matplotlib engine.

Returns:
figFigure or
PlotlySurfaceFigure

The surface figure. If engine='matplotlib' then a Figure is returned. If engine='plotly', then a PlotlySurfaceFigure is returned

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.

nilearn.surface.vol_to_surf

For info on the generation of surfaces.

Examples using nilearn.plotting.plot_surf

A short demo of the surface images & maskers

A short demo of the surface images & maskers