gradunwarp is a Python/Numpy package used to unwarp the distorted volumes (due to the gradient field inhomogenities). Currently, it can unwarp Siemens data.
This is the Human Connectome Project version of the gradunwarp package.
It is forked from a "no longer actively maintained" gradunwarp package.
This fork contains changes made for and by the WU-Minn Human Connectome Project consortium (HCP) for use within the HCP Minimal Preprocessing Pipelines.
You can install the necessary prerequisites in most Ubuntu or Debian-based distributions with this command:
sudo apt install python3-numpy python3-pip
For convenience the latest gradunwarp tarball can be downloaded from here.
First, extract the gradunwarp tarball, and cd into the folder it creates. Then do:
sudo pip3 install -r requirements.txt
sudo pip3 install .
If you don't have superuser permissions on the machine, you can use the --user switch of pip install instead of using sudo:
pip3 install -r requirements.txt --user
pip3 install . --user
If you use the --user switch, you will need to add /home/<username>/.local/bin to your PATH environment variable, replacing <username> with your user name.
You may optionally choose to install gradunwarp into a python virtual environment in order to avoid possible interference with your existing python setup. If the python virtual environment module is not already installed, then you may need to run
sudo apt install python3-venv
before running the below.
First, extract the gradunwarp tarball, and cd into the folder it creates.
Then do:
python3 -m venv gradunwarp.build
source gradunwarp.build/bin/activate
pip install -r requirements.txt
pip install .
deactivate
The command deactivate ensures that your python environment is set to the way it was before.
After this installation, you can then use gradunwarp by adding
source "$PATH_TO_INSTALLATION"/gradunwarp.build/bin/activate
to your scripts, where "$PATH_TO_INSTALLATION" should be replaced with the path where you installed gradunwarp.
Note that you may need to deactivate the virtual environment after running gradunwarp in your scripts to use other environments.
Installation using python2 is slightly different to that for python3 above.
As above extract the gradunwarp tarball, and cd into the folder it creates.
Then do:
virtualenv -p python2 gradunwarp.build
source gradunwarp.build/bin/activate
pip install -r requirements.txt
pip install .
deactivate
Note that virtualenv is used instead of venv.
This virtual environment can then be used in the same way as described for python3 above.
Dependencies of nibabel:
skeleton
gradient_unwarp.py infile outfile manufacturer -g <coefficient file> [optional arguments]
typical usage
gradient_unwarp.py sonata.mgh testoutson.mgh siemens -g coeff_Sonata.grad --fovmin -.15 --fovmax .15 --numpoints 40
gradient_unwarp.py avanto.mgh testoutava.mgh siemens -g coeff_AS05.grad -n
The input file (in Nifti or MGH formats) followed by the output file name (which has the Nifti or MGH extensions -- .nii/.nii.gz/.mgh/.mgz) followed by the vendor name.
-c <coef_file>
-g <grad_file>
The coefficient file (which is acquired from the vendor) is specified
using a -g option, to be used with files of type .grad.
Or it can be specified using a -c in the case you have the .coef
file.
These two options are mutually exclusive.
-n : If you want to suppress the jacobian intensity correction
-w : if the volume is to be warped rather than unwarped
--fovmin <fovmin> : a float argument which specifies the minimum extent of the grid where spherical harmonics are evaluated. (in meters). Default is -.3
--fovmax <fovmax> : a float argument which specifies the maximum extent of the grid where spherical harmonics are evaluated. (in meters). Default is .3
--numpoints <numpoints> : an int argument which specifies the number of points in the grid. (in each direction). Default is 60
--interp_order <order of interpolation> : takes values from 1 to 4. 1 means the interpolation is going to be linear which is a faster method but not as good as higher order interpolations.
--help : display help
gradunwarp tends to use quite a bit of memory because of the intense spherical harmonics calculation and interpolations performed multiple times. For instance, it uses almost 85% memory of a 2GB memory 2.2GHz DualCore system to perform unwarping of a 256^3 volume with 40^3 spherical harmonics grid. (It typically takes 4 to 5 minutes for the entire unwarping)
Some thoughts:
Please see the Copying.md file in the distribution.
Some of the changes to this codebase that were made for the HCP, were made when this code
was not yet forked into its own repository. At that time, this modified version of the
gradient unwarping code was embedded in the src/gradient_unwarping
subdirectory of the HCP Pipelines Repository.
The history (commit comments, changelog, etc. of those changes was not ported to this repository. The HCP Pipelines Repository will keep that history.
To get the last version of the HCP Pipelines Repository before the
gradient unwarping code was separated, retrieve commit 2e06194921638394c7c0ffd90805fdf06051449a.
To do this, after cloning the HCP Pipelines Repository use:
$ git checkout 2e06194921638394c7c0ffd90805fdf06051449a
FAQs
HCP version of Gradient Unwarping Package for Python/Numpy
We found that nipy-gradunwarp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.