Giter VIP home page Giter VIP logo

gradunwarp's Introduction

gradunwarp

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.

Installation

Prerequisites

You can install the necessary prerequisites in most Ubuntu or Debian-based distributions with this command:

sudo apt-get install python3-numpy python3-pip

Install

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 .

If you don't have superuser permissions on the machine, you can use the --user switch of pip install:

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.

Details

If you are on an old distribution that doesn't have the necessary versions of nibabel and its dependencies, here are the details of what you need:

  • Python (>=2.7 or 3.x)
  • Numpy
  • Scipy
  • Numpy devel package, if separate (to compile external modules written in C)
  • nibabel (1.2.0 or later, for MGH support)

Dependencies of nibabel:

  • PyDICOM 0.9.5 or later (for DICOM support)
  • nose 0.11 or later (to run the tests)
  • sphinx (to build the documentation)

Usage

Note that a core component of gradient_unwarp.py (unwarp_resample.py) uses a subprocess call to the FSL tools fslval and fslorient. So FSL must be installed and its configuration file correctly sourced (i.e., FSLDIR and FSLOUTPUTTYPE must be defined appropriately in your environment, and ${FSLDIR}/bin must be in your PATH and contain fslval, fslorient, and fslhd -- this should be done for you by the SetUpHCPPipeline.sh script). FSLOUTPUTTYPE must be set to NIFTI_GZ, which is the default.

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

Positional Arguments

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.

Required Options

-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.

Other Options

-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

Memory Considerations

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:

  • Use lower resolution volumes if possible
  • Run gradunwarp in a computer with more memory
  • Use -numpoints to reduce the grid size. -fovmin and -fovmax can be used to move the grid close to your data extents.
  • Use non-compressed source volumes. i.e. .mgh and .nii instead of .mgz/.nii.gz
  • Recent versions of Python, numpy and scipy

HCP additions

  • slice by slice processing
  • x-y flip bug fix
  • force 32-bit output in 64-bit systems
  • modified for Python3 compatibility

License

Please see the Copying.md file in the distribution.

Credit

  • Jon Polimeni - gradunwarp follows his original MATLAB code
  • Karl Helmer - Project Incharge
  • Nibabel team

Note about change history

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

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.