mwiexamples

This repository contains examples demonstrating usage of the DEcomposition and Component Analysis of Exponential Signals (DECAES) tool, a fast implementation of the MATLAB toolbox from the UBC MRI Research Centre written in the open-source Julia programming language. The source code for DECAES can be found at the DECAES.jl package repository. For an introduction to Julia, see the Julia documentation.

DECAES provides methods for performing fast multiexponential analysis tailored to magnetic resonance imaging (MRI) applications. Voxelwise T2-distributions of multi spin-echo MRI images are computed by projecting measured MR signals onto basis signals using regularized nonnegative least-squares (NNLS); basis signals are computed using the extended phase graph (EPG) algorithm with additional stimulated echo correction. Post-processing these T2-distributions allows for computating measures such as the myelin water fraction (MWF) used in myelin water imaging (MWI) and the luminal water fraction (LWF) used in luminal water imaging (LWI).

Documentation

In-depth documentation for DECAES can be found at the above link with information such as:

Command line interface API details
Julia API reference for using DECAES from within Julia
DECAES internals and algorithmic details

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

Benchmarks

Due to performance optimizations enabled by Julia, DECAES is fast. As an illustration, here is a comparison between DECAES and UBC MWF MATLAB toolbox T2-distribution computation times for two multi spin-echo (MSE) datasets:

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

Tutorial

Quickstart

Command Line Interface

DECAES provides a command line interface (CLI) for performing exponential analysis of multi spin-echo images. Input image files must be stored as NIfTI files (extension .nii or .nii.gz), MATLAB files (extension .mat), Philips PAR/REC file pairs (extensions .par/.rec or .PAR/.REC), or Philips XML/REC file pairs (extensions .xml/.rec or .XML/.REC). If your data is in DICOM format, the freely available dcm2niix tool is able to convert both DICOM files into NIfTI format.

The interface for processing an image file is as follows:

$ julia --threads=auto -e 'using DECAES; main()' -- image.nii <COMMAND LINE ARGS>

Multithreaded parallel processing is enabled by setting the julia command line flag --threads=auto. The file image.nii is the image to be processed, and the Julia code 'using DECAES; main()' loads DECAES and the CLI entrypoint function. Command line arguments are introduced below, and detailed in the documentation.

Alternatively, a Julia script decaes.jl is provided by this respository for convenience. This script will load DECAES (installing it if necessary) and the CLI for you, and can be used as:

$ julia --threads=auto decaes.jl -- image.nii <COMMAND LINE ARGS>

All outputs are saved as .mat files; see the documentation for more information.

MATLAB Interface

The DECAES CLI can be called from within MATLAB using the function decaes.m provided by this repository. The below example processes image.nii using multiple threads (note that the MATLAB interface starts Julia multithreaded by default for convenience; see the decaes.m function documentation for details):

>> decaes('image.nii', <COMMAND LINE ARGS>...) % function syntax
>> decaes image.nii <COMMAND LINE ARGS> % or equivalently, command syntax

NOTE: The examples in this README using the CLI are easily translated to MATLAB: simply replace command line statements such as julia --threads=auto decaes.jl <COMMAND LINE ARGS> with the equivalent MATLAB command decaes <COMMAND LINE ARGS>

Installation

(Optional) cloning this repository

Cloning this repository is not necessary to use DECAES. However, this repository provides the following items which may prove useful to new users of the package:

Example MWI data, brain masks, and a corresponding examples.sh script illustrating how to process the example data
The decaes.jl convenience script for installing DECAES and calling the DECAES CLI
The decaes.m MATLAB function for installing DECAES and calling DECAES from MATLAB
The decaes.py Python module for calling the DECAES Julia API from Python

There are two ways to clone this repository:

Clone mwiexamples using git from the command line by executing the following command in the terminal:
```
$ git clone https://github.com/jondeuce/mwiexamples.git
```
Click the Code -> Download ZIP in the top right of this page to download a .zip file of the repository contents

Downloading Julia

To use DECAES, Julia version 1.9.0 or higher is required. We recommend installing Julia via the juliaup cross-platform Julia installer. Please see the juliaup installation instructions for details.

Installing DECAES

There are two ways to install DECAES:

Use the example script decaes.jl, MATLAB function decaes.m, or Python module decaes.py provided by this repository; DECAES will automatically be installed (if necessary) when used through these interfaces
Start julia from the command line, type ] to enter the package manager REPL mode (the julia> prompt will be replaced by a pkg> prompt), and enter the following command:
```
pkg> add DECAES
```
Once the package is finished installing, type the backspace key to exit the package manager REPL mode (the julia> prompt should reappear). Exit Julia using the keyboard shortcut Ctrl+D, or by typing exit().

NOTE: Julia is a "just-ahead-of-time" compiled language, residing in between ahead-of-time (AOT) and just-in-time (JIT) compiled languages. Because of this, the first time DECAES is installed and run there may be several minutes of installation and compilation delay before processing starts. Subsequent runs will be much faster; typically, 5-10 seconds are needed to start Julia and load DECAES before processing begins.

Updating DECAES

DECAES is implemented as a Julia package, hosted at the DECAES.jl repository, allowing DECAES to be updated through the Julia package manager. To update DECAES, start julia from the command line, type ] to enter the package manager REPL mode, and enter the following:

pkg> update DECAES

Or equivalently, enter the following command at the terminal:

$ julia -e 'import Pkg; Pkg.update("DECAES")'

Command Line Interface (CLI)

The DECAES CLI aims to give users the ability to compute e.g. myelin water fraction maps from the command line and afterwards continue using the programming language of their choice. As such, using the CLI does not require any knowledge of Julia, only the installation steps above need to be completed. Indeed, as mentioned in the Quickstart section, one may call the CLI directly from within MATLAB using the decaes.m file provided by this repository.

DECAES takes images stored as NIfTI, MATLAB, PAR/REC, or XML/REC files as input 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 myelin water fraction. Data must be stored as (x, y, z, echo) for multi-echo input data, or (x, y, z, T2 bin) for T2-distribution input data. See the documentation for more API details.

The examples to follow should be run from within the mwiexamples folder.

Required parameters

Several parameters are required to perform myelin or luminal water imaging. We have chosen to make the most important parameters required arguments. They should be carefully chosen, and most importantly, used consistently when comparing results.

The matrix size and number of echoes MatrixSize and nTE; these are inferred from the size of the input image
The echo time TE (units: seconds). Must correspond to scanning protocol
The number of T2 bins nT2. Typically, nT2 = 40 will be a good default, but note that increasing nT2 or otherwise decreasing the spacing between T2 values (such as by decreasing the width of T2Range) may require more regularization
The range of T2 values T2Range (units: seconds). The lower bound should be on the order of TE, as T2 components much smaller than TE are not well captured by the MSE signal. Similarly, the upper bound of the T2Range typically should not be much higher than a small multiple of the last sampled echo time nTE * TE, as arbitrarily high T2 values cannot be recovered
The small and middle peak windows SPWin and MPWin (units: seconds):
- For myelin water imaging, the myelin vs. intra/extra-cellular water cutoff should be chosen based on the T2 distribution. For example, plotting the mean T2 distribution over white matter voxels should reveal two distinct peaks from which a cutoff value can be chosen. Typical values may be SPWin = [TE, 25e-3] and MPWin = [25e-3, 200e-3], where SPWin controls the myelin water window
- Similar methods should be used for luminal water imaging. In LWI, MPWin controls the luminal water window. Typical values may be SPWin = [TE, 200e-3] and MPWin = [200e-3, T2Range(2)], where T2Range(2) is the upper bound of T2Range
The regularization method Reg. DECAES provides three methods to automatically determine the regularization constant mu used in the Tikhonov regularization term:
- "lcurve": choose mu by locating the point of maximum curvature on the L-curve; this method is parameter-free
- "gcv": choose mu using the generalized cross-validation (GCV) method; this method is parameter-free
- "chi2": choose mu such that the regularized solution increases the chi-squared goodness of fit by a specified ratio relative to the unregularized solution. This method requires an additional parameter Chi2Factor, typically equal to 1.01 or 1.02, controlling the relative increase in chi-squared. See the documentation

