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_img_on_surf

nilearn.plotting.plot_img_on_surf(stat_map, surf_mesh='fsaverage5', mask_img=None, hemispheres=None, bg_on_data=False, inflate=False, views=None, output_file=None, title=None, colorbar=True, vmin=None, vmax=None, threshold=None, symmetric_cbar='auto', cmap='cold_hot', cbar_tick_format='%i', **kwargs)

Plot multiple views of plot_surf_stat_map in a single figure.

It projects stat_map into meshes and plots views of left and right hemispheres. The views argument defines the views that are shown. This function returns the fig, axes elements from matplotlib unless kwargs sets and output_file, in which case nothing is returned.

Parameters:

stat_mapstr or pathlib.Path or 3D Niimg-like object

See Input and output: neuroimaging data representation.

surf_meshstr, dict, or None, default=’fsaverage5’

If str, either one of the two: ‘fsaverage5’: the low-resolution fsaverage5 mesh (10242 nodes) ‘fsaverage’: the high-resolution fsaverage mesh (163842 nodes) If dict, a dictionary with keys: [‘infl_left’, ‘infl_right’, ‘pial_left’, ‘pial_right’, ‘sulc_left’, ‘sulc_right’], where values are surface mesh geometries as accepted by plot_surf_stat_map.

mask_imgNiimg-like object or None, default=None

The mask is passed to vol_to_surf. Samples falling out of this mask or out of the image are ignored during projection of the volume to the surface. If None, don’t apply any mask.

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.

hemisphereslist of str, default=None

Hemispheres to display. Will default to ['left', 'right'] if None is passed.

inflatebool, default=False

If True, display images in inflated brain. If False, display images in pial surface.

viewslist of str, default=None

A list containing all views to display. The montage will contain as many rows as views specified by display mode. Order is preserved, and left and right hemispheres are shown on the left and right sides of the figure. Will default to ['lateral', 'medial'] if None is passed.

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.

titlestr, or None, default=None

The title displayed on the figure.

colorbarbool, optional

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

Note

This function uses a symmetric colorbar for the statistical map.

Default=True.

vminfloat, optional

Lower bound of the colormap. If None, the min of the image is used. Passed to matplotlib.pyplot.imshow.

vmaxfloat, optional

Upper bound of the colormap. If None, the max of the image is used. Passed to matplotlib.pyplot.imshow.

thresholda number, None, or ‘auto’, optional

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. If “auto” is given, the threshold is determined magically by analysis of the image.

symmetric_cbarbool, or “auto”, default=”auto”

Specifies whether the colorbar and colormap should range from -vmax to vmax (or from vmin to -vmin if -vmin is greater than vmax) or from vmin to vmax. Setting to “auto” (the default) will select the former if either vmin or vmax is None and the image has both positive and negative values.

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

cbar_tick_formatstr, optional

Controls how to format the tick labels of the colorbar. Ex: use “%%.2g” to display using scientific notation.

kwargsdict, optional

keyword arguments passed to plot_surf_stat_map.

See also

nilearn.datasets.fetch_surf_fsaverage

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

nilearn.surface.vol_to_surf

For info on the generation of surfaces.

nilearn.plotting.plot_surf_stat_map

For info on kwargs options accepted by plot_img_on_surf.

Examples using nilearn.plotting.plot_img_on_surf

Making a surface plot of a 3D statistical map

Making a surface plot of a 3D statistical map