Note

This page is a reference documentation. It only explains the class signature, and not how to use it. Please refer to the user guide for the big picture.

nilearn.plotting.displays.MosaicSlicer¶

class nilearn.plotting.displays.MosaicSlicer(cut_coords, axes=None, black_bg=False, brain_color=(0.5, 0.5, 0.5), **kwargs)[source]¶

A class to create 3 Axes for plotting cuts of 3D maps, in multiple rows and columns.

This visualization mode can be activated from Nilearn plotting functions, like plot_img, by setting display_mode='mosaic'.

from nilearn.datasets import load_mni152_template
from nilearn.plotting import plot_img

img = load_mni152_template()
# display is an instance of the MosaicSlicer class
display = plot_img(img, display_mode="mosaic")

Parameters:

cut_coordsint, 3-sequence of float or int, dict <str: 1D ndarray> or None: Either a number to indicate number of cuts in each direction, or a sequence of length 3 indicating the number of cuts in each direction (x, y, z), or a dictionary where keys are the directions (‘x’, ‘y’, ‘z’) and the values are sequences holding the cut coordinates.
axesmatplotlib.axes.Axes, or 4 tuple of float: (xmin, ymin, width, height), default=None: The axes, or the coordinates, in matplotlib figure space, of the axes used to display the plot. If None, the complete figure is used.
black_bgbool, or “auto”, optional: If True, the background of the image is set to be black. If you wish to save figures with a black background, you will need to pass facecolor=”k”, edgecolor=”k” to matplotlib.pyplot.savefig.
brain_colortuple, default=(0.5, 0.5, 0.5): The brain color to use as the background color (e.g., for transparent colorbars).
kwargsdict: Extra keyword arguments are passed to CutAxes used for plotting in each direction.

Attributes:

cut_coordsdict <str: 1D ndarray>: The cut coordinates in a dictionary. The keys are the directions (‘x’, ‘y’, ‘z’), and the values are sequences holding the cut coordinates.
axesdict of CutAxes: The axes used for plotting in each direction (‘x’, ‘y’ and ‘z’ here).
frame_axesAxes: The axes framing the whole set of views.
rect4- tuple: Position of axes within the figure.

See also

nilearn.plotting.displays.TiledSlicer: Three cuts are performed in orthogonal directions.
nilearn.plotting.displays.OrthoSlicer: Three cuts are performed and arranged in a 2x2 grid.

__init__(cut_coords, axes=None, black_bg=False, brain_color=(0.5, 0.5, 0.5), **kwargs)[source]¶

add_contours(img, threshold=1e-06, filled=False, **kwargs)[source]¶

Contour a 3D map in all the views.

Parameters:

imgNiimg-like object

See Input and output: neuroimaging data representation. Provides image to plot.

thresholdint or float or None, default=1e-6

Threshold to apply:

If None is given, the maps are 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.

filledbool, default=False

If filled=True, contours are displayed with color fillings.

kwargsdict

Extra keyword arguments are passed to function contour, or function contourf. Useful, arguments are typical “levels”, which is a list of values to use for plotting a contour or contour fillings (if filled=True), and “colors”, which is one color or a list of colors for these contours.

Raises:

ValueError: if the specified threshold is a negative number

Notes

If colors are not specified, default coloring choices (from matplotlib) for contours and contour_fillings can be different.

add_edges(img, color='r')[source]¶

Plot the edges of a 3D map in all the views.

Parameters:

imgNiimg-like object: See Input and output: neuroimaging data representation. The 3D map to be plotted. If it is a masked array, only the non-masked part will be plotted.
colormatplotlib color: str or (r, g, b) value, default=’r’: The color used to display the edge map.

add_markers(marker_coords, marker_color='r', marker_size=30, **kwargs)[source]¶

Add markers to the plot.

Parameters:

marker_coordsndarray of shape (n_markers, 3): Coordinates of the markers to plot. For each slice, only markers that are 2 millimeters away from the slice are plotted.
marker_colorpyplot compatible color or list of shape (n_markers,), default=’r’: List of colors for each marker that can be string or matplotlib colors.
marker_sizefloat or list of float of shape (n_markers,), default=30: Size in pixel for each marker.
kwargsdict: Extra keyword arguments are passed to matplotlib.pyplot.scatter.

