CLI index

MDT

Launches the MDT Graphical User Interface.

usage: MDT [-h] [-d dir]

Named Arguments

-d, --dir

the base directory for the file choosers

mdt-apply-mask

Mask the background using the given mask.

This function multiplies a given volume (or list of volumes) with a binary mask.

usage: mdt-apply-mask [-h] [--overwrite] mask input_files [input_files ...]

Positional Arguments

mask	the (brain) mask to use
input_files	The input images to use

Named Arguments

--overwrite

Overwrite the original images, if not set we create an output file. Default: False

Example of use:

mdt-apply-mask data.nii.gz -m roi_mask_0_50.nii.gz
mdt-apply-mask *.nii.gz -m my_mask.nii.gz

mdt-batch-fit

Fits a batch profile to a set of data.

This script can be used to fit multiple models to multiple datasets. It needs a batch profile with information about the subjects. If no batch profile is given, this routine will try to auto-detect a good batch profile.

The most general batch profile is the ‘DirPerSubject’ profile which assumes that every subject has its own subdirectory under the given data folder. For details, please look up the batch profiles in your home folder.

A few of the batch profile settings can be altered with arguments to this script. For example, use_gradient_deviations and models_to_fit override the values in the batch profile.

usage: mdt-batch-fit [-h] [-o OUTPUT_FOLDER] [-b {}]
                     [--cl-device-ind [{} [{} ...]]] [--recalculate]
                     [--no-recalculate] [--use-gradient-deviations]
                     [--no-gradient-deviations] [--double] [--float]
                     [--subjects-index [SUBJECTS_INDEX [SUBJECTS_INDEX ...]]]
                     [--subjects-id [SUBJECTS_ID [SUBJECTS_ID ...]]]
                     [--dry-run] [--tmp-results-dir TMP_RESULTS_DIR]
                     data_folder [models_to_fit [models_to_fit ...]]

Positional Arguments

data_folder	the directory with the subject to fit
models_to_fit	The models to fit

Named Arguments

-o, --output_folder
	the directory for the output, defaults to an output dir next to the input dir.
-b, --batch_profile
	The batch profile (by name) to use during fitting. If not given abatch profile is auto-detected.
--cl-device-ind
	The index of the device we would like to use. This follows the indices in mdt-list-devices and defaults to the first GPU.
--recalculate	Recalculate the model(s) if the output exists. Default: False
--no-recalculate
	Do not recalculate the model(s) if the output exists. (default) Default: False
--use-gradient-deviations
	Uses the gradient deviations. If not set, the default in the profile is used.
--no-gradient-deviations
	Disable the use of gradient deviations. If not set, the default in the profile is used.
--double	Calculate in double precision. Default: False
--float	Calculate in single precision. (default) Default: False
--subjects-index
	The indices of the subjects we would like to fit. This reduces the set of subjects.
--subjects-id	The id of the subjects we would like to fit. This reduces the set of subjects.
--dry-run	Shows what it will do without the dry run argument. Default: False
--tmp-results-dir
	The directory for the temporary results. The default (“True”) uses the config file setting. Set to the literal “None” to disable. Default: “True”

Example of use:

mdt-batch-fit . NODDI
mdt-batch-fit /data/mgh 'BallStick_r1' --batch-profile 'HCP_MGH'
mdt-batch-fit . CHARMED_r1 --subjects-id 1003 1004 --subjects-index 0 1 2
mdt-batch-fit . BallStick_r1 Tensor --dry-run

mdt-create-bvec-bval

Generate the bval and bvec file from a protocol file.

usage: mdt-create-bvec-bval [-h] protocol [bvec] [bval]

Positional Arguments

protocol	the protocol file
bvec	the output bvec file
bval	the output bvec file

Example of use:

mdt-create-bvec-bval my_protocol.prtcl
mdt-create-bvec-bval my_protocol.prtcl bvec_name.bvec bval_name.bval

mdt-create-mask

