lapgm 0.1.5

A spatially regularized Gaussian mixture model for MR bias field correction and intensity normalization.

lapgm

lapgm is an image correction software package primarily used for MR debiasing and normalization. This package is generalized to work with any number of spatial dimensions and assumes smooth, multiplicative image corruption which is invariant through image channels. Derivations and results for the spatially regularized Gaussian mixture can be found at LapGM: A Multisequence MR Bias Correction and Normalization Model.

Installation

Package lapgm can be installed using pip:

pip install lapgm

A CUDA accelerated version of lapgm is also available:

pip install lapgm[gpu]

Examples

An example overview on how to debias and normalize with lapgm is provided 'image_correction.ipynb' in the 'examples' subdirectory. For data, three biased presets from the BrainWeb normal dataset were used. Some of the debiased and normalized results have been provided below.

T2 debiasing results:

                   

T1 normalization results:

             

Usage

Below we list some common commands and procedures to help with the debiasing and normalization of MR images.

lapgm's GPU compute can be turned on and off globally with the 'use_gpu' command. Returned values will be loaded off of the GPU.

import lapgm

# Set compute to GPU
lapgm.use_gpu(True)

# Set compute back to CPU
lapgm.use_gpu(False)

Before running for debiasing, LapGM's hyperparameters must be specified.

# takes in optional downscale_factor and other saving meta-settings
debias_obj = lapgm.LapGM()

# required: inverse penalty strength 'tau' and number of class 'n_classes'
debias_obj.set_hyperparameters(tau=tau, n_classes=n_classes)

The cylindrical weighting scheme used by Vinas et al. is provided as:

# required: penalty relaxation alpha which goes as r^(-alpha)
# optional: center, semi-major axes, and symmetries of the cylindrical ellipse
debias_obj.specify_cylindrical_decay(alpha=alpha)

Debiasing can be run as:

# before running, disambiguate channeled data from spatial data with 'to_sequence array'
im_arr = lapgm.to_sequence_array([im_seq1, im_seq2])

# retrieve estimated parameters
params = debias_obj.estimate_parameters(im_arr)

# get debiased result
db_arr = lapgm.debias(im_arr, params)

Normalization can be run using the same debiased sequence data and estimated parameters from above:

# specify a target intensity to achieve
TRGT = 1000.

# normalize debiased array from before using estimated parameters and a target intensity
norm_arr = lapgm.normalize(db_arr, params, TRGT)

References

1. L. Vinas, A. A. Amini, J. Fischer, and A. Sudhyadhom. LapGM: A Multisequence MR Bias Correction and Normalization Model. arXiv.org:2209.13619 [physics.med-ph], Sept. 2022.

2. C.A. Cocosco, V. Kollokian, R.K.-S. Kwan, A.C. Evans. BrainWeb: Online Interface to a 3D MRI Simulated Brain Database. In: NeuroImage 5 (1997), p. 425.