API Documentation

Documentation reference for available functions in nifti_overlay.

The most important part here is the NiftiOverlay section, which documents the nifti_overlay.core.NiftiOverlay object. This is the tool which can be used for creating visualizations from a Python session, and it is what is ultimately called in the command line interface.

NiftiOverlay

Module containing code for generating images of NIFTI images overlaid on each other.

class nifti_overlay.core.NiftiOverlay(planes: str = 'xyz', nslices: int = 7, transpose: bool = False, min_all: None | float = None, max_all: None | float = None, minx: float = 0.15, maxx: float = 0.85, miny: float = 0.15, maxy: float = 0.85, minz: float = 0.15, maxz: float = 0.85, background: str = 'black', figsize: Tuple | str = 'automatic', dpi: int = 200, verbose: bool = False)

Bases: object

The main tool of the package, which creates tiled plots of one or more NIFTI images.

Initialize a NiftiOverlay object.

Parameters:

• planes (str, optional) – String specifying the number of rows being plotted, and the dimension of the image being plotted on each row. The length of the string indicates the number of rows being plotted, and the specific characters indicate the image dimensions being plotted (“x”, “y”, or “z”) and their order. Characters can be repeated or omitted.

• nslices (int, optional) – Integer specifying the number of slices to plot per plane, by default 7.

• transpose (bool, optional) – Make the overlay have shape [slices, planes] instead of [planes, slices], by default False.

• min_all (None | float, optional) – Proportion specifying the minimum extent of the image dimension over which to sample slices, by default None, in which case the minx, miny, and minz parameters are used.

• max_all (None | float, optional) – Proportion specifying the maximum extent of the image dimension over which to sample slices, by default None, in which case the minx, miny, and minz parameters are used.

• minx (float, optional) – Minimum slice sampling limit (proportion) in the x dimension, by default 0.15

• maxx (float, optional) – Maximum slice sampling limit (proportion) in the x dimension, by default 0.85

• miny (float, optional) – Minimum slice sampling limit (proportion) in the y dimension, by default 0.15

• maxy (float, optional) – Maximum slice sampling limit (proportion) in the y dimension, by default 0.85

• minz (float, optional) – Minimum slice sampling limit (proportion) in the z dimension, by default 0.15

• maxz (float, optional) – Maximum slice sampling limit (proportion) in the z dimension, by default 0.85

• background (str, optional) – Color passed to matplotlib which sets the background color of panels, by default ‘black’

• figsize (Tuple | str, optional) – Figure size, by default ‘automatic’, which provides a standard setting. Otherwise, a 2-tuple can be passed specifying the figure dimensions in inches.

• dpi (int, optional) – Figure DPI, by default 200

• verbose (bool, optional) – Report progress while generating overlays, by default False

property nrows

Number of rows of panels that will be plotted.

property ncols

Number of columns of panels that will be plotted.

property paddings

Get the slice sampling extent in each dimension.

Returns:

Dictionary with keys “x”, “y”, and “z”. For each, the value are the slice sampling limits provided as a 2-tuple (minimum, maximum).

Return type:

dict

add_anat(src: str | Path | Nifti1Image, color='gist_gray', alpha=1, scale_panel=False, drop_zero=False, vmin=None, vmax=None) → Anatomy

Add an anatomical image to be plotted. This is typically a continuously value image which will be represented with a continuous colormap.

Parameters:

• src (str | pathlib.Path | nib.Nifti1Image) – Source image.

• color (str, optional) – Colormap key from matplotlib. The default is ‘gist_gray’.

• alpha (float, optional) – Color transparency. The default is 1.0.

• scale_panel (bool, optional) – When plotting, scale the colormap to be the extent of intensities observed in each individual panel, rather than across the whole 3D volume. Can be used to maximize the dynamic range within each panel, but makes comparisons across panels more difficult. The default is False.

• drop_zero (bool, optional) – Don’t plot voxels which have a value of zero. The default is False.

• vmin (float | None, optional) – Bottom limit of color range. The default is None.

• vmax (float | None, optional) – Top limit of color range. The default is None.

Returns:

Object for managing the image being plotted.

Return type:

nifti_overlay.image.Anatomy

add_checkerboard(src: str | Path | Nifti1Image, boxes: int = 10, color: str = 'gist_gray', alpha: float = 1.0, normalize: bool = True, histogram_matching: bool = True) → CheckerBoard

Add a checkerboard to be plotted.

Parameters:

• src (Sequence[str, pathlib.Path, nib.Nifti1Image]) – Collection of images.

• boxes (int, optional) – The number of boxes across in the shortest dimension of the slice being plotted, by default 10

• color (str, optional) – Matplotlib colormap to use, by default ‘gist_gray’