Create a (brain) mask for the given DWI. This uses the median-otsu algorithm.

usage: mdt-create-mask [-h] [-o OUTPUT_NAME] [--median-radius MEDIAN_RADIUS]
                       [--mask-threshold MASK_THRESHOLD] [--numpass NUMPASS]
                       [--dilate DILATE] [--cl-device-ind [{} [{} ...]]]
                       dwi protocol

Positional Arguments

dwi	the diffusion weighted image
protocol	the protocol file, see mdt-create-protocol

Named Arguments

-o, --output-name
	the filename of the output file. Default is <dwi_name>_mask.nii.gz
--median-radius
	Radius (in voxels) of the applied median filter (default 4). Default: 4
--mask-threshold
	Everything below this b-value threshold is masked away (value in s/m^2, default 0) Default: 0
--numpass	Number of pass of the median filter (default 4). Default: 4
--dilate	Number of iterations for binary dilation (default 1). Default: 1
--cl-device-ind
	The index of the device we would like to use. This follows the indices in mdt-list-devices and defaults to the first GPU.

Example of use:

mdt-create-mask data.nii.gz data.prtcl
mdt-create-mask data.nii.gz data.prtcl -o data_mask.nii.gz
mdt-create-mask data.nii.gz data.prtcl -o data_mask.nii.gz --median-radius 2

mdt-create-protocol

Create a protocol from a bvec and bval file.

MDT uses a protocol file (with extension .prtcl) to store all the acquisition related values. This is a column based file which can hold, next to the b-values and gradient directions, the big Delta, small delta, gradient amplitude G and more of these extra acquisition details.

usage: mdt-create-protocol [-h] [-s BVAL_SCALE_FACTOR] [-o OUTPUT_FILE]
                           [--sequence-timing-units {ms,s}] [--G G]
                           [--maxG MAXG] [--Delta DELTA] [--delta DELTA]
                           [--TE TE] [--TR TR]
                           bvec bval

Positional Arguments

bvec	the gradient vectors file
bval	the gradient b-values

Named Arguments

-s, --bval-scale-factor
	We expect the b-values in the output protocol in units of s/m^2. Example use: 1 or 1e6. The default is autodetect.
-o, --output_file
	the output protocol, defaults to “<bvec_name>.prtcl” in the same directory as the bvec file.
--sequence-timing-units
	Possible choices: ms, s The units of the sequence timings. The default is ‘ms’ which we will convert to ‘s’. Default: “ms”
--G	The gradient amplitudes in T/m.
--maxG	The maximum gradient amplitude in T/m. This is only useful if we need to guess big Delta and small delta. Default is 0.04 T/m
--Delta	The big Delta to use, either a single number or a file with either a single number or one number per gradient direction.
--delta	The small delta to use, either a single number or a file with either a single number or one number per gradient direction.
--TE	The TE to use, either a single number or a file with either a single number or one number per gradient direction.
--TR	The TR to use, either a single number or a file with either a single number or one number per gradient direction.

Example of use:

mdt-create-protocol data.bvec data.bval
mdt-create-protocol data.bvec data.bval -o my_protocol.prtcl
mdt-create-protocol data.bvec data.bval
mdt-create-protocol data.bvec data.bval --Delta 30 --delta 20
mdt-create-protocol data.bvec data.bval --sequence-timing-units 's' --Delta 0.03
mdt-create-protocol data.bvec data.bval --TE ../my_TE_file.txt

Additional columns can be specified using the syntax: “–{column_name} {value}” structure. Please note that these additional values will not be auto-converted from ms to s.

mdt-create-roi-slice

Create a single slice mask that only includes the voxels in the selected slice.

usage: mdt-create-roi-slice [-h] [-d DIMENSION] [-s SLICE] [-o OUTPUT_NAME]
                            mask

Positional Arguments

mask	the mask to select a slice from

Named Arguments

-d, --dimension
	The dimension to index (0, 1, 2, …). Default is 2.
