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_stat_map¶
- nilearn.plotting.plot_surf_stat_map(surf_mesh=None, stat_map=None, bg_map=None, hemi='left', view='lateral', engine='matplotlib', threshold=None, alpha=None, vmin=None, vmax=None, cmap='cold_hot', colorbar=True, symmetric_cbar='auto', cbar_tick_format='auto', bg_on_data=False, darkness=0.7, title=None, title_font_size=18, output_file=None, axes=None, figure=None, avg_method=None, **kwargs)[source]¶
Plot a stats map on a surface mesh with optional background.
Added in version 0.3.
- Parameters:
- surf_mesh
str
orlist
of twonumpy.ndarray
or aInMemoryMesh
, or aPolyMesh
, or 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 aPolyMesh
object, or None. If None is passed, thensurf_map
must be aSurfaceImage
instance and the mesh from thatSurfaceImage
instance will be used.- stat_map
str
ornumpy.ndarray
Statistical map to be displayed on the surface mesh, can be a file (valid formats are .gii, .mgz, 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. If None is passed for
surf_mesh
thenstat_map
must be aSurfaceImage
instance and its the mesh will be used for plotting.- bg_map
str
ornumpy.ndarray
orSurfaceImage
or None, default=None Background image to be plotted on the mesh underneath the stat_map 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.
- hemi{“left”, “right”}, default=”left”
Hemisphere to display.
- view
str
, or a pair offloat
orint
, default=”lateral” If a string, must be in {“lateral”, “medial”, “dorsal”, “ventral”, “anterior”, “posterior”}. If a sequence, must be a pair (elev, azim) of
float
orint
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 version 0.9.0.
Selects which plotting engine will be used by
plot_surf_stat_map
. Currently, onlymatplotlib
andplotly
are supported.Note
To use the
plotly
engine you need to haveplotly
installed.Note
To be able to save figures to disk with the
plotly
engine you need to havekaleido
installed.Warning
The
plotly
engine is new and experimental. Please report bugs that you may encounter.- thresholda number or None, default=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.
- cmap
matplotlib.colors.Colormap
, orstr
, optional The colormap to use. Either a string which is a name of a matplotlib colormap, or a matplotlib colormap object.
- cbar_tick_format
str
, 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 version 0.7.1.
- colorbar
bool
, 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.
- alpha
float
or ‘auto’ or None, default=None Alpha level of the mesh (not the stat_map). Will default to
"auto"
ifNone
is passed. If ‘auto’ is chosen, alpha will default to .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.- vmin
float
, optional Lower bound of the colormap. If None, the min of the image is used. Passed to
matplotlib.pyplot.imshow
.- vmax
float
, optional Upper bound of the colormap. If None, the max of the image is used. Passed to
matplotlib.pyplot.imshow
.- symmetric_cbar
bool
, 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.
- bg_on_data
bool
, 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.
- darkness
float
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.
Note
This option is currently only implemented for the
matplotlib
engine.- title
str
, or None, default=None The title displayed on the figure.
- title_font_size
int
, default=18 Size of the title font (only implemented for the plotly engine).
Added in version 0.9.0.
- output_file
str
, 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.- figure
int
, ormatplotlib.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.- 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 matricescustom 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"
ifNone
is passed.Added in version 0.10.3dev.
- kwargs
dict
, optional Keyword arguments passed to
nilearn.plotting.plot_surf
.
- surf_mesh
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
For brain surface visualization.
nilearn.surface.vol_to_surf
For info on the generation of surfaces.
Examples using nilearn.plotting.plot_surf_stat_map
¶
Technical point: Illustration of the volume to surface sampling schemes
Seed-based connectivity on the surface
Making a surface plot of a 3D statistical map
Cortical surface-based searchlight decoding
Example of surface-based first-level analysis
Surface-based dataset first and second level analysis of a dataset