DECAES.jl

DEcomposition and Component Analysis of Exponential Signals (DECAES) - a Julia implementation of the UBC Myelin Water Imaging (MWI) toolbox for computing voxelwise T2-distributions of multi spin-echo MRI images.
Author jondeuce
Popularity
22 Stars
Updated Last
10 Months Ago
Started In
January 2020

DEcomposition and Component Analysis of Exponential Signals (DECAES)

Dev Build Status codecov.io

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

Dev

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.

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

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

DECAES Tutorial 2022

DECAES.jl Software Tutorial: Myelin and Luminal Water Imaging in under 1 Minute

JuliaCon 2021

JuliaCon 2021 - Matlab to Julia: Hours to Minutes for MRI Image Analysis

Citing this work

Z Med Phys

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