sct_dmri_moco

Motion correction of dMRI data. Some of the features to improve robustness were proposed in Xu et al. (https://dx.doi.org/10.1016/j.neuroimage.2012.11.014) and include:

  • group-wise (-g)

  • slice-wise regularized along z using polynomial function (-param poly). For more info about the method, type: isct_antsSliceRegularizedRegistration

  • masking (-m)

  • iterative averaging of target volume

  • Optional DL-based motion correction (-dl)

The outputs of the motion correction process are:

  • the motion-corrected dMRI volumes

  • the time average of the corrected dMRI volumes with b == 0

  • the time average of the corrected dMRI volumes with b != 0

  • a time-series with 1 voxel in the XY plane, for the X and Y motion direction (two separate files), as required for FSL analysis.

  • a TSV file with one row for each time point, with the slice-wise average of the motion correction magnitude for that time point, that can be used for Quality Control.

usage: sct_dmri_moco -i <file> -bvec <file> [-bval <file>] [-bvalmin <float>]
                     [-g <int>] [-m <file>] [-ref <file>] [-param <list>]
                     [-x {nn,linear,spline}] [-ofolder <folder>] [-qc <folder>]
                     [-qc-seg <file>] [-qc-fps <float>] [-qc-dataset <str>]
                     [-qc-subject <str>] [-dl] [-h] [-v <int>] [-r {0,1}]

MANDATORY ARGUMENTS

-i

Diffusion data. Example: dmri.nii.gz

-bvec

Bvecs file. Example: bvecs.txt

OPTIONAL ARGUMENTS

-bval

Bvals file. Example: bvals.txt

Default: ''

-bvalmin

B-value threshold (in s/mm2) below which data is considered as b=0.

Default: 100

-g

Group nvols successive dMRI volumes for more robustness. Values 2 or greater will create groups of that size, while a value of 1 will turn off grouping (i.e. per-volume motion correction).

Default: 3

-m

Binary mask to limit voxels considered by the registration metric. You may also provide a softmask (nonbinary, [0, 1]), and it will be binarized at 0.5. Example: dmri_mask.nii.gz

Default: ''

-ref

Reference volume for motion correction, e.g., mean DWI or mean b=0 volume.

Default: ''

-param

Advanced parameters. Assign value with =; Separate arguments with ,.

  • poly [int]: Degree of polynomial function used for regularization along Z. For no regularization set to 0. Default=2.

  • smooth [mm]: Smoothing kernel. Default=1.

  • metric {MI, MeanSquares, CC}: Metric used for registration. Default=MI.

  • iter [int]: Number of iterations. Default=10.

  • gradStep [float]: Searching step used by registration algorithm. The higher the more deformation allowed. Default=1.

  • sampling [None or 0-1]: Sampling rate used for registration metric. Default=None.

  • num_target [int]: Target volume or group (starting with 0). Default=0.

  • iterAvg [int]: Iterative averaging: Target volume is a weighted average of the previously-registered volumes. Default=1.

-x

Possible choices: nn, linear, spline

Final interpolation.

Default: 'spline'

-ofolder

Output folder.

Default: ''

-qc

The path where the quality control generated content will be saved. (Note: Both -qc and -qc-seg are required in order to generate a QC report.)

-qc-seg

Segmentation of spinal cord to improve cropping in qc report. (Note: Both -qc and -qc-seg are required in order to generate a QC report.)

-qc-fps

This float number is the number of frames per second for the output gif images.

Default: 5

-qc-dataset

If provided, this string will be mentioned in the QC report as the dataset the process was run on.

-qc-subject

If provided, this string will be mentioned in the QC report as the subject the process was run on.

-dl

Use deep learning–based motion correction (DenseNet).

  • Requires the -m argument (binary spinal cord mask). The binary mask (3D) defines the spinal cord region used by the model to estimate motion within the mask. It should be large enough to cover the full extent of the spinal cord in the image. DISCLAIMER: This preliminary method has not been thoroughly validated therefore we cannot guarantee it will work well on your data. We suggest you compare the performance with/without the -dl method, and pick the best for your data.

Default: False

MISC ARGUMENTS

-v

Possible choices: 0, 1, 2

Verbosity. 0: Display only errors/warnings, 1: Errors/warnings + info messages, 2: Debug mode.

Default: 1

-r

Possible choices: 0, 1

Remove temporary files.

Default: 1