DEcomposition and Component Analysis of Exponential Signals (DECAES)

DECAES is a fast Julia implementation of the MATLAB toolbox from the UBC MRI Research Centre for computing voxelwise T2-distributions from multi spin-echo MRI images using the extended phase graph algorithm with stimulated echo corrections. Post-processing of these T2-distributions allows for the computation of measures such as the myelin water fraction (MWF) or the luminal water fraction (LWF).

DECAES is written in the open-source Julia programming language. Julia and command line interfaces are available through this package. The examples repository additionally provides a MATLAB interface via the MATLAB function decaes.m, as well as a Python interface via the decaes.py module. If you use DECAES in your research, please cite our work.

Installation

In Julia v1.6 or later you can install DECAES from the Pkg REPL:

pkg> add DECAES

Documentation

Find package documentation at the above link, which includes:

• The command line interface API, available command line arguments, and examples
• API reference detailing how to use DECAES.jl from within Julia
• Other internals and algorithmic details

DECAES tutorial

If you are new to DECAES, the best place to start is the examples repository. There, we provide a walk-through tutorial for using the MATLAB and command-line interfaces for DECAES, including example multi spin-echo (MSE) data for performing MWI.

Command Line Interface

This toolbox provides a command line interface (CLI) for processing from the terminal. The CLI takes image files as inputs and performs one or both of T2-distribution computation and T2-parts analysis, the latter of which performs post-processing of the T2-distribution to calculate parameters such as the MWF or LWF. The input image must be one of the following file types:

1. NIfTI file with extension .nii, or gzip compressed NIfTI file with extension .nii.gz
2. MATLAB file with extension .mat
3. Philips PAR/REC file pair with extensions .par and .rec (or .PAR and .REC)
4. Philips XML/REC file pair with extensions .xml and .rec (or .XML and .REC)

All output files are saved as .mat files in format v7.3.

• Note: if your data is in DICOM format, the freely available dcm2niix tool is able to convert DICOM files into NIfTI format.

Basic usage

There are two equivalent ways to use the CLI, assuming DECAES is already installed:

1. Helper script: Create a script called e.g. decaes.jl with the following contents (or, download the script located here):

using DECAES # load the package
main() # call CLI entrypoint function

This script can then be invoked from the command line as follows:

$ julia --threads=auto decaes.jl -- <COMMAND LINE ARGS> # --threads=auto enables parallel processing

2. Julia -e flag: The contents of the above script can be written directly at the command line using the -e (for "evaluate") flag:

$ julia --threads=auto -e 'using DECAES; main()' -- <COMMAND LINE ARGS> # --threads=auto enables parallel processing

Benchmarks

Benchmarking notes:

• MATLAB scripts used were from the MWI_NNLS_toolbox_0319 subfolder of the ubcmwf github repository
• DECAES.jl was compiled into an app using the --compile flag to reduce compile time overhead
• Both implementations made use of precomputed brain masks to skip voxels outside of the brain

DECAES Tutorial 2022

JuliaCon 2021

Citing this work

If you use DECAES in your research, please cite the following:

@article{DECAES.jl-2020,
  title = {{{DECAES}} - {{DEcomposition}} and {{Component Analysis}} of {{Exponential Signals}}},
  author = {Doucette, Jonathan and Kames, Christian and Rauscher, Alexander},
  year = {2020},
  month = may,
  issn = {1876-4436},
  doi = {10.1016/j.zemedi.2020.04.001},
  journal = {Zeitschrift Fur Medizinische Physik},
  keywords = {Brain,Luminal Water Imaging,MRI,Myelin Water Imaging,Prostate},
  language = {eng},
  pmid = {32451148}
}