As I’ve mentioned before, it’s a good idea to do some preprocessing on your diffusion imaging data! Previous tutorials have covered using AFNI’s built-in tools (Part 1, Part 2, Part 3) as well as the very formidable TORTOISE (Part 1, Part 2, Part 3). As with most things in NeuroImaging, you have many options when processing your data! So today I’m going to cover a bit about DTIprep. If you’re wondering how DTIprep stacks up against TORTOISE, I encourage you to read this publication.
You will notice that DTIprep and TORTOISE work very differently and have different strengths and weaknesses! Ultimately you will have to weigh these against your goals and decide which software suits your needs more. In my initial tests, both packages improve tractography results. I think the one major plus to TORTOISE for my needs (right now) is the integration of blip-up blip-down correction. Though with some creative fiddling, you could (probably) use this tool with DTIprep output.
Before you go too much further, I encourage you to download 3D Slicer (sometimes just called “Slicer”), as DTIprep makes use of several other modules in the software, particularly data format conversion. Like TORTOISE, DTIprep has a nice Graphical User Interface (GUI). Unlike TORTOISE, DTIprep also has a command line interface for easy scripting! That’s not to say that you cannot automate TORTOISE, indeed we have automated it using the IDL interface, but that requires a full license of IDL and a willingness to fiddle with your input files until you can match what TORTOISE expects!
Also unlike TORTOISE, which accepts a great number of input formats, DTIprep currently only accepts data in NRRD format, though it does have a converter for reading DICOM files in. I’m not sure I count this as a deal breaker, as I’ve found that NRRD is a fairly nice file format and includes information about the B-MATRIX right alongside the imaging data!
DTIprep Main Window
Data Conversion to NRRD
Whether you plan to use the GUI or not, converting your imaging data to NRRD format (or back to NIFTI) is fairly straightforward using the DWIConvert module of Slicer. You can use the two examples below to convert DICOM files or NIFTI files over to NRRD format.
If converting from NIFTI format, one REALLY important thing to remember is that DWIConvert expects your b-value and b-vector files to be in column format, instead of the row format output by dcm2nii! So you will want to use a tool like 1dtranspose in AFNI to flip the files before you run the conversion. Failure to do so will result in the NRRD file representing the gradient files incorrectly, which will probably cause bad things to happen when you later analyze your data!
Convert data to NRRD from DICOM
DWIConvert \ -i ep2d_DTI_32dirs_4B0_AP_22 \ -o dwi.nrrd \ --conversionMode DicomToNrrd
Convert data to NRRD from NIFTI
DWIConvert \ --inputVolume ep2dDTI.nii.gz \ -o dwi.nrrd \ --conversionMode FSLToNrrd \ --inputBVectors ep2dDTI.bvec \ --inputBValues ep2dDTI.bval
Using DTIprep
Now that data is converted to NRRD format, open DTIprep and click the icon in the upper left corner (labeled “Open NRRD”). You will immediately see information about your diffusion data (pictured below). When converting from DICOM I’ve noticed some differences between DWIConvert and both TORTOISE and dcm2nii/Mricron. If this bothers you (and that’s perfectly valid) you can convert the NIFTI files from dcm2nii using the second approach above! I’ve submitted a bug report to the folks making DWIConvert (March 23, 2015).
Once you have verified that the data loaded as NRRD is correct (correct gradient directions and b-values), you can setup your QA protocol. Click on the second tab titled “Protocol” and you will notice that everything is currently empty. Click “Default” to load up a boilerplate protocol with your imaging parameters, which will generate the list below.
You can modify this protocol by expanding any of the dropdown lists or changing any of the “No” options to a “Yes”. If you do this you may need to point the software to the appropriate module within Slicer. On my Mac install of Slicer, the modules are located within the application package (Slicer.app/Contents/lib/Slicer-4.4/cli-modules), whereas on Linux they are conveniently located in the “Plug-in” folder. Once you have setup everything, click the “RunByProtocol” button and proceed to wait for a bit. On my Macbook Pro it only takes about 15 minutes to run the default protocol on 36 directions of 2mm^3 data (compared to almost an hour for TORTOISE).
If you just wish to use the default parameters and automate DTIprep from the command line, you can use the DTIPrepExec program within the Mac Application Bundle (or just call DTIprep if you’re running linux). The odd part here is that you have to give it the name of an xmlProtocol even though it’s going to create it using the defaults. You can also tell it how many processors to use. Should you wish to modify the XML file, leave out the –check option and then grep, sed, and awk to change the defaults to how you see fit.
DTIPrep.app/Contents/MacOS/DTIPrepExec \ --default \ --check \ --xmlProtocol SomeProto.xml \ --numberOfThreads 8 \ --DWINrrdFile dwi.nrrd
DTIprep Results
DTIprep will spit out a number of output files, these are usually named using some portion of your input NRRD file. So if my input was dwi.nrrd, then the output files are:
- dwi_QCed.nrrd – the data file after preprocessing (with bad directions removed)
- dwi_QCReport.txt – a text file detailing the QC procedure and results, look to the end for a summary
- dwi_XMLQCResults.xml – an XML file detailing the QC results
If you want to use DTIprep as a quick Quality Control check of your DTI data, you can just spit out the last few lines of the QCReport:
tail -3 dwi_QCReport.txt
Or if you want to use grep:
cat dwi_QCReport.txt | grep PASS cat dwi_QCReport.txt | grep FAIL
Where to go from here?
Now that you’ve run your data through DTIprep, you can convert it back to NIFTI format for use with various tractography programs, including those in AFNI (Part 3).
Convert data back to NIFTI from NRRD
DWIConvert \ --inputVolume dwi_QCed.nrrd \ --outputVolume dwi_QCed.nii.gz \ --outputBVectors dwi_QCed.bvec \ --outputBValues dwi_QCed.bval \ --conversionMode NrrdToFSL
Alternatively, you can make use of various other DTI fitting softwares out there! DTIprep even includes it’s own, and I’ll try to cover those in a future post.