Command Line Interface
DECAES.jl provides a command line interface (CLI) for calling the main analysis functions: T2mapSEcorr
for computing $T_2$-distributions, and T2partSEcorr
for computing $T_2$-parts analysis, such as computing the myelin water fraction.
Using the CLI
Assuming you have DECAES.jl installed, there are two equivalent ways to use the CLI:
1. Helper script: Create a simple Julia script which calls the entrypoint function main
provided by this package. For example, save the following code in a Julia script called decaes.jl
:
using DECAES # load the package
main() # call command line interface
Run this script from the command line using julia
as follows:
$ julia decaes.jl image.nii <COMMAND LINE ARGS>
2. Julia -e
flag: The contents of the above script can equivalently be passed directly to Julia using the -e
flag (-e
for "evaluate"):
$ julia -e 'using DECAES; main()' image.nii <COMMAND LINE ARGS>
Either way of calling the CLI forwards the arguments <COMMAND LINE ARGS>
to the entrypoint function main
. Available arguments are detailed in the Arguments section.
For the remainder of this section, we will make use of the decaes.jl
script from option 1.
Multithreading
Multithreaded parallel processing can be enabled by setting the JULIA_NUM_THREADS
environment variable as follows:
$ export JULIA_NUM_THREADS=1
$ julia decaes.jl image.nii <COMMAND LINE ARGS>
This is highly recommended to speed up computation time, but is not strictly required.
From the Julia documentation:
[The keyword
export
] works on bourne shells on Linux and OSX. Note that if you're using a C shell on these platforms, you should use the keywordset
instead ofexport
. If you're on Windows, start up the command line in the location ofjulia.exe
and useset
instead ofexport
.
File types
The input image (image.nii
above) must be one of two file types:
- NIfTI file with extension
.nii
, or gzip compressed NIfTI file with extension.nii.gz
. See NIfTI.jl for more information - MATLAB file with extension
.mat
. Note:.mat
files saved in the oldest formatv4
are not supported, but all newer formats (v6
,v7
, andv7.3
) are supported. See MAT.jl for more information
All output files are saved as .mat
files in format v7.3
.
Arguments
Available command line arguments are broken into three categories:
- Positional arguments: these are the input files. Input files are typically placed at the beginning of
<COMMAND LINE ARGS>
. - Optional arguments: settings governing the analysis pipeline. See below for details.
T2mapSEcorr
/T2partSEcorr
arguments: settings for computing the $T_2$-distribution and subsequent $T_2$-parts analysis. See below for the full parameter list; seeT2mapSEcorr
andT2partSEcorr
for parameter descriptions. Note: if no default is shown, the parameter is unused by default.
usage: <PROGRAM> [--mask MASK [MASK...]] [-o OUTPUT] [--T2map]
[--T2part] [--quiet] [--dry] [--legacy]
[--Chi2Factor CHI2FACTOR] [--MinRefAngle MINREFANGLE]
[--MPWin MPWIN MPWIN] [--nRefAngles NREFANGLES]
[--nRefAnglesMin NREFANGLESMIN] [--nT2 NT2]
[--RefConAngle REFCONANGLE] [--Reg REG]
[--SaveDecayCurve] [--SaveNNLSBasis] [--SaveRegParam]
[--SaveResidualNorm] [--SetFlipAngle SETFLIPANGLE]
[--Sigmoid SIGMOID] [--Silent] [--SPWin SPWIN SPWIN]
[--T1 T1] [--T2Range T2RANGE T2RANGE] [--TE TE]
[--Threshold THRESHOLD] [--bet] [--betargs BETARGS]
[--betpath BETPATH] input...
positional arguments:
input one or more input filenames. Valid file types
are limited to: .mat, .nii, and .nii.gz
optional arguments:
--mask MASK [MASK...]
one or more mask filenames. Masks are loaded
and subsequently applied to the corresponding
input files via elementwise multiplication.
The number of mask files must equal the number
of input files. Valid file types are the same
as for input files, and are limited to: .mat,
.nii, and .nii.gz
-o, --output OUTPUT output directory. If not specified, output
file(s) will be stored in the same location as
the corresponding input file(s). Outputs are
stored with the same basename as inputs and
additional suffixes; see --T2map and --T2part
--T2map call T2mapSEcorr to compute T2 distributions
from 4D multi spin-echo input images. T2
distributions and T2 maps produced by
T2mapSEcorr are saved as MAT files with
extensions .t2dist.mat and .t2maps.mat
--T2part call T2partSEcorr to analyze 4D T2
distributions to produce parameter maps. If
--T2map is also passed, input 4D arrays are
interpreted as multi spin-echo images and T2
distributions are first computed by
T2mapSEcorr. If only --T2part is passed, input
4D arrays are interpreted as T2 distributions
and only T2partSEcorr is called. Output T2
parts are saved as a MAT file with extension
.t2parts.mat
--quiet suppress printing to the terminal. Note: 1)
errors are not silenced, and 2) this flag
overrides the --Silent flag in T2mapSEcorr
--dry execute dry run of processing without saving
any results
--legacy use legacy settings and algorithms from the
original MATLAB version. This ensures that the
exact same T2-distributions and T2-parts will
be produced as those from MATLAB (to machine
precision). Note that execution time will be
much slower.
T2mapSEcorr/T2partSEcorr arguments:
--Chi2Factor CHI2FACTOR
(default: 1.02)
--MinRefAngle MINREFANGLE
(default: 50.0)
--MPWin MPWIN MPWIN (default: [0.025, 0.2])
--nRefAngles NREFANGLES
(default: 32)
--nRefAnglesMin NREFANGLESMIN
(default: 5)
--nT2 NT2 (default: 40)
--RefConAngle REFCONANGLE
(default: 180.0)
--Reg REG (default: "chi2")
--SaveDecayCurve
--SaveNNLSBasis
--SaveRegParam
--SaveResidualNorm
--SetFlipAngle SETFLIPANGLE
--Sigmoid SIGMOID
--Silent
--SPWin SPWIN SPWIN (default: [0.01, 0.025])
--T1 T1 (default: 1.0)
--T2Range T2RANGE T2RANGE
(default: [0.01, 2.0])
--TE TE (default: 0.01)
--Threshold THRESHOLD
(default: 200.0)
BET arguments:
--bet use the BET brain extraction tool from the FSL
library of analyis tools to automatically
create a binary brain mask. Only voxels within
the binary mask will be analyzed. Note that if
a mask is passed explicitly with the --mask
flag, this mask will be used and --bet will be
ignored.
--betargs BETARGS BET optional arguments. Must be passed as a
single string with arguments separated by
spaces, e.g. '-m -n'. The flag '-m' creates
the binary mask and will be added to the list
of arguments if not provided. (default: "-m -n
-f 0.25 -R")
--betpath BETPATH path to BET executable. (default: "bet")
If desired, the $T_2$-distribution computation and the $T_2$-parts analysis may be performed separately:
- When the
--T2map
flag is passed, or both--T2map
and--T2part
flags are passed, input arrays should be 4D with data as (row, column, slice, echo) - When only the
--T2part
flag is passed, input arrays should be 4D with data as (row, column, slice, $T_2$ bin)
Examples
Default options
Suppose you have a multi spin-echo image file image.nii
which you would like to perform $T_2$ analysis on. We can call T2mapSEcorr
and T2partSEcorr
on the file image.nii
with default options using decaes.jl
as follows:
$ export JULIA_NUM_THREADS=1
$ julia decaes.jl image.nii --T2map --T2part
After a few seconds, the script should begin running with the following messages appearing as the script progresses (note that real images will take longer to process than this toy example):
[ Info: Starting with 1 threads
[ Info: Loading input file: image.nii.gz ...
[ Info: Done (1.05 seconds)
[ Info: Running T2mapSEcorr on file: image.nii.gz ...
┌ Info: T2-Distribution analysis settings:
│ Chi2Factor : 1.02
│ MatrixSize : (100, 100, 1)
│ MinRefAngle : 50.0
│ nRefAngles : 32
│ nRefAnglesMin : 5
│ nT2 : 40
│ nTE : 32
│ RefConAngle : 180.0
│ Reg : chi2
│ SaveDecayCurve : false
│ SaveNNLSBasis : false
│ SaveRegParam : false
│ SaveResidualNorm : false
│ SetFlipAngle : nothing
│ Silent : false
│ T1 : 1.0
│ T2Range : (0.01, 2.0)
│ TE : 0.01
└ Threshold : 200.0
[ Info: [ 0%] -- Elapsed Time: 00h:00m:13s -- Estimated Time Remaining: --h:--m:--s
[ Info: [ 6%] -- Elapsed Time: 00h:00m:28s -- Estimated Time Remaining: 00h:03m:34s
[ Info: [ 14%] -- Elapsed Time: 00h:00m:43s -- Estimated Time Remaining: 00h:03m:04s
[ Info: [ 21%] -- Elapsed Time: 00h:00m:58s -- Estimated Time Remaining: 00h:02m:43s
[ Info: [ 29%] -- Elapsed Time: 00h:01m:13s -- Estimated Time Remaining: 00h:02m:25s
[ Info: [ 36%] -- Elapsed Time: 00h:01m:28s -- Estimated Time Remaining: 00h:02m:09s
[ Info: [ 43%] -- Elapsed Time: 00h:01m:43s -- Estimated Time Remaining: 00h:01m:54s
[ Info: [ 51%] -- Elapsed Time: 00h:01m:58s -- Estimated Time Remaining: 00h:01m:38s
[ Info: [ 58%] -- Elapsed Time: 00h:02m:13s -- Estimated Time Remaining: 00h:01m:23s
[ Info: [ 65%] -- Elapsed Time: 00h:02m:28s -- Estimated Time Remaining: 00h:01m:09s
[ Info: [ 73%] -- Elapsed Time: 00h:02m:43s -- Estimated Time Remaining: 00h:00m:54s
[ Info: [ 80%] -- Elapsed Time: 00h:02m:58s -- Estimated Time Remaining: 00h:00m:39s
[ Info: [ 88%] -- Elapsed Time: 00h:03m:13s -- Estimated Time Remaining: 00h:00m:24s
[ Info: [ 95%] -- Elapsed Time: 00h:03m:28s -- Estimated Time Remaining: 00h:00m:09s
[ Info: [100%] -- Elapsed Time: 00h:03m:36s -- Estimated Time Remaining: 00h:00m:00s
[ Info: Done (225.86 seconds)
[ Info: Saving T2 distribution to file: image.t2dist.mat ...
[ Info: Done (1.13 seconds)
[ Info: Saving T2 parameter maps to file: image.t2maps.mat ...
[ Info: Done (0.41 seconds)
[ Info: Running T2partSEcorr ...
┌ Info: T2-part analysis settings:
│ MatrixSize : (100, 100, 1)
│ MPWin : (0.025, 0.2)
│ nT2 : 40
│ Sigmoid : nothing
│ Silent : false
│ SPWin : (0.01, 0.025)
└ T2Range : (0.01, 2.0)
[ Info: Done (2.12 seconds)
[ Info: Saving T2 parts maps to file: image.t2parts.mat ...
[ Info: Done (0.0 seconds)
[ Info: Finished (230.76 seconds)
The script will produce four files, each with the input filename (without suffix) used as a prefix:
image.t2dist.mat
: MATLAB file containing the $T_2$-distributionsimage.t2maps.mat
: MATLAB file containing $T_2$-distribution property maps and NNLS fit parameters; seeT2mapSEcorr
image.t2parts.mat
: MATLAB file containing $T_2$-parts analysis results such as the MWF; seeT2partSEcorr
image.log
: Log file containing the console output
Multiple input files
Multiple input files (possibly of different file types) can be passed in the obvious way:
$ export JULIA_NUM_THREADS=1
$ julia decaes.jl image1.nii image2.mat image3.nii.gz --T2map --T2part
.nii
and .nii.gz
input image files are assumed to be 4D when loaded; an error will occur if they are not 4D. For .mat
files, the first 4D array which is found within the .mat
file is used (multiple 4D arrays should not be stored in the same .mat
file); an error will occur if no 4D image is found.
Specify output folder
By default, output files are saved in the same location as the corresponding input file. If you'd like to save them in a different folder, you can use the -o
or --output
flag:
$ export JULIA_NUM_THREADS=1
$ julia decaes.jl image.nii --T2map --T2part --output /path/to/output/folder/
The requested output folder will be created if it does not already exist.
Non-default parameters
Parameter values can be set to non-default values at the command line. For example, we can set the echo time TE
to 8ms, the number of $T_2$ bins nT2
to 60, and the $T_2$ distribution range to [10ms, 1.5s] as follows:
$ export JULIA_NUM_THREADS=1
$ julia decaes.jl image.nii --T2map --T2part --TE 0.008 --nT2 60 --T2Range 0.010 1.5
Passing image masks
Image masks can be passed into DECAES.jl using the --mask
flag:
$ export JULIA_NUM_THREADS=1
$ julia decaes.jl image.nii --T2map --T2part --mask mask.nii
The mask file is loaded and applied to the input image via elementwise multiplication over the spatial dimensions, e.g. the mask is applied to each echo of a 4D multi-echo input image.
If multiple image files are passed, a mask can be passed for each input image (note that each mask file can be any valid file type):
$ export JULIA_NUM_THREADS=1
$ julia decaes.jl image1.nii image2.mat --T2map --T2part --mask mask1.mat mask2.nii.gz
If input images have been manually masked such that they are e.g. zero outside regions of interest, a mask need not be passed. The --Threshold
parameter of T2mapSEcorr
controls a first echo intensity cutoff threshold (default value 200.0), below which voxels are automatically skipped during processing.
Automatic brain masking with BET
The BET brain extraction tool from the FSL library of analysis tools can be used to automatically generate a brain mask prior to analysis. Only voxels within the generated brain mask will be processed, greatly reducing analysis time. To use BET, pass the --bet
flag:
$ export JULIA_NUM_THREADS=1
$ julia decaes.jl image.nii --T2map --T2part --bet
If bet
is not on your system path, you can pass the path to the bet
binary with the --betpath
flag. Additionally, you can pass arguments to bet
with the --betargs
flag:
$ export JULIA_NUM_THREADS=1
$ julia decaes.jl image.nii --T2map --T2part --bet --betpath /path/to/bet --betargs '-m -n'
Note that bet
arguments must be passed as a single string to --betargs
, separated by spaces, as shown above.
If a mask file is passed using the --mask
flag, the --bet
flag will be ignored and the mask file will be used.
Settings files
Parameter values can be read in from a settings file. For example, we can combine the examples from the Specify output folder and Non-default parameters sections by creating a settings.txt
file with the following contents:
/path/to/image.nii
--output
/path/to/output/folder/
--T2map
--T2part
--TE
0.008
--nT2
60
--T2Range
0.010
1.5
If this file is located at /path/to/settings.txt
, simply prefix the filepath with the @
character to have the file contents read into the main
function:
$ export JULIA_NUM_THREADS=1
$ julia decaes.jl @/path/to/settings.txt
- The use of settings files is highly recommended for both reproducibility and for self-documentation. The input settings file will be automatically copied into the output folder for each processed image, with the image filename prepended. In this case, for example, the copied settings file would be called
image.settings.txt
- Only one flag or value is allowed per line within a settings file. Flags which require multiple inputs (e.g.
--T2Range
above) must use one line for each input - The extension of the settings file is ignored;
.txt
is arbitrary in this example - Though not strictly necessary, using full input- and output paths is recommended. This way, one doesn't rely on relative paths and can e.g. call
julia /path/to/decaes.jl @/path/to/settings.txt
from any directory
Legacy options
During the MATLAB port to Julia, some algorithms were replaced with mathematically identical but computationally more efficient algorithms which may cause small differences in output parameter maps, and some default options were changed.
For example, the flip angle optimization procedure requires finding the root of a cubic spline. In MATLAB this was performed by evaluating the spline on a very fine mesh and choosing the value nearest zero. During profiling it was found that this was a time consuming operation, and therefore in Julia this was replaced by an efficient spline rootfinding method.
The differences due to algorithmic changes like the one above are quite small. For example, most tests will pass when using a relative tolerance of $10^{-3}$, and almost all tests pass with a relative tolerance of $10^{-2}$. That is to say that nearly all outputs are identical to 3 or more significant digits, which includes $T_2$-distributions, MWF maps, etc.
The --legacy
flag is available if exact reproducibility is required compared to the MATLAB version. This will ensure that all outputs match to nearly machine precision (a relative tolerance of $10^{-10}$ is used during testing). Note however that the --legacy
flag may cause a significant slowdown in processing time due to less efficient internal algorithms being used, and is therefore not recommended unless absolutely necessary. Differences due to changes in default parameters can always be overridden by passing in the desired value explicitly (e.g. --SPWin 0.014 0.040
) without the need for the --legacy
flag.
Default options with the --legacy
flag
usage: <PROGRAM> [--mask MASK [MASK...]] [-o OUTPUT] [--T2map]
[--T2part] [--quiet] [--dry] [--legacy]
[--Chi2Factor CHI2FACTOR] [--MinRefAngle MINREFANGLE]
[--MPWin MPWIN MPWIN] [--nRefAngles NREFANGLES]
[--nRefAnglesMin NREFANGLESMIN] [--nT2 NT2]
[--RefConAngle REFCONANGLE] [--Reg REG]
[--SaveDecayCurve] [--SaveNNLSBasis] [--SaveRegParam]
[--SaveResidualNorm] [--SetFlipAngle SETFLIPANGLE]
[--Sigmoid SIGMOID] [--Silent] [--SPWin SPWIN SPWIN]
[--T1 T1] [--T2Range T2RANGE T2RANGE] [--TE TE]
[--Threshold THRESHOLD] [--bet] [--betargs BETARGS]
[--betpath BETPATH] input...
positional arguments:
input one or more input filenames. Valid file types
are limited to: .mat, .nii, and .nii.gz
optional arguments:
--mask MASK [MASK...]
one or more mask filenames. Masks are loaded
and subsequently applied to the corresponding
input files via elementwise multiplication.
The number of mask files must equal the number
of input files. Valid file types are the same
as for input files, and are limited to: .mat,
.nii, and .nii.gz
-o, --output OUTPUT output directory. If not specified, output
file(s) will be stored in the same location as
the corresponding input file(s). Outputs are
stored with the same basename as inputs and
additional suffixes; see --T2map and --T2part
--T2map call T2mapSEcorr to compute T2 distributions
from 4D multi spin-echo input images. T2
distributions and T2 maps produced by
T2mapSEcorr are saved as MAT files with
extensions .t2dist.mat and .t2maps.mat
--T2part call T2partSEcorr to analyze 4D T2
distributions to produce parameter maps. If
--T2map is also passed, input 4D arrays are
interpreted as multi spin-echo images and T2
distributions are first computed by
T2mapSEcorr. If only --T2part is passed, input
4D arrays are interpreted as T2 distributions
and only T2partSEcorr is called. Output T2
parts are saved as a MAT file with extension
.t2parts.mat
--quiet suppress printing to the terminal. Note: 1)
errors are not silenced, and 2) this flag
overrides the --Silent flag in T2mapSEcorr
--dry execute dry run of processing without saving
any results
--legacy use legacy settings and algorithms from the
original MATLAB version. This ensures that the
exact same T2-distributions and T2-parts will
be produced as those from MATLAB (to machine
precision). Note that execution time will be
much slower.
T2mapSEcorr/T2partSEcorr arguments:
--Chi2Factor CHI2FACTOR
(default: 1.02)
--MinRefAngle MINREFANGLE
(default: 50.0)
--MPWin MPWIN MPWIN (default: [0.04, 0.2])
--nRefAngles NREFANGLES
(default: 8)
--nRefAnglesMin NREFANGLESMIN
(default: 8)
--nT2 NT2 (default: 40)
--RefConAngle REFCONANGLE
(default: 180.0)
--Reg REG (default: "chi2")
--SaveDecayCurve
--SaveNNLSBasis
--SaveRegParam
--SaveResidualNorm
--SetFlipAngle SETFLIPANGLE
--Sigmoid SIGMOID
--Silent
--SPWin SPWIN SPWIN (default: [0.014, 0.04])
--T1 T1 (default: 1.0)
--T2Range T2RANGE T2RANGE
(default: [0.015, 2.0])
--TE TE (default: 0.01)
--Threshold THRESHOLD
(default: 200.0)
BET arguments:
--bet use the BET brain extraction tool from the FSL
library of analyis tools to automatically
create a binary brain mask. Only voxels within
the binary mask will be analyzed. Note that if
a mask is passed explicitly with the --mask
flag, this mask will be used and --bet will be
ignored.
--betargs BETARGS BET optional arguments. Must be passed as a
single string with arguments separated by
spaces, e.g. '-m -n'. The flag '-m' creates
the binary mask and will be added to the list
of arguments if not provided. (default: "-m -n
-f 0.25 -R")
--betpath BETPATH path to BET executable. (default: "bet")