sct_fmri_moco

Motion correction of fMRI data. Some robust features 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 fMRI volumes

  • the time average of the corrected fMRI volumes

  • 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_fmri_moco -i <file> [-g <int>] [-m <file>] [-ref <file>]
                     [-param <list>] [-ofolder <folder>] [-x {nn,linear,spline}]
                     [-qc <folder>] [-qc-seg <file>] [-qc-fps <float>]
                     [-qc-dataset <str>] [-qc-subject <str>] [-dl] [-h]
                     [-v <int>] [-r {0,1}]

MANDATORY ARGUMENTS

-i

Input data (4D). Example: fmri.nii.gz

OPTIONAL ARGUMENTS

-g

Group nvols successive fMRI 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: 1

-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.

Default: ''

-ref

Reference volume for motion correction, for example the mean fMRI 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=0.

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

  • 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). Not used if -ref is provided. Default=0.

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

-ofolder

Output path.

Default: '.'

-x

Possible choices: nn, linear, spline

Final interpolation.

Default: 'linear'

-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