-s, --slice	The slice to use in the selected dimension (0, 1, 2, …).Defaults to center of chosen dimension.
-o, --output-name
	the filename of the output file. Default is <mask_name>_<dim>_<slice>.nii.gz

Example of use:

mdt-create-roi-slice mask.nii.gz
mdt-create-roi-slice mask.nii.gz -d 1 -s 50
mdt-create-roi-slice mask.nii.gz -d 1 -s 50 -o my_roi_1_50.nii.gz

mdt-estimate-noise-std

Estimate the noise standard deviation of the Gaussian noise in the original complex image domain.

The result is a single floating point number with the noise std. for every voxel. It uses the estimation routines from the components folders for the estimation. The estimation is the same as the one used in mdt-model-fit, but since the noise std estimation depends on the mask used, it is better to call this function beforehand with a complete brain mask. Later, the mdt-model-fit routine can be called on smaller masks with as noise std the value from this function.

usage: mdt-estimate-noise-std [-h] dwi protocol mask

Positional Arguments

dwi	the diffusion weighted image
protocol	the protocol file, see mdt-create-protocol
mask	the (brain) mask to use

Example of use:

mdt-estimate-noise-std data.nii.gz data.prtcl full_mask.nii.gz

mdt-get-example-data

Get the MDT example data that is accompanying the installation.

This will write the MDT example data (b1k_b2k and b6k datasets) to the indicated directory. You can use this data for testing MDT on your computer. These example datasets are contained within the MDT package and as such are available on every machine with MDT installed.

usage: mdt-get-example-data [-h] [dir]

Positional Arguments

dir	the output directory

Example of use:

mdt-get-example-data
mdt-get-example-data .

mdt-gui

Launches the MDT Graphical User Interface.

usage: mdt-gui [-h] [-d dir]

Named Arguments

-d, --dir

the base directory for the file choosers

mdt-info-img

Print some basic information about an image file.

usage: mdt-info-img [-h] images [images ...]

Positional Arguments

images

The input images

Example of use:

mdt-info-img my_img.nii
mdt-info-img *.nii

mdt-info-protocol

Print some basic information about a protocol.

usage: mdt-info-protocol [-h] protocol

Positional Arguments

protocol

the protocol file

Example of use:

mdt-info-protocol my_protocol.prtcl

mdt-init-user-settings

This script is meant to update your home folder with the latest MDT models.

The location we will write to is: ~/.mdt (where ~ stands for your home folder).

usage: mdt-init-user-settings [-h] [--pass-if-exists] [--always-overwrite]

Named Arguments

--pass-if-exists
	do nothing if the config dir exists (default) Default: False
--always-overwrite
	always overwrite the config directory with the default settings Default: False

mdt-list-devices

This script prints information about the available devices on your computer.

usage: mdt-list-devices [-h] [-l]

Named Arguments

-l, --long

print all info about the devices Default: False

mdt-list-models

This script prints a list of all the models MDT can find in your home directory.

usage: mdt-list-models [-h] [-l]

Named Arguments

-l, --long

print the descriptions Default: False

mdt-math-img

Evaluate an expression on a set of images.

This is meant to quickly convert/combine one or two maps with a mathematical expression. The expression can be any valid python expression.

The input list of images are loaded as numpy arrays and stored in the array ‘input’ and ‘i’. Next, the expression is evaluated using the input images and the result is stored in the indicated file(s).

In the expression you can either use the arrays ‘input’ or ‘i’ with linear indices, or/and you can use alphabetic characters for each image. For example, if you have specified 2 input images you can address them as:

• input[0] or i[0] or a
• input[1] or i[1] or b

This linear alphabetic indexing works with every alphabetic character except for the ‘i’ since that one is reserved for the array.

The module numpy is available under ‘np’ and some functions of MDT under ‘mdt’. This allows expressions like:

np.mean(np.concatenate(i, axis=3), axis=3)

to get the mean value per voxel of all the input images.

