Command Line Interface

DECAES provides a command line interface (CLI) for calling the main analysis functions: T2mapSEcorr for computing $T_2$-distributions, and T2partSEcorr for running $T_2$-parts analysis on the resulting $T_2$-distributions for computing measures such as the myelin water fraction.

Using the CLI

There are two equivalent ways to use the command line interface (CLI), assuming DECAES is already installed:

1. (Recommended) decaes launcher: Use the script ~/.julia/bin/decaes which comes with DECAES:

$ decaes <COMMAND LINE ARGS>

2. Julia -e flag: Call the DECAES CLI from Julia directly using the -e (for "evaluate") flag:

$ julia --project=@decaes --threads=auto -e 'using DECAES; main()' -- <COMMAND LINE ARGS>

The decaes launcher is in fact just a thin wrapper script around a command like this one.

Either way of calling the CLI forwards the arguments <COMMAND LINE ARGS> to the entrypoint function main. Available command line arguments are detailed in the Arguments section.

For the remainder of this section, we will make use of the decaes launcher.

File types

Input files must be one of the following file types:

1. NIfTI file with extension .nii, or gzip compressed NIfTI file with extension .nii.gz. See NIfTI.jl for more information.
2. MATLAB file with extension .mat. Note: .mat files saved in the oldest format v4 are not supported, but all newer formats (v6, v7, and v7.3) are supported. See MAT.jl for more information.
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.

Arguments

Available command line arguments are broken into four categories:

1. Positional arguments: these are the input files. Input files are typically placed at the beginning of <COMMAND LINE ARGS>.
2. Optional arguments: settings governing the analysis pipeline. See below for details.
3. T2mapSEcorr/T2partSEcorr arguments: settings for computing the $T_2$-distribution and subsequent $T_2$-parts analysis. Required arguments are listed first; see below for the full parameter list, and see T2mapSEcorr and T2partSEcorr for parameter descriptions. Note: if no default is shown, the parameter is unused by default.
4. B1 correction and stimulated echo correction: settings for controlling B1 correction and stimulated echo correction. These settings typically need not be modified. However, the following options are noteworthy: --SetFlipAngle allows for prescribing a fixed flip angle for all voxels instead of estimating the flip angle per-voxel; and --B1map allows for passing B1 maps (units of degrees) directly, replacing the flip angle estimation step.
5. Additional save options: optional additional output maps
6. BET arguments: settings for governing automatic brain mask generation using the BET brain extraction tool; see below for details.

