Usage: Python

This page will cover how to use Nifti Overlay from within a Python session. The workflow is very similar to that of the CLI, so reading that usage page (Usage: Command Line) might also be helpful.

Basic Usage

Start by importing the nifti_overlay.core.NiftiOverlay class.

from nifti_overlay import NiftiOverlay

For every visualization, create an instance of the NiftiOverlay class.

overlay = NiftiOverlay()

You can then add layers to be plotted, using one of the .add_...() methods:

• add_anat() Plot the raw intensities of an image.

• add_mask() Plot only a single value within an image.

• add_edges() Plot the countours of an image.

• add_checkerboard() Plot 2 (or more) images interleaved with each other in a checkerboard pattern.

For example:

overlay.add_anat('t1.nii.gz')
overlay.add_mask('lesion_mask.nii.gz')

Images are parsed into objects (see nifti_overlay.image and nifti_overlay.multiimage), and stored in the images attribute of the NiftiOverlay instance.

Creating the plot

Once a NiftiOverlay class is instantiated and the desired images have been added, there are two methods which can be used for generating the visualization:

• nifti_overlay.core.NiftiOverlay.plot() will run the visualization. The plot will then be displayed if working in an environment where matplotlib can show plots.

• nifti_overlay.core.NiftiOverlay.generate() will also run the visualization, but will save the visualization as an image file.

Either of these methhods should be called at the end of the script, after all desired images have been added. When plotting, a new matplotlib Figure and several Axes will be created (these are accessible by the fig and axes attributes of the NiftiOverlay instance).

Options

There are two places where options can be specified to customize the visualization:

• During the instantiation of nifti_overlay.core.NiftiOverlay. These are global options which affect the entire visualization for all images plotted. Global options can change the number of slices/axes plotted, the DPI, the figure size, and others.

• When calling one of the add_...() methods. These are options which are specific to one image/layer being plotted. This is where the color/opacity of the layer can be set, as well as other layer-specific configurations.

As an example:

# set global options when initializing the overlay
overlay = NiftiOverlay(
    nslices=5,          # plot 5 slices for each image axis
    planes='zyx',       # select which axes are plotted (and their order)
    miny=0.4,           # set the range for over which slices are slected in the y-direction
    maxy=0.6,
    dpi=300             # set the DPI
)

# now set specific arguments for each image/layer being plotted
overlay.add_anat(
    src='t1.nii.gz',    # path to the image
    color='viridis',    # colormap to use
)

overlay.add_mask(
    src='mask.nii.gz',  # path to the image
    color='cyan',       # color for this image; only affects this image
    alpha=0.5,          # opacity; only affects this image
)

See nifti_overlay.core.NiftiOverlay for a complete list of global and layer-specific arguments. Also, see the gallery for more Python examples (Gallery).