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

nilearn.plotting.view_img_on_surf(stat_map_img, surf_mesh='fsaverage5', threshold=None, cmap=<matplotlib.colors.LinearSegmentedColormap object>, black_bg=False, vmax=None, vmin=None, symmetric_cmap=True, bg_on_data=False, darkness=0.7, colorbar=True, colorbar_height=0.5, colorbar_fontsize=25, title=None, title_fontsize=25, vol_to_surf_kwargs=None)[source]

Insert a surface plot of a statistical map into an HTML page.

Parameters:
stat_map_imgNiimg-like object, 3D

See Input and output: neuroimaging data representation.

surf_meshstr or dict, default=’fsaverage5’

If a string, it should be one of the following values:

  • “fsaverage3”: the low-resolution fsaverage3 mesh (642 nodes)

  • “fsaverage4”: the low-resolution fsaverage4 mesh (2562 nodes)

  • “fsaverage5”: the low-resolution fsaverage5 mesh (10242 nodes)

  • “fsaverage6”: the medium-resolution fsaverage6 mesh (40962 nodes)

  • “fsaverage7”: same as “fsaverage”

  • “fsaverage”: the high-resolution fsaverage mesh (163842 nodes)

    Note

    The high-resolution fsaverage will result in more computation time and memory usage

If a dictionary, it should have the same structure as those returned by nilearn.datasets.fetch_surf_fsaverage, i.e. keys should be ‘infl_left’, ‘pial_left’, ‘sulc_left’, ‘infl_right’, ‘pial_right’, and ‘sulc_right’, containing inflated and pial meshes, and sulcal depth values for left and right hemispheres.

thresholdstr, number or None, default=None

If None, no thresholding. If it is a number only values of amplitude greater than threshold will be shown. If it is a string it must finish with a percent sign, e.g. “25.3%”, and only values of amplitude above the given percentile will be shown.

cmapstr or matplotlib colormap, default=cm.cold_hot

Colormap to use.

black_bgbool, default=False

If True, image is plotted on a black background. Otherwise on a white background.

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.

darknessfloat between 0 and 1, optional

Specifying the darkness of the background image:

  • 1 indicates that the original values of the background are used

  • 0.5 indicates that the background values are reduced by half before being applied.

Default=1.

vmaxfloat or None, default=None

upper bound for the colorbar. if None, use the absolute max of the brain map.

vminfloat or None, default=None

min value for mapping colors. If symmetric_cmap is True, vmin is always equal to -vmax and cannot be chosen. If symmetric_cmap is False, vmin is equal to the min of the image, or 0 when a threshold is used.

symmetric_cmapbool, default=True

Make colormap symmetric (ranging from -vmax to vmax). You can set it to False if you are plotting only positive values.

colorbarbool, default=True

Add a colorbar or not.

colorbar_heightfloat, default=0.5

Height of the colorbar, relative to the figure height

colorbar_fontsizeint, default=25

Fontsize of the colorbar tick labels.

titlestr, default=None

Title for the plot.

title_fontsizeint, default=25

Fontsize of the title.

vol_to_surf_kwargsdict, default=None

Dictionary of keyword arguments that are passed on to nilearn.surface.vol_to_surf when extracting a surface from the input image. See the function documentation for details.This parameter is especially useful when plotting an atlas. See https://nilearn.github.io/stable/auto_examples/01_plotting/plot_3d_map_to_surface_projection.html Will default to {} if None is passed.

Returns:
SurfaceViewplot of the stat map.

It can be saved as an html page or rendered (transparently) by the Jupyter notebook. Useful methods are :

  • ‘resize’ to resize the plot displayed in a Jupyter notebook

  • ‘save_as_html’ to save the plot to a file

  • ‘open_in_browser’ to save the plot and open it in a web browser.

See also

nilearn.plotting.view_surf

plot from a surface map on a cortical mesh.

Examples using nilearn.plotting.view_img_on_surf

Making a surface plot of a 3D statistical map

Making a surface plot of a 3D statistical map