Giving credit

Table Of Contents

Previous topic

3.5. Clustering to parcellate the brain in regions

Next topic

5. Manipulation brain volumes with nilearn

4. Plotting brain images

In this section, we detail the general tools to visualize neuroimaging volumes with nilearn.

Nilearn comes with plotting function to display brain maps coming from Nifti-like images, in the nilearn.plotting module.

Code examples

Nilearn has a whole section of the example gallery on plotting.

A small tour of the plotting functions can be found in the example Plotting tools in nilearn.

Finally, note that, as always in the nilearn documentation, clicking on a figure will take you to the code that generates it.

4.1. Different plotting functions

Nilearn has a set of plotting functions to plot brain volumes that are fined tuned to specific applications. Amongst other things, they use different heuristics to find cutting coordinates.

plot_anat plot_anat
Plotting an anatomical image
plot_epi plot_epi
Plotting an EPI, or T2* image
plot_glass_brain plot_glass_brain
Glass brain visualization. By default plots maximum intensity projection of the absolute values. To plot positive and negative values set plot_abs parameter to False.
plot_stat_map plot_stat_map
Plotting a statistical map, like a T-map, a Z-map, or an ICA, with an optional background
plot_roi plot_roi
Plotting ROIs, or a mask, with an optional background
plot_connectome plot_connectome
Plotting a connectome
plot_prob_atlas plot_prob_atlas
Plotting 4D probabilistic atlas maps
plot_img plot_img
General-purpose function, with no specific presets


Opening too many figures without closing

Each call to a plotting function creates a new figure by default. When used in non-interactive settings, such as a script or a program, these are not displayed, but still accumulate and eventually lead to slowing the execution and running out of memory.

To avoid this, you must close the plot as follow:

>>> from nilearn import plotting
>>> display = plotting.plot_stat_map(img)     
>>> display.close()     

4.2. Different display modes

plot_ortho display_mode=’ortho’, cut_coords=[36, -27, 60]
Ortho slicer: 3 cuts along the x, y, z directions
plot_z_many display_mode=’z’, cut_coords=5
Cutting in the z direction, specifying the number of cuts
plot_x display_mode=’x’, cut_coords=[-36, 36]
Cutting in the x direction, specifying the exact cuts
plot_y_small display_mode=’y’, cut_coords=1
Cutting in the y direction, with only 1 cut, that is automatically positionned
plot_z_small display_mode=’z’, cut_coords=1, colorbar=False
Cutting in the z direction, with only 1 cut, that is automatically positionned
plot_xz display_mode=’xz’, cut_coords=[36, 60]
Cutting in the x and z direction, with cuts manually positionned
plot_yx display_mode=’yx’, cut_coords=[-27, 36]
Cutting in the y and x direction, with cuts manually positionned
plot_yz display_mode=’yz’, cut_coords=[-27, 60]
Cutting in the y and z direction, with cuts manually positionned
plot_lzr Glass brain display_mode=’lzr’
Glass brain and Connectome provide additional display modes due to the possibility of doing hemispheric projections. Check out: ‘l’, ‘r’, ‘lr’, ‘lzr’, ‘lyr’, ‘lzry’, ‘lyrz’.
plot_lyrz Glass brain display_mode=’lyrz’
Glass brain and Connectome provide additional display modes due to the possibility of doing hemispheric projections. Check out: ‘l’, ‘r’, ‘lr’, ‘lzr’, ‘lyr’, ‘lzry’, ‘lyrz’.

4.3. Adding overlays, edges, contours, contour fillings and markers

To add overlays, contours, or edges, use the return value of the plotting functions. Indeed, these return a display object, such as the nilearn.plotting.displays.OrthoSlicer. This object represents the plot, and has methods to add overlays, contours or edge maps:

display = plotting.plot_epi(...)
plot_edges display.add_edges(img)
Add a plot of the edges of img, where edges are extracted using a Canny edge-detection routine. This is typically useful to check registration. Note that img should have some visible sharp edges. Typically an EPI img does not, but a T1 does.
plot_contours display.add_contours(img, levels=[.5], colors=’r’)
Add a plot of the contours of img, where contours are computed for constant values, specified in ‘levels’. This is typically useful to outline a mask, or ROI on top of another map.
Example: Plot Haxby masks
plot_fill display.add_contours(img, filled=True, alpha=0.7, levels=[0.5], colors=’b’)
Add a plot of img with contours filled with colors
plot_overlay display.add_overlay(img,, threshold=3)
Add a new overlay on the existing figure
Example: Visualizing a probablistic atlas: the default mode in the MSDL atlas
plot_markers display.add_markers(coords, marker_color=’y’, marker_size=100)
Add seed based MNI coordinates as spheres on top of statistical image or EPI image. This is useful for seed based regions specific interpretation of brain images.
Example: Producing single subject maps of seed-to-voxel correlation

4.4. Displaying or saving to an image file

To display the figure when running a script, you need to call (this is just an alias to

>>> from nilearn import plotting

The simplest way to output an image file from the plotting functions is to specify the output_file argument:

>>> from nilearn import plotting
>>> plotting.plot_stat_map(img, output_file='pretty_brain.png')     

In this case, the display is closed automatically and the plotting function returns None.

The display object returned by the plotting function has a savefig method that can be used to save the plot to an image file:

>>> from nilearn import plotting
>>> display = plotting.plot_stat_map(img)     
>>> display.savefig('pretty_brain.png')     
# Don't forget to close the display
>>> display.close()