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.XSlicer¶

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

The XSlicer class enables sagittal visualization with plotting functions of Nilearn like nilearn.plotting.plot_img.

This visualization mode can be activated by setting display_mode='x':

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

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

Attributes:

cut_coords1D ndarray: The cut coordinates.
axesdict of CutAxes: The axes used for plotting.
frame_axesAxes: The axes framing the whole set of views.

See also

nilearn.plotting.displays.YSlicer: Coronal view
nilearn.plotting.displays.ZSlicer: Axial view

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

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.

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

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

colorbarbool, default=False

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

cbar_vminfloat, optional

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

cbar_vmaxfloat, optional

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

Parameters:

cut_coords3-tuple of float, optional: The position of the cross to draw. If None is passed, the OrthoSlicer’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]¶

Instantiate the slicer and find cut coordinates.

Parameters:

img3D Nifti1Image: The brain map.
thresholdfloat, optional: 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_coordslist of float, optional: xyz world coordinates of cuts.

Returns:

cut_coordslist of float: xyz world coordinates of cuts.

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_coords3 tuple of int: The cut position, in world space.
axesmatplotlib.axes.Axes, optional: The axes that will be subdivided in 3.
black_bgbool, default=False: If True, the background of the figure will be put to 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).

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.

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, optional: The color of the font of the title.
bgcolormatplotlib color specifier, optional: The color of the background of the title.
alphafloat, default=1: The alpha value for the background.
kwargs: Extra keyword arguments are passed to matplotlib’s text function.

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

More plotting tools from nilearn

nilearn.plotting.displays.XSlicer¶

Examples using nilearn.plotting.displays.XSlicer¶

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