dMRI pre-processing (complete)

[oesteban]

Continuing with #525, a full pre-processing pipeline for dMRI is proposed:

• Motion correction artifact: a new workflow is created with rigid registration (6 degrees of freedom) among volumes, and rotation of the B-matrix (Leemans et al. 2007 - http://www.ncbi.nlm.nih.gov/pubmed/19319973).
• Eddy currents correction: some minor improvements (explicitly set affine registration), following (Rolheiser 2011 [online: http://wiredminds.blogspot.com.es/2011/06/dti-preprocessing-in-fsl-b-vector.html]).
• Epidewarp.fsl script has been renamed to 'susceptibility' correction and added some extra features (the most important one being the possibility to introduce the GRAPPA acceleration factor if parallel imaging was used).
• A new workflow integrating the 3 elements for dMRI correction.

TODO: it would be nice to separate workflows for consistency, collecting all of them simultaneously appropriate for fMRI and dMRI on one side and separating the ones specific for dMRI (the motion correction pipeline and the full pre-processing pipeline).

[oesteban]

Adds support to save the output log of FLIRT in verbose mode. It was necessary when I wanted to use the fdt_rotate_bvecs script from FSL. Finally, I decided to perform the B-matrix rotation using numpy.

[satra]

use np.array instead of np.matrix.

[oesteban]

Isn't it necessary for the posterior matrix multiplication?

[satra]

very nice effort. a couple of things:

• depending on how the dicoms were converted to nifti the bvecs may not be proper - you should warn users in the docs to ensure that their conversion automatically adjusts things to image space. dcm2nii does this, but other converters may not
• make sure spline interpolation is used wherever resampling is required
• run autopep8/pep8 for syntax

[chrisgorgo]

Excellent work again. I think we can simplify this a bit. As far as I know eddy correction (as implemented in FSL) is just affine registration of all volumes to the reference volume. Which is the same what create_motion_correct_pipeline is doing (with addition of bvecs rotation). And the same what create_susceptibility_correct_pipeline would do. Instead I propose the following:

1. Have one pipeline that just does the corregistration to ref image (like eddy_correct). Make this pipeline expose the corregistration matrices in outputfield. - pipeline1
2. Have a dwi specific motion/eddy correction pipeline that would call pipeline1 and do the bvecs rotation on top of it. - pipeline2
3. Have the susceptibility correction pipeline call pipeline2 if user requires coregistration. pipeline3

This way the corregistration code is not repeated and we can drop create_dmri_preprocessing pipeline.

[oesteban]

Thanks,

I explicitly separated eddy_correct and motion correction because they should be treated separately (it is detailed here: http://wiredminds.blogspot.com.es/2011/06/dti-preprocessing-in-fsl-b-vector.html)

For fMRI, both pipelines could (and should) be performed at once, as you suggest. As it is implemented right now, you can keep using only eddy_correct (actually, you should).

About refactoring organization, I would be happy to make it, no problem.

EDIT (explanation):

eddy_correct needs dof=12 for FLIRT
motion_correct needs dof=6 for FLIRT

[chrisgorgo]

Ok I get it now - so the difference is that for bvecs rotation you need 6 dof and for actual correction 12 dof?

In this case I propose the following:

1. Have one pipeline that just does the corregistration to ref image (like eddy_correct). Make this pipeline expose the corregistration matrices in outputfield. Add dof as an input parameter - pipeline1
2. Have a dwi specific motion/eddy correction pipeline that would call pipeline1 twice - once with dof=6 for bvec rotation and once with dof=12 for actual correction. - pipeline2
3. Have the susceptibility correction pipeline call pipeline2 if user requires coregistration. pipeline3

I'm just trying to avoid code redundancy.

[oesteban]

Great :)

Sounds good that all the spliting-coregistration-merging process is performed with just one pipeline.

I don't know if I fully understand 3). In the susceptibility pipeline, the optional coregistration is against the magnitude of the fieldmap...

About 2): this is OK for dMRI, but you could not use this pipeline for fMRI, that only needs one coregistration with dof=12.

So, this could be a possible structure:

Pipeline 1: dwi corregistration:

• Provides an input for the reference volume. If we want to perform eddy currents correction or motion correction we connect a Select node with the B0. If we want to use it inside the susceptibility correction, we plug the magnitude of the fieldmap in.
• Provides an input for the dwi
• Provides an input for the dof
• Provides an output with the matrices

Pipeline 2: eddy_correct
Pipeline 3: motion correct
Pipeline 4: susceptibility correct

The complete correction pipeline (calling all the rest) could be avoided, but it is really convenient...

[oesteban]

(and it is useful and illustrating to have the 3 different corrections separated, specially for dMRI experienced people)

[satra]

the other thing that might be useful, since you are using the fsl tools anyway, is to get another pipeline with the newer tools - topup and eddy - we don't have interfaces for those yet. but all of that can be in two separate PRs.

[oesteban]

Yes, I did not see those two new tools :$, but I agree, they should go through two separate PRs

[oesteban]

@chrisfilo I quickly created the co-registration pipeline, but realized that it is only apt for the eddy currents and motion correction pipelines. Parameters are quite different in the susceptibility correction pipeline.

I agree with @satra: probably it is better to explore interfacing the newer tools (topup and eddy) and provide workflows for them, allowing the community to make comparisons.

Are you still interested on creating this extra pipeline? It just saves 3 or 4 lines in each pipeline (and adds constraints for people interested on modifying them).

[chrisgorgo]

Ok fair enough (sorry for misreading the pipeline3 - you are right of course). In the future we should think of extracting rotation components from the 12 DOF affine matrices instead of doing it in two steps (see http://callumhay.blogspot.de/2010/10/decomposing-affine-transforms.html ).