It is possible to change the mode of evaluation from single expression to a more complex python statement using the switch –as-statement (the default is –as-expression). In a statement more complex python commands are allowed. In statement mode you must explicitly output the results using ‘return’. (Basically it wraps your command in a function, of which the output is used as expression value).

If no output file is specified and the output is of dimension 2 or lower we print the output directly to the console. If the output is a list or tuple instead of an ndarray we will write every element of that sequence as a separate file. This will use the indicated file as basename and append an numerical index to it.

usage: mdt-math-img [-h] [-e] [-s] [-o OUTPUT_FILE] [-w] [-4d] [--verbose]
                    input_files [input_files ...] expr

Positional Arguments

input_files	The input images to use
expr	The expression/statement to evaluate.

Named Arguments

-e, --as-expression
	Evaluates the given string as an expression (default). Default: True
-s, --as-statement
	Evaluates the given string as an statement. Default: True
-o, --output-file
	the output file, if set we write to this specific file
-w, --write	write the results Default: False
-4d, --input-4d
	Add a singleton dimension to all input 3d maps to make them 4d, this prevents some broadcast issues. Default: False
--verbose, -v	Verbose, prints runtime information Default: False

Example of use:

mdt-math-img fiso.nii ficvf.nii '(1-input[0]) * i[1]' -o Wic.w.nii.gz
mdt-math-img fiso.nii ficvf.nii '(1-a) * b' -o Wic.w.nii.gz
mdt-math-img *.nii.gz 'np.mean(np.concatenate(i, axis=3), axis=3)' -o output.nii.gz
mdt-math-img FA.nii.gz 'np.mean(a)'
mdt-math-img FA.nii white_matter_mask.nii 'np.mean(mdt.create_roi(a, b))'
mdt-math-img images*.nii.gz mask.nii 'list(map(lambda f: np.mean(mdt.create_roi(f, i[-1])), i[0:-1]))'
mdt-math-img FA.nii.gz
mdt-math-img timeseries.nii '[a[..., ind] for ind in range(a.shape[-1])]' -o split.nii

mdt-math-protocol

Evaluate an expression on a protocol.

This is meant to quickly change a protocol using mathematical expressions. The expressions can be any valid python string separated if needed with the semicolon (;).

The columns of the input protocol are loaded and stored as arrays with as variable names the names of the columns. Next, the expression is evaluated on those columns and the result is stored in the indicated file.

Columns can easily be removed with the python ‘del’ command. New columns can easily be added by assignment. When adding a column, the value can either be a scalar or a vector.

Additionally, the numpy library is available with prefix ‘np.’.

usage: mdt-math-protocol [-h] [-o OUTPUT_FILE] [-a ADDITIONAL_FILES]
                         input_protocol expr

Positional Arguments

input_protocol	The input protocol
expr	The expression to evaluate.

Named Arguments

-o, --output_file
	the output protocol, defaults to the input protocol.
-a, --additional-file
	additional file to load to be used for columns, placed in ‘files’ list by index

Example of use:

mdt-math-protocol protocol.prtcl 'G *= 1e-3' -o new_protocol.prtcl
mdt-math-protocol p.prtcl 'G *= 1e-3; TR /= 1000; TE /= 1000'
mdt-math-protocol p.prtcl 'del(G)'
mdt-math-protocol p.prtcl 'TE  = 50e-3'
mdt-math-protocol p.prtcl -a Delta.txt 'Delta = files[0]'

mdt-model-fit

Fit one of the models to the given data.

This function can use two kinds of noise standard deviation, a global or a local (voxel wise). If the argument -n / –noise-std is not set, MDT uses a default automatic noise estimation which may be either global or local. To use a predefined global noise std please set the argument to a floating point value. To use a voxel wise noise std, please give it a filename with a map to use.

