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
  • 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

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)?
  • 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, and qoffset_z.

Attribution

If you use DIRAC in your work, please cite the following publication: