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

Refer to the DECAES documentation for in-depth descriptions of the command line interface, a Julia API reference for using DECAES from within Julia, and DECAES internals and algorithmic details.

If you use DECAES in your research, please cite our work:

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

Quickstart

Example usage of the DECAES command line interface (CLI) to process two example multi spin-echo images provided in the data/ folder of this repository. See the tutorial below for detailed descriptions of the CLI arguments.

$ julia --project=@decaes -e 'import Pkg; Pkg.add("DECAES"); Pkg.build("DECAES")' # build DECAES CLI

$ decaes \ # run CLI launcher script stored in ~/.julia/bin
> data/images/image-194x110x1x56.nii.gz \ # multi spin-echo images to process
> data/images/image-194x110x8x56.nii.gz \
> --mask \
> data/masks/image-194x110x1x56_mask.nii.gz \ # brain masks corresponding to input images
> data/masks/image-194x110x8x56_mask.nii.gz \
> --output output/quickstart/ \ # output directory
> --T2map \ # compute T2 distribution and derived quantities, e.g. geometric mean T2
> --T2part \ # compute T2-parts from T2 distribution, e.g. myelin water fraction
> --TE 7e-3 \ # uniform echo spacing (seconds)
> --nT2 40 \ # number of T2 components
> --T2Range 7e-3 2.0 \ # range of logarithmically-spaced T2 components (seconds)
> --SPWin 7e-3 25e-3 \ # small peak window/short T2 range
> --MPWin 25e-3 200e-3 \ # middle peak window/long T2 range
> --Reg lcurve # regularization method (L-curve recommended)

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.m MATLAB function for installing DECAES and calling DECAES from MATLAB

Clone this repository using git clone https://github.com/jondeuce/mwiexamples.git from the command line, or by clicking Code -> Download ZIP in the top right of this page.

Downloading Julia

To use DECAES, Julia version 1.9 or higher is required. We recommend always installing the latest version of Julia via the juliaup official cross-platform Julia installer. Please refer to the Julia downloads page for installation instructions.

Installing DECAES (Command Line Interface)

Using Julia v1.9 or later you can install DECAES as follows:

$ julia --project=@decaes -e 'import Pkg; Pkg.add("DECAES"); Pkg.build("DECAES")'

This will add DECAES.jl to a named Julia project environment separate from your global environment, and build the decaes launcher script at ~/.julia/bin for running DECAES from the command line.

Simiarly, DECAES can be updated to the latest version via

$ julia --project=@decaes -e 'import Pkg; Pkg.update("DECAES"); Pkg.build("DECAES")'

Installing DECAES (MATLAB)

Download the MATLAB function decaes.m provided by this repository. DECAES will be installed the first time decaes.m is invoked, e.g. by running decaes --help in the MATLAB console. A Julia project folder .decaes is created in the same directory as decaes.m.

The DECAES version used by decaes.m can be updated by running decaes --update in the MATLAB console, or by deleting the .decaes folder which will trigger re-installation the next time decaes.m is called.

Tutorial

DECAES contains many parameters for performing T2 distribution analysis. For most parameters, we defer to the documentation.

Here we describe the most important parameters, which we have chosen to make required arguments. These parameters should be set carefully according to the scan parameters used when acquiring the image, and most importantly, should be set consistently when comparing results.

Required arguments:

MatrixSize: image matrix size (inferred from input image when using CLI)
nTE: number of echoes (inferred from input image when using CLI)
TE: echo time (units: seconds). Must correspond to scanning protocol
nT2: number of T2 bins. 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) requires more regularization
T2Range: range of logarithmically-spaced T2 values (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
SPWin and MPWin: 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 and MPWin controls the I/E water window
- For luminal water imaging (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
Reg: regularization method. DECAES provides three methods to automatically determine the regularization parameter mu for the Tikhonov regularization term:
- "lcurve": choose mu by locating the point of maximum curvature on the L-curve. This method is parameter-free; see the documentation
- "gcv": choose mu using the generalized cross-validation (GCV) method. This method is parameter-free; see the documentation
- "chi2": choose mu implicitly by specifying a (typically small) amount by which the squared-norm of

Mwiexamples

Install / Use

README