BDP: Technical Details

Data Requirements

BrainSuite Diffusion Pipeline (BDP) assumes the following about input diffusion datasets:

• For registration based distortion correction to work correctly, the diffusion data should be scanned with single-shot Echo Planar Imaging sequence.
• Distortion in diffusion images aligns with the imaging matrix used during the acquisition. Thus, before running distortion correction, the diffusion data should not be re-sampled or interpolated in a way that can cause distortion to no longer be aligned with the imaging matrix. Preprocessing steps such as de-noising can be performed if it does not violate this assumption.
• If intensity correction is used for registration-based distortion correction (the default behavior), it can change the noise distribution in the corrected diffusion image (spatially across the image). This does not affect ODF or tensor estimation nor any derived parameters like Fractional Anisotropy (FA).
• For fieldmap-based distortion correction, the fieldmap should be scanned with the same shim settings as the diffusion data and during the same session as the diffusion MRI. Further, the fieldmap should be unwrapped and saved in units of radians/second.
• ODF estimation assumes that all diffusion weighted images were collected with roughly the same b-values. The results will not be accurate if b-values differ significantly (e.g. as found with DSI datasets).
• Diffusion tensor estimation should work for most acquisitions with at-least seven (7) distinct diffusion encodings.
• The .bmat, .bvec or .bval file should contain zero matrices corresponding to b=0 diffusion images. b=0 images are required for co-registration with T1-weighted image. When no b=0 image is found, BDP will try to use diffusion weighted images with minimum b-value in place of b=0 image. This is done only when the ratio of the maximum and minimum b-value is more than a specified threshold. See --bval-ratio-threshold in flags page for more details.
• While using NIfTI files as input, .bvec or .bmat files should describe diffusion encoding direction in voxel coordinate of the diffusion data (i.e. in the same frame of reference as the image data). Further, the order of entries of gradient direction in the specified .bvec or .bmat file must match the order of volumes in the input 4-D NIfTI data.

System Requirements

1. BDP requires write permission to the current working directory (the directory from which the BDP commands were called/started) and the operating system’s temporary directory. Although not required, it may be a good idea to first change the current working directory to the directory where you want to write the outputs (e.g. the subject directory).
2. BDP may create multiple temporary directories in the operating system’s temporary directory to save some temporary files. These directories should not be deleted while BDP is running and are automatically deleted by BDP after the processing. If BDP is interrupted (by the user or the system) before it finishes processing, these temporary directories may not be automatically deleted and may need to be deleted manually.
3. BDP requires about 6 GB of physical memory to run successfully. Because of this, BDP tries to detect the available memory during runtime and shows a warning if not enough memory is found. However, BDP can be still used on a low memory system in following situations:
   • When enough virtual memory (or swap space) is available to the system, such that total memory (physical + virtual memory) is more than 6GB. This may slow down the computer and take longer than usual to run. If you are using Mac OS X, the system will increase your virtual memory as needed (provided you have enough hard drive space for it). Windows and Linux also automatically manage virtual memory, but if you find that you need to increase the amount the system uses, please check the following links (or search for documentation for your particular system): Windows Linux
   • When fieldmap-based distortion correction is used instead of registration-based correction (See coregister_diffusion_mprage_pipeline). This requires a fieldmap (collected in the same session as the diffusion MRI) and echo-spacing as input flags (as explained here under “Optional Flags”).
   • When BDP is run with the flag --low-memory. This will likely reduce the accuracy of distortion correction (See coregister_diffusion_mprage_pipeline)

DICOM to NIfTI Conversion

When DICOM format is used as input, it must first be converted to a a 4-D NIfTI-1 file before further processing. DICOM files usually contain both the diffusion weighted images (DWIs) and the scan parameters of the diffusion sequence. You can use a program such as dcm2nii.

Known Issues

• It is possible to get BDP outputs to work in non-BrainSuite software packages. However it might require some sophistication and effort from the user if the other software package does not follow standard NIfTI format conventions.