Basic usage

The most straightforward usage is to call julia on the decaes.jl script provided by this repository, passing the input image filename and analysis settings as command line arguments:

$ julia --threads=auto decaes.jl -- data/images/image-194x110x1x56.nii.gz \
  --T2map --T2part --TE 7e-3 --nT2 40 \
  --T2Range 7e-3 2.0 --SPWin 7e-3 25e-3 --MPWin 25e-3 200e-3 --Reg lcurve \
  --output output/basic/

The 4D image file data/images/image-194x110x1x56.nii.gz is passed as the first argument
The flags --T2map and --T2part are passed, indicating that both T2-distribution computation and T2-parts analysis (to compute e.g. the myelin water fraction) will be performed
The flag --TE is passed with argument 7e-3, setting the echo times to 7 ms, 14 ms, ...
The flag --nT2 is passed with argument 40, setting the number of T2 components to 40
The flag --T2Range is passed with argument 7e-3 2.0 to set the range of T2 values for the T2-distribution; the --SPWin and --MPWin flags similarly set the short peak and middle peak windows
The flag --Reg is passed with argument lcurve, specifying that the L-curve regularization method will be used
The flag --output is passed with argument output/basic/. The folder output/basic/ will be created if it does not already exist, and the T2-distribution and T2-parts results will be stored there as .mat files.

See the arguments section of the documentation for more information on command line arguments.

Passing image masks

Image masks can be passed in for processing. We can process the image file data/images/image-194x110x8x56.nii.gz using the brain mask data/masks/image-194x110x8x56_mask.nii.gz as follows:

$ julia --threads=auto decaes.jl -- data/images/image-194x110x8x56.nii.gz \
  --T2map --T2part --TE 7e-3 --nT2 40 \
  --T2Range 7e-3 2.0 --SPWin 7e-3 25e-3 --MPWin 25e-3 200e-3 --Reg gcv \
  --mask data/masks/image-194x110x8x56_mask.nii.gz \
  --output output/masked/

These results will be stored in the folder output/masked/.

Processing multiple files

Multiple files can be passed in for processing. Here, we process both images from the above examples, this time using brain masks for both images:

$ julia --threads=auto decaes.jl -- \
  data/images/image-194x110x1x56.nii.gz \
  data/images/image-194x110x8x56.nii.gz \
  --T2map --T2part --TE 7e-3 --nT2 40 \
  --T2Range 7e-3 2.0 --SPWin 7e-3 25e-3 --MPWin 25e-3 200e-3 --Reg chi2 --Chi2Factor 1.02 \
  --mask \
  data/masks/image-194x110x1x56_mask.nii.gz \
  data/masks/image-194x110x8x56_mask.nii.gz \
  --output output/multiple/

Passing parameters from a settings file

Flags and parameters can be passed in from settings file by prepending the @ character to the path of the settings file. Using the settings files in the data/ folder, we can re-run the above examples as follows:

$ julia --threads=auto decaes.jl -- @data/example1.txt
$ julia --threads=auto decaes.jl -- @data/example2.txt
$ julia --threads=auto decaes.jl -- @data/example3.txt

These results will be stored in the folders output/example1/, output/example2/, and output/example3/, as specified by the settings files.

The use of settings files is highly recommended for reproducibility and self-documentation, as a copy of the input settings file will be automatically saved in the output folder. For more information on creating settings files, see the documentation.

Example scripts

The scripts examples.sh and examples.m provided by this repository demonstrate the three example invocations of DECAES above. The only requirement for these scripts to run is that the julia executable is on your system path and that DECAES is installed. The scripts can also be easily modified to replace julia with /path/to/julia on your system, if necessary.

Running ./examples.sh in the terminal or examples in MATLAB will execute the respective scripts. Results will be stored in a directory output/.

jondeuce / mwiexamples