add_overlay(img, threshold=1e-06, colorbar=False, cbar_tick_format='%.2g', cbar_vmin=None, cbar_vmax=None, transparency=None, transparency_range=None, **kwargs)[source]¶

Plot a 3D map in all the views.

Parameters:

imgNiimg-like object

See Input and output: neuroimaging data representation. If it is a masked array, only the non-masked part will be plotted.

thresholdint or float or None, default=1e-6

Threshold to apply:

If None is given, the maps are 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.

colorbarbool, optional

If True, display a colorbar next to the plots. Default=False.

cbar_tick_formatstr, default=”%.2g” (scientific notation)

Controls how to format the tick labels of the colorbar. Ex: use “%i” to display as integers.

cbar_vminfloat, default=None

Minimal value for the colorbar. If None, the minimal value is computed based on the data.

cbar_vmaxfloat, default=None

Maximal value for the colorbar. If None, the maximal value is computed based on the data.

transparencyfloat between 0 and 1, or a Niimg-Like object, or None, default = None

Value to be passed as alpha value to imshow. if None is passed, it will be set to 1. If an image is passed, voxel-wise alpha blending will be applied, by relying on the absolute value of transparency at each voxel.

Added in Nilearn 0.12.0.

transparency_rangetuple or list of 2 non-negative numbers, or None, default = None

When an image is passed to transparency, this determines the range of values in the image to use for transparency (alpha blending). For example with transparency_range = [1.96, 3], any voxel / vertex ( $v_i$ ):

with a value between between -1.96 and 1.96, would be fully transparent (alpha = 0),
with a value less than -3 or greater than 3, would be fully opaque (alpha = 1),
with a value in the intervals [-3.0, -1.96] or [1.96, 3.0], would have an alpha_i value scaled linearly between 0 and 1 : $alpha_i = (\lvert v_i \lvert - 1.96) / (3.0 - 1.96)$ .

This parameter will be ignored unless an image is passed as transparency. The first number must be greater than 0 and less than the second one. if None is passed, this will be set to [0, max(abs(transparency))].

Added in Nilearn 0.12.0.

kwargsdict

Extra keyword arguments are passed to function imshow.

Raises:

ValueError: if the specified threshold is a negative number

annotate(left_right=True, positions=True, scalebar=False, size=12, scale_size=5.0, scale_units='cm', scale_loc=4, decimals=0, **kwargs)[source]¶

Add annotations to the plot.

Parameters:

left_rightbool, default=True

If True, annotations indicating which side is left and which side is right are drawn.

positionsbool, default=True

If True, annotations indicating the positions of the cuts are drawn.

scalebarbool, default=False

If True, cuts are annotated with a reference scale bar. For finer control of the scale bar, please check out the draw_scale_bar method on the axes in “axes” attribute of this object.

sizeint, default=12

The size of the text used.

scale_sizeint or float, default=5.0

The length of the scalebar, in units of scale_units.

scale_units{‘cm’, ‘mm’}, default=’cm’

The units for the scalebar.

scale_locint, default=4

The positioning for the scalebar. Valid location codes are:

1: “upper right”
2: “upper left”
3: “lower left”
4: “lower right”
5: “right”
6: “center left”
7: “center right”
8: “lower center”
9: “upper center”
10: “center”

decimalsint, default=0

Number of decimal places on slice position annotation. If zero, the slice position is integer without decimal point.

kwargsdict

Extra keyword arguments are passed to matplotlib’s text function.

property black_bg¶: Return black background.

property brain_color¶: Return brain color.

close()[source]¶

Close the figure.

This is necessary to avoid leaking memory.

draw_cross(cut_coords=None, **kwargs)[source]¶

Draw a crossbar on the plot to show where the cut is performed.

Not implemented for this slicer.

Parameters:

cut_coordsdict <str: 1D ndarray> or None, default=None: The positions of the crosses to draw. If None is passed, the MosaicSlicer’s cut coordinates are used.
kwargsdict: Extra keyword arguments are passed to function matplotlib.pyplot.axhline.

classmethod find_cut_coords(img=None, threshold=None, cut_coords=None)[source]¶

Find world coordinates of cut positions compatible with this slicer.

Parameters:

img3D Nifti1Image, default=None

