DIRAC: Diffusion Imaging Reconstruction and Analysis Collection
Overview
DIRAC is a suite of software tools for processing and analyzing diffusion-weighted MRI (DWI) data sets. The current release, DIRAC v2.2, is comprised of the following programs:
- dirac-synthesizer
- dirac-datapacker
- dirac-denoiser
- dirac-tensorcalculator
- dirac-odfcalculator
- dirac-tensormetrics
- dirac-odfmetrics
- dirac-fasttract
- dirac-preprocessor
Getting DIRAC
- General Public
- DIRAC is available as a set of modules on the LONI Pipeline
- DIRAC is available as a set of modules on the LONI Pipeline
- LONI Members
- Access the binaries on Cranium at
/usr/local/loniApps/vpatel/bin
- Build from the source archive at
/ifs/ccb/vpatel/dist/dirac.tar.gz
- Access the binaries on Cranium at
Documentation
Relevant excerpts from the README
:
A. General Guidelines The following points apply across the entire DIRAC package. - Everything is NIfTI [http://nifti.nimh.nih.gov/]. All input and output volumes consumed and produced by DIRAC tools are monolithic NIfTI files. Metadata for DWI data sets, diffusion tensor volumes, and ODF volumes is stored according to the MiND specification [http://mind.loni.usc.edu/]. Volumes may be in uncompressed (*.nii) or gzip compressed (*.nii.gz) form. Both NIfTI-1.1 and NIfTI-2.0 formats are supported. - Since 0 (zero) is valid data in many DWI post-processing operations, the DIRAC tools rely on the value NaN (not a number) to mask voxels outside the brain to be excluded from processing. B. dirac-synthesizer The dirac-synthesizer program generates a simulated DWI data set that can be used as a digital phantom for evaluating fiber orientation reconstruction or tractography methods. dirac-synthesizer [-i <input>] [-o <output>] -i, --input (optional, default: read from standard input) A plain text simulation parameter file formatted as in the following example: b=3000 snr=10 g=1,1,1 g=1,1,0 f=1,0,0|1.0|8.5|1,1,1 f=1,1,0|0.3|4.0|1,1,1 f=1,1,0|0.7|8.5|1,1,-1 This example specifies that the simulated data set be generated with a b-value of 3000 mm/s^2 and a signal-to-noise ratio of 10. The diffusion-weighting gradient directions to sample are (1,1,1) and (1,1,0). Additionally, 3 fibers are to be simulated. The first fiber is in voxel (1,0,0) and contributes 100% of the signal there, and the ideal tensor should have a primary eigenvalue 8.5 times as large as the secondary eigenvalue (which is equal to the tertiary eigenvalue), with the primary eigenvector pointing in the (1,1,1) direction. The second fiber is in voxel (1,1,0) and accounts for 30% of the signal there, with a primary eigenvalue 4 times larger than the secondary, with a tensor oriented along the (1,1,1) direction. The third fiber is also in voxel (1,1,0) and accounts for 70% of the signal there, with a primary:secondary eigenvalue ratio of 8.5, and a primary eigenvector pointing towards (1,1,-1). Any number of gradient directions and fibers can be specified as shown, but the b-value and SNR must be defined once and only once. The ordering of the lines in the input file is not significant. -o, --output (optional, default: write to standard output) The filename at which to write the NIfTI volume containing the simulated diffusion-weighted data set and the associated metadata, stored according to the MiND standard. C. dirac-datapacker The dirac-datapacker program combines the individual volumes from a diffusion-weighted study and their diffusion-weighting b-values and gradient directions into a single NIfTI file according to the MiND standard for diffusion-weighted imaging. dirac-datapacker [-i <input>] [-m <mask>] [-o <output>] -i, --input (optional, default: read from standard input) A comma separated values (CSV) file describing the characteristics of each individual DWI per line as in the following example: 0,NaN;NaN;NaN,/home/user/data/dwi0.nii 1000,1;0;1,/home/user/data/dwi1.nii 1200,-1;-1;1,/home/user/data/dwi2.nii This example indicates that the image at /home/user/data/dwi0.nii was acquired without diffusion weighting, that the DWI at dwi1.nii was acquired with a b-value of 1000 mm/s^2, weighted in the (1,0,1) direction, and that the DWI at dwi2.nii was acquired with a b-value of 1200 mm/s^2, weighted in the (-1,-1,1) direction. Include as many lines as needed to specify the entire DWI data set. Optionally, the first line of the file may contain column headings, (for example, "b-value,gradient-direction,file-path"), but these labels are ignored and cannot be used to rearrange the order of columns in the file. Ideally, the images should have been corrected for subject motion and eddy current distortions. The spatial transformations produced by these and any other registration operations should be taken into account when specifying the diffusion-weighting gradient directions. -m, --mask (optional, default: none) A NIfTI volume with nonzero voxels marking regions of the image that lie within the brain. Providing this skull stripping mask is highly recommended to accelerate and improve the accuracy of downstream processing. -o, --output (optional, default: write to standard output) The filename at which to write the NIfTI volume containing the complete diffusion-weighted data set and the associated metadata, stored according to the MiND standard. D. dirac-denoiser The dirac-denoiser program reduces the noise in a diffusion-weighted data set using the K-SVD method. dirac-denoiser [-i <input>] [-d <dictionary-size>] [-s <sparsity>] [-r <rounds>] [-n <noise-level>] [-t <training-size>] [-o <output>] -i, --input (optional, default: read from standard input) A NIfTI volume containing the complete noisy diffusion-weighted data set and the associated metadata, stored according to the MiND standard. -d, --dictionary-size (optional, default: 200) The number of atoms in each K-SVD dictionary. -s, --sparsity (optional, default: 10) The sparsity threshold for K-SVD signal encoding. -r, --rounds (optional, default: 2) The number of rounds of K-SVD denoising to perform. Higher values improve the reproducibility of denoising results at the expense of processing time. -n, --noise-level (optional, default: 10.0) The estimated signal-to-noise ratio for the input DWIs. -t, --training-size (optional, default: 2000) The number of voxels to sample when training the K-SVD dictionaries. -o, --output (optional, default: write to standard output) The filename at which to write the NIfTI volume containing the complete denoised diffusion-weighted data set and the associated metadata, stored according to the MiND standard. E. dirac-tensorcalculator The dirac-tensorcalculator program computes the second-order, symmetric, positive definite diffusion tensors for a diffusion-weighted data set. dirac-tensorcalculator [-i <input>] [-o <output>] -i, --input (optional, default: read from standard input) A NIfTI volume containing a complete diffusion-weighted data set and the associated metadata, stored according to the MiND standard. -o, --output (optional, default: write to standard output) The filename at which to write the NIfTI volume containing the diffusion tensor components, stored according to the MiND standard. F. dirac-odfcalculator The dirac-odfcalculator program computes spherical harmonic coefficients to represent the orientation distribution functions (ODFs) for a diffusion-weighted data set. dirac-odfcalculator [-i <input>] [-d <degree>] [-o <output>] -i, --input (optional, default: read from standard input) A NIfTI volume containing a complete diffusion-weighted data set and the associated metadata, stored according to the MiND standard. -d, --degree (optional, default: maximum possible degree) The maximum degree spherical harmonic function to fit. This should be a nonnegative even number less than or equal to -1.5*sqrt(2*n+0.25), where n is the number of diffusion-weighted images in the input data set. -o, --output (optional, default: write to standard output) The filename at which to write the NIfTI volume containing the ODF spherical harmonic coefficients, stored according to the MiND standard. G. dirac-tensormetrics The dirac-tensormetrics program computes various measures from the second-order, symmetric, positive-definite diffusion tensor reconstruction. dirac-tensormetrics [-i <input>] -m <metric> [-o <output>] -i, --input (optional, default: read from standard input) A NIfTI volume containing the diffusion tensor components, stored according to the MiND standard. -m, --metric (required) One of the following codes that specify the metric to calculate: * MD = mean diffusivity * FA = fractional anisotropy * SRA = scaled relative anisotropy * VF = volume fraction * LIN = lattice index * CA = Westin's anisotropy measure * CL = Westin's linear measure * CP = Westin's planar measure * CS = Westin's spherical measure * DEC = directionally-encoded color * DECFA = DEC scaled by FA * SI = secondary eigenvector index * GA = geodesic anisotropy * TGA = hyperbolic tangent transform of GA * XX = Dxx tensor component * YY = Dyy tensor component * ZZ = Dzz tensor component * XY = Dxy tensor component * YZ = Dyz tensor component * XZ = Dxz tensor component -o, --output (optional, default: write to standard output) The filename at which to write the NIfTI volume containing the map of the specified tensor-derived measure. H. dirac-odfmetrics The dirac-odfmetrics program computes various measures from the orientation distribution function and compares ODFs between volumes. dirac-odfmetrics [-i <input>] -m <metric> [-r <reference>] [-o <output>] -i, --input (optional, default: read from standard input) A NIfTI volume containing ODF data (specified either as spherical harmonic coefficients or as discrete spherical functions), stored according to the MiND standard. -m, --metric (required) One of the following codes that specify the metric to calculate: * GFA = generalized fractional anisotropy * SKEW = skewness * KURT = kurtosis * KURTGFA = KURT normalized by GFA * DEC = directionally-encoded color * DECGFA = DEC scaled by GFA * SKL = symmetrized Kullback-Leibler divergence * JSD = Jensen-Shannon divergence * FR = Fisher-Rao distance -r, --reference (optional, default: none) For distance metrics, a second NIfTI volume containing ODF data, stored according to the MiND standard. -o, --output (optional, default: write to standard output) The filename at which to write the NIfTI volume containing the map of the specified ODF measure. I. dirac-fasttract The dirac-fasttract program performs fast marching tractography through a volume of diffusion tensors or ODFs from a given seed region to produce a connectivity index map. dirac-fasttract [-i <input>] -s <seed> [-t <trajectories>] [-o <output>] -i, --input (optional, default: read from standard input) A NIfTI volume containing diffusion tensor or ODF data (specified either as spherical harmonic coefficients or as discrete spherical functions), stored according to the MiND standard. -s, --seed (required) A NIfTI volume with nonzero voxels marking regions of the image from which to initialize fast marching tractography. -t, --trajectories (optional, default: none) The filename at which to write the NIfTI volume containing the ranked fast marching trajectories for visualization with DIVA. -o, --output (optional, default: write to standard output) The filename at which to write the NIfTI volume containing the connectivity index map. J. dirac-preprocessor The dirac-preprocessor.sh wrapper script is a utility for importing NIfTI DWI volumes for analysis with DIRAC. dirac-preprocessor.sh -b <bval> -g <gdir> -f <file> [-b <bval> -g <gdir> -f <file> ...] [-c] [-r <target>] [-s <mask>] -m <meta> -b (required, once for each volume) The diffusion-weighting b-value in units of s/mm^2. -g (required, once for each volume) The diffusion-weighting gradient direction vector in the form x;y;z. -f (required, once for each volume) Absolute path to the DWI volume (NIfTI) to be imported. -c (optional flag) Correct imported data for motion and eddy current distortions. -r (optional, default: none) The target volume (NIfTI) to which the imported data should be registered. -s (optional, default: none) The filename at which to write a binary mask (NIfTI) produced by skullstripping the imported data. -m (required) Output CSV metadata in the form required by dirac-datapacker.
Frequently Asked Questions
- What causes the error
ambiguous data orientation (qform_code <= 0)
?- The NIfTI header provides a method for explicitly specifying data orientation using a quaternion. Omitting this information (by not specifying a valid
qform_code
), is an error in DIRAC because the data orientation is of critical importance in most DW-MRI processing operations.
- The NIfTI header provides a method for explicitly specifying data orientation using a quaternion. Omitting this information (by not specifying a valid
- What causes the error
volume dimension mismatch
?- DIRAC programs that operate on multiple volumes simultaneously (dirac-datapacker, dirac-odfmetrics, dirac-facttract) require all volumes to have the same x, y, and z dimensions.
- What causes the error
voxel dimension mismatch
?- DIRAC programs that operate on multiple volumes simultaneously (dirac-datapacker, dirac-odfmetrics, dirac-facttract) require all volumes to have the same voxel sizes.
- What causes the error
data orientation (qform) mismatch
?- DIRAC programs that operate on multiple volumes simultaneously (dirac-datapacker, dirac-odfmetrics, dirac-facttract) require all volumes to be in the same orientation. The following fields from their NIfTI headers must match:
qform_code
,pixdim[0]
(qfac
),quatern_b
,quatern_c
,quatern_d
,qoffset_x
,qoffset_y
, andqoffset_z
.
- DIRAC programs that operate on multiple volumes simultaneously (dirac-datapacker, dirac-odfmetrics, dirac-facttract) require all volumes to be in the same orientation. The following fields from their NIfTI headers must match:
Attribution
If you use DIRAC in your work, please cite the following publication: