pygrappa 0.6.0

GeneRalized Autocalibrating Partially Parallel Acquisitions.

About

GRAPPA is a popular parallel imaging reconstruction algorithm. Unfortunately there aren’t a lot of easy to use Python implementations available, so I decided to release this simple one.

Included in the pygrappa module are the following:

• grappa()

• tgrappa()

• slicegrappa()

• splitslicegrappa()

Installation

This package is developed in Ubuntu 18.04 using Python 3.6.8. That’s not to say it won’t work on other things. You should submit an issue when it doesn’t work like it says it should. The whole idea was to have an easy to use, pip-install-able GRAPPA module, so let’s try to do that.

In general, it’s a good idea to work inside virtual environments. I create and activate mine like this:

python3 -m venv ~/Documents/venvs/pygrappa
source ~/Documents/venvs/pygrappa/bin/activate

More information can be found in the venv documentation: https://docs.python.org/3/library/venv.html

Installation under a Unix-based platform should then be as easy as:

pip install pygrappa

See INSTALLATION.rst for more info on installing under Windows.

Usage

pygrappa.grappa() is called with undersampled k-space data and calibration data (usually a fully sampled portion of the center of k-space). The unsampled points in k-space should be exactly 0:

from pygrappa import grappa

sx, sy, ncoils = kspace.shape[:]
cx, cy, ncoils = calib.shape[:]
res = grappa(kspace, calib, kernel_size=(5, 5), coil_axis=-1)
sx, sy, ncoils = res.shape[:]

If calibration data is in the k-space data, simply extract it (make sure to call the ndarray.copy() method, may break if using reference to the original k-space data):

from pygrappa import grappa

sx, sy, ncoils = kspace.shape[:] # center 20 lines are ACS
ctr, pd = int(sy/2), 10
calib = kspace[:, ctr-pd:ctr+pad, :].copy()
res = grappa(kspace, calib, kernel_size=(5, 5), coil_axis=-1)
sx, sy, ncoils = res.shape[:]

A very similar GRAPPA implementation with the same interface can be called like so:

from pygrappa import cgrappa
res = cgrappa(kspace, calib, kernel_size=(5, 5), coil_axis=-1)

This function uses much of the same code as the Python grappa() implementation, but has certain parts written in C++ and all compiled using Cython. It runs about twice as fast but is considered experimental. It will probably become the default GRAPPA implementation in future releases.

TGRAPPA does not require calibration data and can be called as:

from pygrappa import tgrappa

sx, sy, ncoils, nt = kspace.shape[:]
res = tgrappa(
    kspace, calib_size=(20, 20), kernel_size=(5, 5),
    coil_axis=-2, time_axis=-1)

Calibration region size and kernel size must be provided. The calibration regions will be constructed in a greedy manner: once enough time frames have been consumed to create an entire ACS, GRAPPA will be run. TGRAPPA uses the cgrappa implementation for its speed.

slicegrappa() is a Slice-GRAPPA implementation that can be called like:

from pygrappa import slicegrappa

sx, sy, ncoils, nt = kspace.shape[:]
sx, sy, ncoils, sl = calib.shape[:]
res = slicegrappa(kspace, calib, kernel_size=(5, 5), prior='sim')

kspace is assumed to SMS-like with multiple collapsed slices and multiple time frames that each need to be separated. calib are the individual slices’ kspace data at the same size/resolution. prior tells the Slice-GRAPPA algorithm how to construct the sources, that is, how to solve T = S W, where T are the targets (calibration data), S are the sources, and W are GRAPPA weights. prior=’sim’ creates S by simulating the SMS acquisition, i.e., S = sum(calib, slice_axis). prior=’kspace’ uses the first time frame from the kspace data, i.e., S = kspace[1st time frame]. The result is an array containing all target slices for all time frames in kspace.

Similarly, Split-Slice-GRAPPA can be called like so:

from pygrappa import splitslicegrappa as ssgrappa

sx, sy, ncoils, nt = kspace.shape[:]
sx, sy, ncoils, sl = calib.shape[:]
res = ssgrappa(kspace, calib, kernel_size=(5, 5))

# Note that pygrappa.splitslicegrappa is an alias for
# pygrappa.slicegrappa(split=True), so it can also be called
# like this:
from pygrappa import slicegrappa
res = slicegrappa(kspace, calib, kernel_size=(5, 5), split=True)

Also see the examples module. It has several scripts showing basic usage. Docstrings are also a great resource – check them out for all possible arguments and usage info.