usage: mdt-model-fit [-h] [-o OUTPUT_FOLDER] [-n NOISE_STD]
                     [--gradient-deviations GRADIENT_DEVIATIONS]
                     [--cl-device-ind [{} [{} ...]]] [--recalculate]
                     [--no-recalculate] [--dont-use-cascaded-inits]
                     [--use-cascaded-inits]
                     [--method {Powell,Nelder-Mead,Levenberg-Marquardt,Subplex}]
                     [--patience PATIENCE] [--double] [--float]
                     [--tmp-results-dir TMP_RESULTS_DIR]
                     [--config-context CONFIG_CONTEXT]
                     [--extra-protocol EXTRA_PROTOCOL [EXTRA_PROTOCOL ...]]
                     model dwi protocol mask

Positional Arguments

model	model name, see mdt-list-models
dwi	the diffusion weighted image
protocol	the protocol file, see mdt-create-protocol
mask	the (brain) mask to use

Named Arguments

-o, --output_folder
	the directory for the output, defaults to “output/<mask_name>” in the same directory as the dwi volume
-n, --noise-std
	the noise std, defaults to None for automatic noise estimation.Either set this to a value, or to a filename.
--gradient-deviations
	The volume with the gradient deviations to use, in HCP WUMINN format.
--cl-device-ind
	The index of the device we would like to use. This follows the indices in mdt-list-devices and defaults to the first GPU.
--recalculate	Recalculate the model(s) if the output exists. (default) Default: True
--no-recalculate
	Do not recalculate the model(s) if the output exists. Default: True
--dont-use-cascaded-inits
	Do not initialize the model with a better starting point. Default: True
--use-cascaded-inits
	Initialize the model with a better starting point (default). Only works for default MDT models. Default: True
--method	Possible choices: Powell, Nelder-Mead, Levenberg-Marquardt, Subplex The optimization method to use, defaults to Powell. Default: “Powell”
--patience	The patience for the optimization routine
--double	Calculate in double precision. Default: False
--float	Calculate in single precision. (default) Default: False
--tmp-results-dir
	The directory for the temporary results. The default (“True”) uses the config file setting. Set to the literal “None” to disable. Default: “True”
--config-context
	The configuration context to use during fitting the model. Same syntax as config files
--extra-protocol
	Additional protocol values, provide as <key>=<value> pairs

Example of use:

mdt-model-fit BallStick_r1 data.nii.gz data.prtcl roi_mask_0_50.nii.gz
mdt-model-fit ... --cl-device-ind 1
mdt-model-fit ... --cl-device-ind {0, 1}
mdt-model-fit ... --extra-protocol T1=T1_map.nii.gz T2=10

mdt-view-maps

Launches the MDT maps visualizer.

usage: mdt-view-maps [-h] [-c CONFIG] [-m] [--to-file TO_FILE] [--width WIDTH]
                     [--height HEIGHT] [--dpi DPI]
                     [items [items ...]]

Positional Arguments

items

the directory or file(s)

Named Arguments

-c, --config	Use the given initial configuration
-m, --maximize	Maximize the shown window Default: False
--to-file	If set, export the figure to the given filename
--width	The width of the output file when –to-file is set
--height	The height of the output file when –to-file is set
--dpi	The dpi of the output file when –to-file is set

mdt-volume-merge

Merge a list of volume images on the 4th dimension. Writes the result to a single image.

Please note that by default this will sort the list of volume names based on a natural key sort. This is the most convenient option in the case of globbing files. You can disable this behaviour using the flag –no-sort.

usage: mdt-volume-merge [-h] -o OUTPUT_FILE [--sort] [--no-sort]
                        [--no-merge-order-file]
                        input_files [input_files ...]

Positional Arguments

input_files

The input images to merge

Named Arguments

-o, --output_file
	the filename of the output file
--sort	Sort the input images using a natural sort (default) Default: True
--no-sort	Do not sort the input images Default: True
--no-merge-order-file
	Do not write the merge order file Default: False

Example of use:

mdt-volume-merge merged.nii.gz *.nii.gz
mdt-volume-merge --no-sort merged.nii.gz *.nii.gz