• alpha (float, optional) – Color opacity, by default 1.0

• normalize (bool, optional) – Normalize slices being plotted to be between 0 and 1, by default True

• histogram_matching (bool, optional) – Use skimage.exposure.histogram_matching to normalize the intensities of images being plotted, by default True. As one colormap is applied to all images, this can be good to make sure all images are visible. May not be necessary if the images are all coming in with the same dynamic range.

Returns:

Object for managing the image being plotted.

Return type:

CheckerBoard

add_edges(src: str | Path | Nifti1Image, color: str = 'yellow', alpha: float = 1.0, sigma: float = 1.0, interpolation: str = 'none') → Edges

Add an edges image to be plotted. The contours/edges of each slice are automatically detected.

Parameters:

• src (str path, pathlib.Path, or nibabel.Nifti1Image) – Source image.

• color (str, RGB, RGBA, optional) – Color understood by matplotlib. The default is ‘yellow’.

• alpha (float, optional) – Color transparency. The default is 1.0.

• sigma (float, optional) – Standard deviation of the Gaussian filter of the Canny edge detector. The default is 1.0. See skimage.feature.canny.

• interpolation (str, optional) – Type of interpolation for plotting images. The default is ‘none’. See matplotlib for more details (plt.imshow).

Returns:

Object for managing the image being plotted.

Return type:

Edges

add_mask(src: str | Path | Nifti1Image, color: str | None = None, alpha: float = 1.0, mask_value: float = 1.0) → Mask

Add a mask to be plotted; a binary image plotted with a single color.

Parameters:

• src (str path, pathlib.Path, or nibabel.Nifti1Image) – Source image.

• color (str, RGB, RGBA, None, optional) – Color understood by matplotlib. The default is None, in which case the default color cycle is used.

• alpha (float, optional) – Color transparency. The default is 1.0.

• mask_value (int or float, optional) – Value to be plotted. For segmentations with multiple labels, this can be used to specify the single label to be plotted. The default is 1. (Note: to plot all values for a multi-label segmentation, you can plot it as an Anatomy instead of a Mask.)

Returns:

Object for managing the image being plotted.

Return type:

Mask

plot()

Run the plot with the provided parameters (set during initialization) of NiftiOverlay and the images added with the add_...() methods.

generate(savepath: str, separate: bool = False, rerun: bool = True)

Create the plot and save it to a file (or files).

Parameters:

• savepath (str) – Path to save output image file, with extension included. See matplotlib documentation for acceptable output format.s

• separate (bool, optional) – Save each panel as a separate image, by default False. In this case, a directory path should be provided instead of a single file path. Images will be saved as PNG. If the provided directory does not exist, it will attempt to be created.

• rerun (bool, optional) – Regenerate the figure before saving, by default True. In some cases, you may have already called the plot() method and made no changes to the visualization, in which case rerunning is not strictly necessary. But changes are not automatically detected - so rerunning is default.

Image Objects

Single Images

Classes for overlays generating plot data from single image files.

class nifti_overlay.image.Image(src: str | Path | Nifti1Image)

Bases: ABC

Generic, abstract class for representing a single image to plot. This is an abstract class, and should not be used directly.

Parameters:

src (str path, pathlib.Path, or nibabel.Nifti1Image) – Source image.

Raises:

• TypeError – src is not an accepted type.

• ValueError – Input image is not 3D.

Return type:

None.

property shape

Tuple specifying the length of each dimension.

aspect(dimension: int)

For a given dimension (int[0-2]), get the aspect ratio as indicated by the voxel size.

dimension_shape(dimension: int)

For a given dimension (int[0-2]), get the size of the remaining 2 dimensions. When plotting over a given dimension/axis, the image shape will be what is returned here.

abstract plot_slice(dimension: int, position: int, ax: Axes | None, **kwargs)

Plot a 2D slice from one axis (dimension) at a given depth (position).

abstract get_slice(dimension: int, position: int)

Return the data for a 2D slice from one axis (dimension) at a given depth (position).

class nifti_overlay.image.Anatomy(src: str | Path | Nifti1Image, color: str = 'gist_gray', alpha: float = 1.0, scale_panel: bool = False, drop_zero: bool = False, vmin: float | None = None, vmax: float | None = None)

Bases: Image

Class for plotting anatomical images, where the voxel values are typically continuous and should be plotted with a colormap.

Instantiate an Anatomy image.

Parameters:

• src (str | pathlib.Path | nib.Nifti1Image) – Source image.

• color (str, optional) – Colormap key from matplotlib. The default is ‘gist_gray’.

• alpha (float, optional) – Color transparency. The default is 1.0.

