Alignment check - API

A tutorial-like presentation is available at Alignment check - usage, using the following API:

Top-level package for mrivis.

mrivis.checkerboard(img_spec1=None, img_spec2=None, patch_size=10, view_set=(0, 1, 2), num_slices=(10, ), num_rows=2, rescale_method='global', background_threshold=0.05, annot=None, padding=5, output_path=None, figsize=None)

Checkerboard mixer.

Parameters:

img_spec1 : str or nibabel image-like object

MR image (or path to one) to be visualized

img_spec2 : str or nibabel image-like object

MR image (or path to one) to be visualized

patch_size : int or list or (int, int) or None

size of checker patch (either square or rectangular) If None, number of voxels/patch are chosen such that,

there will be 7 patches through the width/height.

view_set : iterable

Integers specifying the dimensions to be visualized. Choices: one or more of (0, 1, 2) for a 3D image

num_slices : int or iterable of size as view_set

number of slices to be selected for each view Must be of the same length as view_set,

each element specifying the number of slices for each dimension. If only one number is given, same number will be chosen for all dimensions.

num_rows : int

number of rows (top to bottom) per each of 3 dimensions

rescale_method : bool or str or list or None

Range to rescale the intensity values to Default: ‘global’, min and max values computed based on ranges from both images. If false or None, no rescaling is done (does not work yet).

background_threshold : float or str

A threshold value below which all the background voxels will be set to zero. Default : 0.05. Other option is a string specifying a percentile: ‘5%’, ‘10%’. Specify None if you don’t want any thresholding.

annot : str

Text to display to annotate the visualization

padding : int

number of voxels to pad around each panel.

output_path : str

path to save the generate collage to.

figsize : list

Size of figure in inches to be passed on to plt.figure() e.g. [12, 12] or [20, 20]

Returns:

fig : figure handle

handle to the collage figure generated.

mrivis.voxelwise_diff(img_spec1=None, img_spec2=None, abs_value=True, cmap='gray', overlay_image=False, overlay_alpha=0.8, num_rows=2, num_cols=6, rescale_method='global', background_threshold=0.05, annot=None, padding=5, output_path=None, figsize=None)

Voxel-wise difference map.

Parameters:

img_spec1 : str or nibabel image-like object

MR image (or path to one) to be visualized

img_spec2 : str or nibabel image-like object

MR image (or path to one) to be visualized

abs_value : bool

Flag indicating whether to take the absolute value of the diffenence or not. Default: True, display absolute differences only (so order of images does not matter)

Colormap to show the difference values.

overlay_image : bool

Flag to specify whether to overlay the difference values on the original image. .. note: This feature is not reliable and supported well yet.

num_rows : int

number of rows (top to bottom) per each of 3 dimensions

num_cols : int

number of panels (left to right) per row of each dimension.

rescale_method : bool or str or list or None

Range to rescale the intensity values to Default: ‘global’, min and max values computed based on ranges from both images. If false or None, no rescaling is done (does not work yet).

background_threshold : float or str

A threshold value below which all the background voxels will be set to zero. Default : 0.05. Other option is a string specifying a percentile: ‘5%’, ‘10%’. Specify None if you don’t want any thresholding.

annot : str

Text to display to annotate the visualization

padding : int

number of voxels to pad around each panel.

output_path : str

path to save the generate collage to.

figsize : list

Size of figure in inches to be passed on to plt.figure() e.g. [12, 12] or [20, 20]

Returns:

fig : figure handle

handle to the collage figure generated.

mrivis.color_mix(img_spec1=None, img_spec2=None, alpha_channels=None, color_space='rgb', view_set=(0, 1, 2), num_slices=(10, ), num_rows=2, rescale_method='global', background_threshold=0.05, annot=None, padding=5, output_path=None, figsize=None)

Color mixer, where each image is represented with a different color (default: red and green) in color channels.

Parameters:

img_spec1 : str or nibabel image-like object

MR image (or path to one) to be visualized

img_spec2 : str or nibabel image-like object

MR image (or path to one) to be visualized

alpha_channels : (float, float)

weights for red and green channels in the composite image. Default: [1, 1]

color_space : str

type of color space to mix the images in. Currently supports ‘rgb’ only. Support for ‘hsv’ coming later.

view_set : iterable

Integers specifying the dimensions to be visualized. Choices: one or more of (0, 1, 2) for a 3D image

num_slices : int or iterable of size as view_set

number of slices to be selected for each view Must be of the same length as view_set,

each element specifying the number of slices for each dimension. If only one number is given, same number will be chosen for all dimensions.

num_rows : int

number of rows (top to bottom) per each of 3 dimensions

rescale_method : bool or str or list or None

Range to rescale the intensity values to Default: ‘global’, min and max values computed based on ranges from both images. If false or None, no rescaling is done (does not work yet).

background_threshold : float or str

A threshold value below which all the background voxels will be set to zero. Default : 0.05. Other option is a string specifying a percentile: ‘5%’, ‘10%’. Specify None if you don’t want any thresholding.

annot : str

Text to display to annotate the visualization

padding : int

number of voxels to pad around each panel.

output_path : str

path to save the generate collage to.

figsize : list

Size of figure in inches to be passed on to plt.figure() e.g. [12, 12] or [20, 20]

Returns:

fig : figure handle

handle to the collage figure generated.

Helpers and Utility scripts

mrivis.utils.scale_0to1(image_in, exclude_outliers_below=False, exclude_outliers_above=False)

Scale the two images to [0, 1] based on min/max from both.

Parameters:

image_in : ndarray

Input image

exclude_outliers_{below,above} : float

Lower/upper limit, a value between 0 and 100.

Returns:

scaled_image : ndarray

clipped and/or scaled image

mrivis.utils.row_wise_rescale(matrix)

Row-wise rescale of a given matrix.

For fMRI data (num_voxels x num_time_points), this would translate to voxel-wise normalization over time.

Parameters:

matrix : ndarray

Input rectangular matrix, typically a carpet of size num_voxels x num_4th_dim, 4th_dim could be time points or gradients or other appropriate

Returns:

normed : ndarray

normalized matrix

mrivis.utils.threshold_image(img, bkground_thresh, bkground_value=0.0)

Thresholds a given image at a value or percentile.

Replacement value can be specified too.

Parameters:

image_in : ndarray

Input image

bkground_thresh : float

a threshold value to identify the background

bkground_value : float

a value to fill the background elements with. Default 0.

Returns:

thresholded_image : ndarray

thresholded and/or filled image