PyHySCO

This is a package for Echo-Planar MRI susceptibility artifact correction implemented in PyTorch.

Associated Publication

PyHySCO: GPU-Enabled Susceptibility Artifact Distortion Correction in Seconds

https://arxiv.org/abs/2403.10706

Please cite as

@article{julian2024pyhysco,
      title={PyHySCO: GPU-Enabled Susceptibility Artifact Distortion Correction in Seconds}, 
      author={Abigail Julian and Lars Ruthotto},
      year={2024},
      journal = {arXiv preprint arXiv:2403.10706}
}

Installation

From PyPI:

pip install PyHySCO

Python package dependencies (automatically installed by pip) are listed in requirements.txt. It is suggested to run the python file tests/test_all.py to ensure all tests are passing and the code is setup properly.

Usage

Command Line Correction

The program can be run directly from a terminal or command line by using the python command to run the file pyhysco.py or if installed using pip the command pyhysco. Supplying the following required parameters:

• file_1: file path of first image (stored as nii.gz) with phase encoding direction opposite of file_2
• file_2: file path of second image (stored as nii.gz) with phase encoding direction opposite of file_1
• ped: phase-encoding dimension (1, 2, or 3)

Use the help flag (--help) to see optional parameters available.

Minimal Usage:

pyhysco --file_1 <image1> --file_2 <image2> --ped <phase encoding direction>

Example:

pyhysco --file_1 image1.nii.gz --file_2 image2.nii.gz --ped 1 --output_dir results/ --max_iter 25

Write a Correction Script

A user-written script can be used to call the methods of the program.

Example:

from EPI_MRI.EPIMRIDistortionCorrection import *
from optimization.GaussNewton import *
import torch

device = 'cuda:0' if torch.cuda.is_available() else 'cpu'

# load the image and domain information
# change this function call to be the filepath for your data
data = DataObject('../data/156334_v.nii.gz', '../data/156334_-v.nii.gz', 1, device=device,dtype=torch.float32)

loss_func = EPIMRIDistortionCorrection(data, 300, 1e-4, regularizer=myLaplacian3D, PC = JacobiCG)
# initialize the field map
B0 = loss_func.initialize(blur_result=True)
# set-up the optimizer
# change path to be where you want logfile and corrected images to be stored
opt = GaussNewton(loss_func, max_iter=500, verbose=True, path='results/gnpcg-Jac/')
# optimize!
opt.run_correction(B0)
# save field map and corrected images
opt.apply_correction()
# see plot of corrected images
opt.visualize()

Examples and Further Documentation

There are a set of examples in the examples directory. Full API documentation is in the docs directory. See also Instructions.md for an overview of the correction process.

Acknowledgements

This material is partly based upon work supported by the US National Science Foundation Graduate Research Fellowship under Grant No. 1937971 and NSF Grants DMS-1751636 and DMS-2038118. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the funding agencies.