usage: decaes [-m MASK [MASK...]] [-o OUTPUT [OUTPUT...]] [--T2map]
              [--T2part] [-q] [--dry] [--legacy]
              [--MatrixSize MATRIXSIZE MATRIXSIZE MATRIXSIZE]
              [--nTE NTE] [--TE TE] [--nT2 NT2]
              [--T2Range T2RANGE T2RANGE] [--SPWin SPWIN SPWIN]
              [--MPWin MPWIN MPWIN] [--Reg REG]
              [--RegParams REGPARAMS [REGPARAMS...]]
              [--Chi2Factor CHI2FACTOR] [--T1 T1] [--Sigmoid SIGMOID]
              [--Threshold THRESHOLD] [--B1map B1MAP [B1MAP...]]
              [--nRefAngles NREFANGLES]
              [--nRefAnglesMin NREFANGLESMIN]
              [--MinRefAngle MINREFANGLE]
              [--SetFlipAngle SETFLIPANGLE]
              [--RefConAngle REFCONANGLE] [--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. 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
  -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
  --legacy              use legacy settings and algorithms from the
                        original MATLAB pipeline. Note: this flag is
                        now deprecated and will be removed in future
                        releases

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: seconds) (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: seconds)
                        (type: Float64)
  --SPWin SPWIN SPWIN   minimum and maximum T2 values of the short
                        peak window. Required parameter when --T2part
                        is passed. (units: seconds) (type: Float64)
  --MPWin MPWIN MPWIN   minimum and maximum T2 values of the middle
                        peak window. Required parameter when --T2part
                        is passed. (units: seconds) (type: Float64)
  --Reg REG             method used for choosing the Tikhonov
                        regularization parameter. One of "lcurve",
                        "gcv", "chi2", "mdp", or "none". These flags
                        correspond to the L-curve method, generalized
                        cross-validation, the chi-squared method,
                        Morozov's discrepency principle, and zero
                        regularization. Required parameter
  --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: seconds) (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: seconds) (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
                        in estimating the local refocusing flip angle
                        to correct for B1 inhomogeneities, up to
                        --nRefAngles angles in the range
                        [--MinRefAngle, 180] are explicitly checked.
                        The optimal angle is then estimated by
                        interpolating between these observations.
                        (default: 32) (type: Int64)
  --nRefAnglesMin NREFANGLESMIN
                        initial number of angles in the range
                        [--MinRefAngle, 180] to check during flip
                        angle estimation before refinement near likely
                        optima. Setting --nRefAnglesMin equal to
                        --nRefAngles forces all candidate angles to be
                        checked before interpolation. (default: 5)
                        (type: Int64)
  --MinRefAngle MINREFANGLE
                        minimum refocusing angle for flip angle
                        estimation. (default: 50.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:
  --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")

Outputs

DECAES will produce up to five output files, each with the input filename (without suffix) used as a prefix. For example, if the input file is called image.nii, the possible output files are:

1. image.t2dist.mat: MATLAB file containing the 4D array of $T_2$-distributions (produced when --T2map flag is passed)
2. image.t2maps.mat: MATLAB file containing $T_2$-distribution property maps and NNLS fit parameters; see T2mapSEcorr (produced when --T2map flag is passed)
3. image.t2parts.mat: MATLAB file containing $T_2$-parts analysis results such as the MWF; see T2partSEcorr (produced when --T2part flag is passed)
4. image.log: Log file containing the console output
5. image.settings.txt: Copy of settings file which was named settings.txt (produced when passing settings as a file)

If the --dry flag is passed, none of the above files will be produced.

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 using the decaes launcher. We pass the required arguments with the appropriate flags and leave the remaining parameters at default values:

$ 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 lcurve

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 DECAES v0.6.0 using Julia v1.10.0 with 1 threads
[ Info: Loading input file: image.nii.gz
[ Info: Done (0.03 seconds)
[ Info: Running T2mapSEcorr on file: image.nii.gz
┌ Info: T2-distribution analysis settings:
│ * Chi2Factor       : nothing
│ * legacy           : false
│ * MatrixSize       : (100, 100, 1)
│ * MinRefAngle      : 50.0
│ * NoiseLevel       : nothing
│ * nRefAngles       : 64
│ * nRefAnglesMin    : 5
│ * nT2              : 40
│ * nTE              : 48
│ * RefConAngle      : 180.0
│ * Reg              : lcurve
│ * SaveDecayCurve   : false
│ * SaveNNLSBasis    : false
│ * SaveRegParam     : false
│ * SaveResidualNorm : false
│ * SetFlipAngle     : nothing
│ * Silent           : false
│ * T1               : 1.0
│ * T2Range          : (0.01, 2.0)
│ * TE               : 0.01
│ * Threaded         : false
└ * Threshold        : 0.0
[ Info:    7%[===>                                               ]  ETA: 0:01:08
[ Info:   14%[=======>                                           ]  ETA: 0:01:02
[ Info:   21%[==========>                                        ]  ETA: 0:00:57
[ Info:   28%[==============>                                    ]  ETA: 0:00:51
[ Info:   35%[=================>                                 ]  ETA: 0:00:47
[ Info:   42%[=====================>                             ]  ETA: 0:00:41
[ Info:   49%[=========================>                         ]  ETA: 0:00:36
[ Info:   56%[============================>                      ]  ETA: 0:00:31
[ Info:   63%[================================>                  ]  ETA: 0:00:26
[ Info:   71%[===================================>               ]  ETA: 0:00:21
[ Info:   78%[=======================================>           ]  ETA: 0:00:16
[ Info:   85%[===========================================>       ]  ETA: 0:00:11
[ Info:   92%[==============================================>    ]  ETA: 0:00:06
[ Info:   99%[==================================================>]  ETA: 0:00:01
[ Info:  100%[===================================================] Time: 0:01:12
[ Info: Done (72.79 seconds)
[ Info: Saving T2 distribution to file: image.t2dist.mat
[ Info: Done (0.46 seconds)
[ Info: Saving T2 parameter maps to file: image.t2maps.mat
[ Info: Done (0.1 seconds)
[ Info: Running T2partSEcorr
┌ Info: T2-parts analysis settings:
│ * legacy     : false
│ * 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   : false
[ Info: Done (0.01 seconds)
[ Info: Saving T2 parts maps to file: image.t2parts.mat
[ Info: Done (0.0 seconds)
[ Info: Finished (73.75 seconds)

Settings files

As there are several required parameters, it is convenient to store settings for DECAES in a settings file. Using the same options from the previous section, we create a file settings.txt with the following contents:

/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
lcurve

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:

$ decaes @/path/to/settings.txt

Default settings files

Suppose you have a default settings file default.txt, similar to the settings.txt file in the above section. Settings in default.txt can be individually overridden. For example, if we are interested in changing the number of $T_2$ bins nT2 to 60, but leaving all other parameters the same, run the following:

$ decaes @/path/to/default.txt --nT2 60

Multiple input files

Multiple input files (possibly of different file types) can be passed in the obvious way:

$ decaes image1.nii image2.mat image3.nii.gz image4.par <COMMAND LINE ARGS>

Equivalently, place multiple image paths at the top of your settings file, with each path on a new line.

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:

$ decaes image.nii --output /path/to/output/folder/ <COMMAND LINE ARGS>

The requested output folder will be created if it does not already exist.

Equivalently, add --output and /path/to/output/folder/ as consecutive lines in your settings file.

Passing image masks

Image masks can be passed into DECAES using the -m or --mask flag:

$ decaes image.nii --mask /path/to/mask.nii <COMMAND LINE ARGS>

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, multiple corresponding mask files can be passed, too:

$ decaes image1.nii image2.mat --mask /path/to/mask1.mat /path/to/mask2.nii.gz <COMMAND LINE ARGS>

Equivalently, add --mask, /path/to/mask1.mat, /path/to/mask2.mat, ... as consecutive lines in your settings file.

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:

$ decaes image.nii --bet <COMMAND LINE ARGS>

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:

$ decaes image.nii --bet --betpath /path/to/bet --betargs -m,-n <COMMAND LINE ARGS>

Note that bet arguments must be passed as a single string to --betargs, separated by commas or spaces, as shown above.

Equivalently, add --bet, --betpath, /path/to/bet, --betargs, -m,-n as consecutive lines in your settings file.