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.
In Julia v1.6 or later you can install DECAES from the Pkg REPL:
pkg> add DECAES
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
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.
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:
- NIfTI file with extension
.nii
, or gzip compressed NIfTI file with extension.nii.gz
- MATLAB file with extension
.mat
- Philips PAR/REC file pair with extensions
.par
and.rec
(or.PAR
and.REC
) - 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.
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
Dataset | Matrix Size | CPU | Cores | MATLAB | DECAES |
---|---|---|---|---|---|
48-echo MSE | 240 x 240 x 48 | Intel i5 4200U | 2 | 4h:35m:18s | 7m:49s |
56-echo MSE | 240 x 240 x 113 | Xeon E5-2640 (x2) | 12 | 1h:25m:01s | 2m:39s |
48-echo MSE | 240 x 240 x 48 | Xeon E5-2640 (x2) | 12 | 59m:40s | 1m:40s |
56-echo MSE | 240 x 240 x 113 | Ryzen 9 3950X | 16 | 22m:33s | 43s |
48-echo MSE | 240 x 240 x 48 | Ryzen 9 3950X | 16 | 17m:56s | 27s |
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
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}
}