dti_preproc - IBIC DTI preprocessing scripts

Motivation

This project is a collection of scripts and utilities aimed at simplifing DTI preprocessing.

The main features of this package are:

• Automatic generation of QA reports as standalone .html files
• Itegrated motion correction and EPI unwarping (both fieldmap-based unwarping and “blip-up, blip-down” unwarping)
• Support for processing pipelines based on GNU make
• Specify direction of unwarping. Supported directions are y (default) and y-, which is set by adding the -Y flag to dti_preproc.sh or the unwarp scripts.

These scripts are intended implement ‘state of the art’ preprocessing options by default. This includes motion correction with FSL’s ‘eddy’, with rotation of the b-vectors, and tensor estimation using RESTORE.

Preparing the Data

This script assumes all B0s and DWIs are concatenated into one 4d image, with the B0 images first. Depending on the type of EPI unwarping required, you may need to create an "acquisition parameter file" and/or an "index file" in FSL format, described here. You will also need to generate an initial brain mask.

Make-Based Pipeline:

These scripts can be integrated into a processing pipeline based on ‘GNU Make’, using the approach described in Askren et al. 2016. example_makefile.mk can serve as a template, but will need to be modified for your particular environment.

To help with functionality in make-based pipelines, there is the addtional flag -T <name> which allows you to supply a prefix to the temp directory to make sure two directiories don't end up with the same name while make is running concurrently.

Files in the Repository

main scripts

• dti_preproc.sh this is the main script it can call the other scripts in the appropriate order
• unwarp_bupbdown.sh unwarps EPI distortions using images acquired with the phase-encoding along opposite direction (i.e. “blip-up, blip-down” images)
• motion_correct.sh corrects for motion and eddy currents using fsl’s ‘eddy’
• unwarp_fieldmap.sh unwarps EPI distortions using an acquired fieldmap
• fit_tensor.sh fits the diffusion tensor (defaut: RESTORE as implemented in Camino)

report generation

These are called by the main scripts but may be invoked on their own

• unwarp_bupbdown_report.sh example
• motion_correct_report.sh example
• unwarp_fieldmap_report.sh example
• fit_tensor_report.sh example

utilites for preparing the data

• concatenate_diffusion.sh combines two runs of diffusion data, including 4d images, b-values and b-vectors.
• rearrange_diffusion.sh rearranges a diffusion run (again, including 4d images, bvals, bvecs)

utilities that are called by other scripts

• eddy_pars_to_xfm_dir.py takes a ‘motion parameter file’ as generated by eddy and makes a directory of linear transforms
• image_to_movie.sh takes a 4d image and creates an animated gif showing tri-planar images across various slices
• image_to_gif.sh takes 3D images and makes static images. also handles overlays (basically a wrapper for slicer)

other resources

• b02b0_fast.cnf configuration file for topup that does a minimal amount of processing. Used for debugging/testing in “fast mode”
• example_makefile.mk an example makefile for gnu-make based processing

Dependencies

• imagemagick
• whirlgif OR Gifsicle
• fsl ( if installed with neurodebian, make sure you read this )
• camino
• R (with package rmarkdown)
• pandoc

TO DO

• Correct min/max display info in header of output images
• add BIDS compatibility

Add to report

• versions of fsl, camino, etc
• embed entirety of log file somehow
• display rotating gif of bvecs
• display fieldmap estimated from topup
• display gif of residuals across DWIs