Command Line Interface
The DECAES command-line interface (CLI) computes $T_2$ distributions and derived quantities such as the myelin water fraction.
Using the CLI
After installing DECAES, use one of these equivalent commands:
1. Recommended: decaes launcher
decaes <COMMAND LINE ARGS>2. Julia -e flag
julia --project=@decaes --threads=auto -e 'using DECAES; main()' -- <COMMAND LINE ARGS>The flag --threads=auto enables parallel processing, which is critical for maximizing DECAES performance.
Both commands pass <COMMAND LINE ARGS> to main. The examples below use the decaes launcher.
File types
Supported input formats are:
- NIfTI:
.niior.nii.gz; see NIfTI.jl - MATLAB:
.matin v6, v7, or v7.3 format; see MAT.jl - Philips PAR/REC:
.parand.rec(or.PARand.REC); see ParXRec.jl - Philips XML/REC:
.xmland.rec(or.XMLand.REC); see ParXRec.jl
Outputs are saved as MATLAB files in format v7.3 by default. Pass --OutputFormat nii to save image outputs as NIfTI files instead.
Convert DICOM data to NIfTI using dcm2niix.
- Image arrays must have dimensions
(row, column, slice, echo)for multi-echo data and(row, column, slice, T2 bin)for $T_2$ distributions. Masks must have dimensions(row, column, slice). - For MATLAB files, DECAES uses the first array with the required shape. Store only one candidate image array per file.
Arguments
The CLI accepts the arguments below, grouped by purpose:
- Input image paths and general options such as the output directory
- Required and optional settings for $T_2$ mapping and $T_2$-parts analysis
- B1 and stimulated-echo correction settings
- Optional output maps
- Automatic brain masking with BET
See also T2mapOptions and T2partOptions.
usage: decaes [-m MASK [MASK...]] [-o OUTPUT [OUTPUT...]] [--T2map]
[--T2part] [-q] [--dry]
[--MatrixSize MATRIXSIZE MATRIXSIZE MATRIXSIZE]
[--nTE NTE] [--TE TE] [--nT2 NT2]
[--T2Range T2RANGE T2RANGE] [--SPWin SPWIN SPWIN]
[--MPWin MPWIN MPWIN] [--Reg REG] [--RegNorm REGNORM]
[--RegParams REGPARAMS [REGPARAMS...]]
[--Chi2Factor CHI2FACTOR] [--T1 T1] [--Sigmoid SIGMOID]
[--Threshold THRESHOLD] [--B1map B1MAP [B1MAP...]]
[--nRefAngles NREFANGLES]
[--nRefAnglesMin NREFANGLESMIN]
[--MinRefAngle MINREFANGLE]
[--SetFlipAngle SETFLIPANGLE]
[--RefConAngle REFCONANGLE]
[--OutputFormat OUTPUTFORMAT] [--NoSaveT2Dist]
[--SaveDecayCurve] [--SaveNNLSBasis] [--SaveRegParam]
[--SaveResidualNorm] [--bet] [--betargs BETARGS]
[--betpath BETPATH] [input...]
positional arguments:
input one or more input filenames. Valid file types
are limited to: .mat, .nii, .nii.gz, .par,
.xml, and .rec
optional arguments:
-m, --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, .nii.gz, .par, .xml, and .rec
-o, --output OUTPUT [OUTPUT...]
one or more output directories. If not
specified, output file(s) will be stored in
the same location as the corresponding input
file(s). If one folder is passed, all output
files from all processed images will be stored
in the same folder. Otherwise, the number of
output folders must equal the number of input
files. Outputs are stored with the same
basename as the input files with additional
suffixes; see --T2map and --T2part
--T2map call T2mapSEcorr to compute T2 distributions
from 4D multi-spin echo input images. Outputs
use the suffixes .t2dist and .t2maps; see
--OutputFormat
--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. Outputs use
the suffix .t2parts; see --OutputFormat
-q, --quiet suppress printing to the terminal. Note: all
terminal outputs, including errors and
warnings, are still printed to the log file
--dry execute dry run of processing without saving
any results
T2map/T2part required parameters:
--MatrixSize MATRIXSIZE MATRIXSIZE MATRIXSIZE
matrix size of the magnitude image. Inferred
automatically as the first three dimensions of
the input 4D image (type: Int64)
--nTE NTE number of echoes of the magnitude image.
Inferred automatically as the last dimension
of the input 4D image (type: Int64)
--TE TE inter-echo spacing. Required when --T2map is
passed. (units: time, must match --T1 and
--T2Range) (type: Float64)
--nT2 NT2 number of T2 components used in the
multi-exponential analysis. Required when
--T2map is passed. Inferred from fourth
dimension of input image if only --T2part and
not --T2map is passed (type: Int64)
--T2Range T2RANGE T2RANGE
minimum and maximum T2 values. T2 components
are logarithmically spaced between these
bounds. Required parameter. (units: time, must
match --TE) (type: Float64)
--SPWin SPWIN SPWIN minimum and maximum T2 values of the short
peak window. Required parameter when --T2part
is passed. (units: time, must match --T2Range)
(type: Float64)
--MPWin MPWIN MPWIN minimum and maximum T2 values of the middle
peak window. Required parameter when --T2part
is passed. (units: time, must match --T2Range)
(type: Float64)
--Reg REG method used for choosing the regularization
parameter. One of "gcv", "lcurve", "reginska",
"chi2", "mdp", or "none". These flags
correspond to generalized cross-validation,
the L-curve method, Reginska's minimum-product
criterion, the chi-squared method, Morozov's
discrepancy principle, and zero
regularization. Required parameter
--RegNorm REGNORM norm of the regularization penalty term. One
of "l2" or "l1", penalizing mu^2 * ||x||_2^2
or mu * ||x||_1, respectively. --Reg="gcv"
supports only "l2". (default: "l2")
--RegParams REGPARAMS [REGPARAMS...]
parameters for the regularization method
chosen via --Reg. Required parameter if
--Reg="chi2" or --Reg="mdp" (type: Float64)
--Chi2Factor CHI2FACTOR
if --Reg="chi2", the T2 distribution is
regularized such that the chi^2 goodness of
fit is increased by a multiplicative factor
--Chi2Factor relative to the unregularized
solution. Required parameter when
--Reg="chi2". Note: this flag is now
deprecated and will be removed in future
releases; use --RegParams instead (type:
Float64)
T2map/T2part optional parameters:
--T1 T1 assumed value of longitudinal T1 relaxation.
(default: 1.0) (units: time, must match --TE)
(type: Float64)
--Sigmoid SIGMOID replace the hard upper limit cutoff time of
the short peak window, SPWin[2], with a
smoothed sigmoidal cutoff function 'σ' scaled
and shifted such that σ(SPWin[2] +/- Sigmoid)
= 0.5 -/+ 0.4. Sigmoid is the time scale of
the smoothing. (units: time, must match
--T2Range) (type: Float64)
--Threshold THRESHOLD
first echo intensity cutoff for empty voxels.
Processing is skipped for voxels with
intensity <= --Threshold. (default: 0.0)
(units: signal magnitude) (type: Float64)
B1 correction and stimulated echo correction:
--B1map B1MAP [B1MAP...]
one or more B1 map filenames. The B1 maps must
have the same matrix sizes as the
corresponding images, and are assumed to
represent flip angles in units of degrees. The
number of B1 map files must equal the number
of input files. Valid file types are the same
as for input files, and are limited to: .mat,
.nii, .nii.gz, .par, .xml, and .rec. (units:
degrees)
--nRefAngles NREFANGLES
maximum number of flip angles spanning
[--MinRefAngle, 180] checked during local
refocusing flip angle estimation. (default:
500) (type: Int64)
--nRefAnglesMin NREFANGLESMIN
initial number of angles evaluated before
refinement near likely optima during local
refocusing flip angle estimation. (default:
15) (type: Int64)
--MinRefAngle MINREFANGLE
minimum refocusing angle estimate allowed.
(default: 90.0) (units: degrees) (type:
Float64)
--SetFlipAngle SETFLIPANGLE
to skip B1 inhomogeneity correction, use
--SetFlipAngle to assume a fixed refocusing
flip angle for all voxels. (units: degrees)
(type: Float64)
--RefConAngle REFCONANGLE
refocusing pulse control angle. The sequence
of flip angles used within the extended phase
graph algorithm to perform stimulated echo
correction is (90, 180, β, β, ..., β), where β
is the refocusing pulse control angle. For
typical multi-spin echo sequences this
parameter should not be changed. (default:
180.0) (units: degrees) (type: Float64)
Additional save options:
--OutputFormat OUTPUTFORMAT
format of image outputs. One of "mat" or
"nii". NIfTI outputs are gzipped and inherit
the header of a NIfTI input image; non-image
data remain in a MAT file. (default: "mat")
(default: "mat")
--NoSaveT2Dist skip saving the 4D T2 distribution computed by
--T2map, which is large for typical image
sizes
--SaveDecayCurve include a 4D array of the time domain decay
curves resulting from the NNLS fits in the
output maps dictionary
--SaveNNLSBasis include a 5D (or 2D if --SetFlipAngle is used)
array of NNLS basis matrices in the output
maps dictionary. Note: this 5D array is
extremely large for typical image sizes; in
most cases, this flag should only be set when
debugging small images
--SaveRegParam include 3D arrays of resulting regularization
parameters and χ² factors in the output maps
dictionary
--SaveResidualNorm include a 3D array of the l2-norms of the
residuals from the NNLS fits in the output
maps dictionary
BET arguments:
--bet use the BET brain extraction tool from the FSL
library of analysis 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 the --bet
flag will be ignored
--betargs BETARGS BET command line interface arguments. Must be
passed as a single string with arguments
separated by commas or spaces, e.g. "-m,-n".
The flag "-m" indicates that a binary mask
should be computed, and therefore 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")--T2map requires multi-echo data. --T2part is typically run after --T2map, but can be run independently if given a precomputed $T_2$ distribution.
Outputs
Output filenames use the input filename as a prefix. For an input named image.nii, DECAES may produce:
image.t2dist.mat: $T_2$ distributions from--T2mapimage.t2maps.mat: $T_2$ distribution properties and fit parameters from--T2map; seeT2mapSEcorrimage.t2parts.mat: derived quantities such as MWF from--T2part; seeT2partSEcorrimage.log: console outputimage.settings.txt: copy of an input settings file
If --NoSaveT2Dist is passed, the large $T_2$ distribution file is not saved; it is not needed if one is only interested in derived image maps.
If the --dry flag is passed, none of the above files will be produced.
NIfTI outputs
Passing --OutputFormat nii saves the $T_2$ distribution and derived maps as gzipped NIfTI files:
image.t2dist.nii.gz: $T_2$ distributinoimage.t2maps.meta.mat: non-image metadata such as echo times, $T_2$ times, etc.image.t2maps.<name>.nii.gz: image shaped outputs fromT2mapSEcorrimage.t2parts.<name>.nii.gz: image shaed outputs fromT2partSEcorr
NIfTI output files inherit the header of a NIfTI input image, preserving its voxel size and orientation.
Examples
Default options
Compute the $T_2$ distribution and $T_2$ parts for a multi-spin echo image using:
$ decaes image.nii --T2map --T2part --TE 10e-3 --nT2 40 --T2Range 10e-3 2.0 --SPWin 10e-3 40e-3 --MPWin 40e-3 200.0e-3 --Reg lcurveThis command:
- Reads the multi-echo data from
image.nii - Uses
--T2mapto compute the $T_2$ distribution, then--T2partto compute quantities derived from it - Sets the echo spacing to
10e-3, the number of $T_2$ bins to 40, and the $T_2$ range to[10e-3, 2.0] - Defines the short- and middle-$T_2$ peak windows with
--SPWinand--MPWin - Selects L-curve regularization with
--Reg lcurve
The time-valued arguments use seconds here, but any consistent unit may be used. Acquisition-dependent values such as TE, T2Range, SPWin, and MPWin should be chosen for the data rather than copied blindly from this example.
Below is an example pipeline output on a small synthetic image:
[ Info: Starting DECAES v0.7.0 using Julia v1.12.7 with 4 threads
[ Info: Loading input file: image.nii.gz
[ Info: Done (0.02 seconds)
[ Info: Running T2mapSEcorr on file: image.nii.gz
┌ Info: T2-distribution analysis settings:
│ * Chi2Factor : nothing
│ * MatrixSize : (100, 100, 1)
│ * MinRefAngle : 90.0
│ * NoiseLevel : nothing
│ * nRefAngles : 500
│ * nRefAnglesMin : 15
│ * nT2 : 40
│ * nTE : 48
│ * RefConAngle : 180.0
│ * Reg : lcurve
│ * RegNorm : l2
│ * SaveDecayCurve : false
│ * SaveNNLSBasis : false
│ * SaveRegParam : false
│ * SaveResidualNorm : false
│ * SetFlipAngle : nothing
│ * Silent : false
│ * T1 : 1.0
│ * T2Range : (0.01, 2.0)
│ * TE : 0.01
│ * Threaded : true
└ * Threshold : 0.0
[ Info: Done (0.42 seconds)
[ Info: Saving T2 distribution to file: image.t2dist.mat
[ Info: Done (0.01 seconds)
[ Info: Saving T2 parameter maps to file: image.t2maps.mat
[ Info: Done (0.0 seconds)
[ Info: Running T2partSEcorr
┌ Info: T2-parts analysis settings:
│ * MatrixSize : (100, 100, 1)
│ * MPWin : (0.04, 0.2)
│ * nT2 : 40
│ * Sigmoid : nothing
│ * Silent : false
│ * SPWin : (0.01, 0.04)
│ * T2Range : (0.01, 2.0)
└ * Threaded : true
[ Info: Done (0.0 seconds)
[ Info: Saving T2 parts maps to file: image.t2parts.mat
[ Info: Done (0.0 seconds)
[ Info: Finished (0.87 seconds)Settings files
Settings files make long commands easier to reuse and record. They place one flag or value on each line; an option with multiple values, such as --T2Range, therefore uses multiple lines. For example, /path/to/settings.txt could contain:
/path/to/image.nii
--T2map
--T2part
--TE
10e-3
--nT2
40
--T2Range
10e-3
2.0
--SPWin
10e-3
40e-3
--MPWin
40e-3
200.0e-3
--Reg
lcurvePrefix the path with @ to use it:
$ decaes @/path/to/settings.txtDECAES copies each settings file to the output directory for reproducibility. The extension is arbitrary. Using absolute input and output paths allows the settings file to be used from any working directory.
Default settings files
Arguments written after a settings file override values from that file. This is useful when most settings remain fixed across analyses. For example, the following command uses default.txt but changes nT2 to 60:
$ decaes @/path/to/default.txt --nT2 60Multiple input files
One command can process multiple input files using the same analysis settings. The files may use different supported formats:
$ decaes image1.nii image2.mat image3.nii.gz image4.par <COMMAND LINE ARGS>In a settings file, place each image path on a separate line.
Specify output folder
Outputs are saved in the same folder as the inputs by default. Use -o or --output to select another directory:
$ decaes image.nii --output /path/to/output/folder/ <COMMAND LINE ARGS>DECAES creates the output directory if needed.
Passing image masks
Pass an image mask using -m or --mask. Voxels outside the mask are skipped and are represented by NaN in output maps:
$ decaes image.nii --mask /path/to/mask.nii <COMMAND LINE ARGS>For multiple images, pass the corresponding masks in the same order:
$ decaes image1.nii image2.mat --mask /path/to/mask1.mat /path/to/mask2.nii.gz <COMMAND LINE ARGS>A separate mask is unnecessary for images that are already masked to zero outside the region of interest. See T2mapOptions for the Threshold behavior.
Automatic brain masking with BET
If no mask is available, DECAES can call FSL's BET brain extraction tool to generate one. Only voxels inside the generated mask are processed:
$ decaes image.nii --bet <COMMAND LINE ARGS>If bet is not on PATH, specify its location with --betpath. Pass BET arguments as one comma- or space-separated string using --betargs:
$ decaes image.nii --bet --betpath /path/to/bet --betargs -m,-n <COMMAND LINE ARGS>