The brain image.

thresholdfloat, default=None

The lower threshold to the positive activation. If None, the activation threshold is computed using the 80% percentile of the absolute value of the map.

cut_coordsint, sequence of float or int or dict <str: 1D ndarray> or None, default=None

The world coordinates of the points where the cuts are performed.

If cut_coords is not provided, 7 coordinates of cuts are automatically calculated for each direction (‘x’, ‘y’, ‘z’). If an integer is provided, specified number of cuts are calculated for each direction.

Returns:

cut_coordsdict <str: 1D ndarray>: xyz world coordinates of cuts in a direction. Each key denotes the direction.

classmethod init_with_figure(img, threshold=None, cut_coords=None, figure=None, axes=None, black_bg=False, leave_space=False, colorbar=False, brain_color=(0.5, 0.5, 0.5), **kwargs)[source]¶

Initialize the slicer with an image.

Parameters:

imgNiimg-like object

See Input and output: neuroimaging data representation.

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.

cut_coordsNone, allowed types depend on the display_mode, optional

The world coordinates of the point where the cut is performed.

If display_mode is 'ortho' or 'tiled', this must be a 3-sequence of float or int: (x, y, z).
If display_mode is 'xz', 'yz' or 'yx', this must be a 2-sequence of float or int: (x, z), (y, z) or (x, y).
If display_mode is "x", "y", or "z", this can be:
- a sequence of float or int representing the coordinates of each cut in the corresponding direction,
- an int in which case it specifies the number of cuts to perform.
If display_mode is 'mosaic', this can be:
- an int in which case it specifies the number of cuts to perform in each direction "x", "y", "z".
- a 3-sequence of float or int in which case it specifies the number of cuts to perform in each direction "x", "y", "z" separately.
- dict <str: 1D ndarray> in which case keys are the directions (‘x’, ‘y’, ‘z’) and the values are sequences holding the cut coordinates.
If None is given, the cuts are calculated automatically.

figurematplotlib.figure.Figure

Figure to be used for plots.

axesmatplotlib.axes.Axes, or 4 tuple of float: (xmin, ymin, width, height), default=None

The axes, or the coordinates, in matplotlib figure space, of the axes used to display the plot. If None, the complete figure is used. default=None The axes that will be subdivided in 3.

black_bgbool, or “auto”, optional

If True, the background of the image is set to be black. If you wish to save figures with a black background, you will need to pass facecolor=”k”, edgecolor=”k” to matplotlib.pyplot.savefig. default=False

leave_spacebool, default=False

If True, leave space between the plots.

colorbarbool, optional

If True, display a colorbar next to the plots. Default=False.

brain_colortuple, default=(0.5, 0.5, 0.5)

The brain color to use as the background color (e.g., for transparent colorbars).

kwargsdict

Extra keyword arguments are passed to CutAxes used for plotting in each direction.

Raises:

ValueError: if the specified threshold is a negative number

savefig(filename, dpi=None, **kwargs)[source]¶

Save the figure to a file.

Parameters:

filenamestr: The file name to save to. Its extension determines the file type, typically ‘.png’, ‘.svg’ or ‘.pdf’.
dpiNone or scalar, default=None: The resolution in dots per inch.
kwargsdict: Extra keyword arguments are passed to matplotlib.pyplot.savefig.

title(text, x=0.01, y=0.99, size=15, color=None, bgcolor=None, alpha=1, **kwargs)[source]¶

Write a title to the view.

Parameters:

textstr: The text of the title.
xfloat, default=0.01: The horizontal position of the title on the frame in fraction of the frame width.
yfloat, default=0.99: The vertical position of the title on the frame in fraction of the frame height.
sizeint, default=15: The size of the title text.
colormatplotlib color specifier, default=None: The color of the font of the title.
bgcolormatplotlib color specifier, default=None: The color of the background of the title.
alphafloat, default=1: The alpha value for the background.
kwargsdict: Extra keyword arguments are passed to matplotlib’s text function.

Examples using `nilearn.plotting.displays.MosaicSlicer`¶

More plotting tools from nilearn

nilearn.plotting.displays.MosaicSlicer¶

Examples using nilearn.plotting.displays.MosaicSlicer¶

Examples using `nilearn.plotting.displays.MosaicSlicer`¶