• scale_panel (bool, optional) – When plotting, scale the colormap to be the extent of intensities observed in each individual panel, rather than across the whole 3D volume. Can be used to maximize the dynamic range within each panel, but makes comparisons across panels more difficult. The default is False.

• drop_zero (bool, optional) – Don’t plot voxels which have a value of zero. The default is False.

• vmin (float | None, optional) – Bottom limit of color range. The default is None.

• vmax (float | None, optional) – Top limit of color range. The default is None.

Return type:

None.

get_slice(dimension: int, position: int)

Return the data to be plotted for a given slice. The data returned are the raw intensities of a slice through the 3D volume. If drop_zero is specified, the zero values with be replaced with NaN.

Parameters:

• dimension (int) – Image dimension to plot over (0 for x, 1 for y, 2 for z).

• position (int) – Index of the slice to plot.

Returns:

Imaging slice data.

Return type:

numpy array

plot_slice(dimension: int, position: int, ax: Axes | None = None, **kwargs)

Plot the data for a given slice.

Parameters:

• dimension (int) – Image dimension to plot over (0 for x, 1 for y, 2 for z).

• position (int) – Index of the slice to plot.

• ax (None | matplotlib.axes.Axes, optional) – Matplotlib axes to plot on, by default None, in which case plt.gca() is used.

Returns:

Axes after plotting.

Return type:

matplotlib axes

aspect(dimension: int)

For a given dimension (int[0-2]), get the aspect ratio as indicated by the voxel size.

dimension_shape(dimension: int)

For a given dimension (int[0-2]), get the size of the remaining 2 dimensions. When plotting over a given dimension/axis, the image shape will be what is returned here.

property shape

Tuple specifying the length of each dimension.

class nifti_overlay.image.Edges(src: str | Path | Nifti1Image, color: str = 'yellow', alpha: float = 1.0, sigma: float = 1.0, interpolation: str = 'none')

Bases: Image

Class for plotting the contours/edges (automatically detected) of a slice.

Instantiate an Edges image.

Parameters:

• src (str path, pathlib.Path, or nibabel.Nifti1Image) – Source image.

• color (str, RGB, RGBA, optional) – Color understood by matplotlib. The default is ‘yellow’.

• alpha (float, optional) – Color transparency. The default is 1.0.

• sigma (float, optional) – Standard deviation of the Gaussian filter of the Canny edge detector. The default is 1.0. See skimage.feature.canny.

• interpolation (str, optional) – Type of interpolation for plotting images. The default is ‘none’. See matplotlib for more details (plt.imshow).

Return type:

None.

get_slice(dimension: int, position: int)

Return the data to be plotted for a given slice. The data for a slice is first indexed, and then the Canny edge detector is run to generate the binary edge image for the slice.

Parameters:

• dimension (int) – Image dimension to plot over (0 for x, 1 for y, 2 for z).

• position (int) – Index of the slice to plot.

Returns:

Imaging slice data.

Return type:

numpy array

plot_slice(dimension: int, position: int, ax: Axes | None = None, **kwargs)

Plot the data for a given slice.

Parameters:

• dimension (int) – Image dimension to plot over (0 for x, 1 for y, 2 for z).

• position (int) – Index of the slice to plot.

• ax (None | matplotlib.axes.Axes, optional) – Matplotlib axes to plot on, by default None, in which case plt.gca() is used.

Returns:

Axes after plotting.

Return type:

matplotlib axes

aspect(dimension: int)

For a given dimension (int[0-2]), get the aspect ratio as indicated by the voxel size.

dimension_shape(dimension: int)

For a given dimension (int[0-2]), get the size of the remaining 2 dimensions. When plotting over a given dimension/axis, the image shape will be what is returned here.

property shape

Tuple specifying the length of each dimension.

class nifti_overlay.image.Mask(src: str | Path | Nifti1Image, color: str = 'red', alpha: float = 1.0, mask_value: float = 1.0)

Bases: Image

Class for plotting a binary mask, represented as a single color.

Instantiate a Mask image.

Parameters:

• src (str path, pathlib.Path, or nibabel.Nifti1Image) – Source image.

• color (str, RGB, RGBA, optional) – Color understood by matplotlib. The default is ‘red’.

• alpha (float, optional) – Color transparency. The default is 1.0.

• mask_value (int or float, optional) – Value to be plotted. For segmentations with multiple labels, this can be used to specify the single label to be plotted. The default is 1. (Note: to plot all values for a multi-label segmentation, you can plot it as an Anatomy instead of a Mask.)

Return type:

None.

aspect(dimension: int)

For a given dimension (int[0-2]), get the aspect ratio as indicated by the voxel size.

dimension_shape(dimension: int)

For a given dimension (int[0-2]), get the size of the remaining 2 dimensions. When plotting over a given dimension/axis, the image shape will be what is returned here.

property shape

Tuple specifying the length of each dimension.

get_slice(dimension: int, position: int)

Return the data to be plotted for a given slice. The intesities for a slice are first extracted. Then, all values matching the mask_value are replaced with 1, and all other values are replaced with NaN.

Parameters:

• dimension (int) – Image dimension to plot over (0 for x, 1 for y, 2 for z).

• position (int) – Index of the slice to plot.

Returns:

Imaging slice data.

Return type:

numpy array

plot_slice(dimension: int, position: int, ax: Axes | None = None, _override_color: str | None = None, **kwargs)

Plot the data for a given slice.

Parameters:

• dimension (int) – Image dimension to plot over (0 for x, 1 for y, 2 for z).

• position (int) – Index of the slice to plot.

• ax (None | matplotlib.axes.Axes, optional) – Matplotlib axes to plot on, by default None, in which case plt.gca() is used.

• _override_color (str | None) – Set a color which is only used at time of plotting. Mostly for internal purposes.

Returns:

Axes after plotting.

Return type:

matplotlib axes

Multiple Images

Classes for overlays computed from multiple images. Currently, this is only for Checkerboards, but could be extended for other purposes (e.g., plotting mathematical results derived from multiple images.)

class nifti_overlay.multiimage.MultiImage(src: Sequence[str | Path | Nifti1Image])

Bases: ABC

Class for plotting layers which are made up of multple images. This is an abstract class and should not be used directly.

Instantiate a MultiImage object.

Parameters:

src (collection) – List of paths to images (string or pathlib) or Nibabel images.

aspect(dimension: int)

For a given dimension (int[0-2]), get the aspect ratio as indicated by the voxel size.

dimension_shape(dimension: int)

For a given dimension (int[0-2]), get the size of the remaining 2 dimensions. When plotting over a given dimension/axis, the image shape will be what is returned here.

abstract get_slice(dimension: int, position: int)

Plot a 2D slice from one axis (dimension) at a given depth (position).

abstract plot_slice(dimension: int, position: int, ax: None | Axes = None, **kwargs)

Return the data for a 2D slice from one axis (dimension) at a given depth (position).

class nifti_overlay.multiimage.CheckerBoard(src: Sequence[str | Path | Nifti1Image], boxes: int = 10, normalize: bool = True, histogram_matching: bool = True, color: str = 'gist_gray', alpha: float = 1.0)

Bases: MultiImage

Multiple images plotted as an interleaved checkerboard.

Initialize a CheckerBoard.

Parameters:

• src (Sequence[str, pathlib.Path, nib.Nifti1Image]) – Collection of images.

• boxes (int, optional) – The number of boxes across in the shortest dimension of the slice being plotted, by default 10

• normalize (bool, optional) – Normalize slices being plotted to be between 0 and 1, by default True

• histogram_matching (bool, optional) – Use skimage.exposure.histogram_matching to normalize the intensities of images being plotted, by default True. As one colormap is applied to all images, this can be good to make sure all images are visible. May not be necessary if the images are all coming in with the same dynamic range.

• color (str, optional) – Matplotlib colormap to use, by default ‘gist_gray’

• alpha (float, optional) – Color opacity, by default 1.0

_assemble_checkerboard_mask(dimension: int)

Return an array which matches the shape of the dimensions being plotted and is filled with integers indicating which images (as indexed) should be plotted in which pixels.

Parameters:

dimension (int) – Plotting dimension of the image (0 for x, 1 for y, 2 for z).

Returns:

• numpy array – Checkerboard array

• :meta public:

get_slice(dimension: int, position: int)

Return the data to be plotted for a given slice.

Parameters:

• dimension (int) – Image dimension to plot over (0 for x, 1 for y, 2 for z).

• position (int) – Index of the slice to plot.

Returns:

Imaging slice data.

Return type:

numpy array

plot_slice(dimension: int, position: int, ax: None | Axes = None, **kwargs)

Plot the data for a given slice.

Parameters:

• dimension (int) – Image dimension to plot over (0 for x, 1 for y, 2 for z).

• position (int) – Index of the slice to plot.

• ax (None | matplotlib.axes.Axes, optional) – Matplotlib axes to plot on, by default None, in which case plt.gca() is used.

Returns:

Axes after plotting.

Return type:

matplotlib axes

aspect(dimension: int)

For a given dimension (int[0-2]), get the aspect ratio as indicated by the voxel size.

dimension_shape(dimension: int)

For a given dimension (int[0-2]), get the size of the remaining 2 dimensions. When plotting over a given dimension/axis, the image shape will be what is returned here.