omni_synthunwarp#

Overview#

Example commands#

omni_synthunwarp

Argument types#

In order to run, omni_synthunwarp requires

Required arguments#

-o OUTPUT_PATH, --output_path OUTPUT_PATH

The directory where output files should be stored.

-x T1_DEBIAS, --t1_debias T1_DEBIAS

A T1 image that is bias field corrected.

-y T2_DEBIAS, --t2_debias T2_DEBIAS

A T2 image that is bias field corrected.

-m ANAT_BET_MASK, --anat_bet_mask ANAT_BET_MASK

Brain mask in anatomical space.

-r REF_EPI, --ref_epi REF_EPI

Reference EPI image (Single frame and [0,1] normalized). Should be deobliqued.

-b REF_EPI_BET_MASK, --ref_epi_bet_mask REF_EPI_BET_MASK

Brain mask of reference EPI image.

-e EPI, --epi EPI

The file name of an EPI data set (e.g., task, rest or diffusion weighted). This data set must contain multiple frames. Any desired frame-wise alignment and slice timing correction should already be performed.

Optional arguments#

-i ANAT_EYE_MASK, --anat_eye_mask ANAT_EYE_MASK

Eye mask in anatomical space.

--program PROGRAM (default: fsl)

At various stages of preprocessing different images need to be approximately aligned to one another. For instance, when creating a synthetic image, an initial “guess” for the appropriate affine alignment parameters that bring T1w, T2w and EPI images into approximate registration are required. The user can select between two widely used registration utilities to perform this estimate: FSL’s FLIRT, and AFNI’s 3dAllineate by setting PROGRAM equal to fsl or afni.

--dilation_size DILATION_SIZE (default: 30)

DILATION_SIZE is the size of the structural element used to dilate the anatomical weight mask.

Synthtarget options#

Note

omni_synthunwarp corrects EPI image distortion by non-linearly warping distorted EPI images to align with a high resolution undistorted synthetic EPI image. Creation of the synthetic image is accomplished by the standalone utility omni_synthtarget. The followiing options modify the action of the internal calls to`` omni_synthtarget``.

--initial_synth_model INITIAL_SYNTH_MODEL (default: rbf(0;4)+rbf(1;4)+rbf(0;4)*rbf(1;4))

INITIAL_SYNTH_MODEL is a string describing the radial basis function model used for the initial synthetic EPI image estimate. In an abundance of caution, to avoid potential overfitting early on, we suggest using a relatively simple model for the first estimate.

--final_synth_model FINAL_SYNTH_MODEL (default: rbf(0;12)+rbf(1;12)+rbf(0;12)*rbf(1;12))

FINAL_SYNTH_MODEL is a string that describes the radial basis function model used to construct the final synthetic EPI image.

-p BANDWIDTH, --bandwidth BANDWIDTH (default: 8)

The BANDWIDTH parameter is used to model the difference in effective resolution between typically high resolution source T1w/T2w image and typically low resolution EPI image. BANDWIDTH specifically correspond the bandwidth the Epanachnikov blurring kernel used in the synthetic image model. See omni_synthtarget documentation for more information.

--skip_affine

Enabling this flag will disable affine registration between the the target EPI image and the set of T1w and T2w anatomical images. Why might this option be useful? Well, suppose you are abso-posi-lutely certain that the subject in the scanner did not move at all during data acquisition. Then you could disable affine registration and attempt to measure correct just the distortions caused by field inhomogeneity, and maybe even empirically measure the structure of EPI distortion arising from different sources. Other uses may exist, but probably best to leave this option alone.

--skip_synthtarget_affine

Enabling this flag will disable the affine registration component of the SynthTarget program. This option essentially disables the joint registration component of the SynthTarget algorithm, which alternates finding a solution between the affine parameters and synthetic image regression parameters. Note that this is NOT related to the non-linear transform part of the Synth algorithm.

--resolution_pyramid RESOLUTION_PYRAMID ... (Number of Arguments: ∞) (default: [4, 2, 1])

Internally omni_synthtarget (which creates a synthetic EPI image that is affine aligned to the input EPI) performs its magic working from low to high resolution. This process tends to stabilize estimates by avoiding solutions that are local minima. RESOLUTION_PYRAMID is a list of values describing the isotropic voxel size used at each level of the resolution pyramid.

-d SYNTHTARGET_MAX_ITERATIONS ..., --synthtarget_max_iterations SYNTHTARGET_MAX_ITERATIONS ... (Number of Arguments: ∞) (default: [2000, 500, 100])

Maximum number of optimizing iterations that will be run to estimate the synthetic image model parameters.

--synthtarget_err_tol SYNTHTARGET_ERR_TOL ... (Number of Arguments: ∞) (default: [0.0001, 0.0001, 0.0005])

Typically this value should remain untouched by the users who do not crave adventure. One reason for changing this value is if you have decided not to rescale the target image so that all values lie between 0 and 1.

--synthtarget_step_size SYNTHTARGET_STEP_SIZE ... (Number of Arguments: ∞) (default: [0.001, 0.001, 0.001])

Gradient step size for optimization. Increasing the step size may speed convergence, but may come at the cost of reduced accuracy. Decreasing the step size slows convergence an if MAX_ITERATIONS (-i parameter) is not increased appropriately may result in no convergence at all.

Distortion correction options#

--resample_resolution RESAMPLE_RESOLUTION (default: 1)

Resample resolution space to do warps on (mm). It is recommended you use the same resolution as the anatomical images (T1w/T2w images).

--sigma_t2 SIGMA_T2 (default: 0.5)

Gaussian kernel width expressed in millimeters used to smooth T2w image used for an initial very coarse distortion correcting warp. Before estimating the synthetic EPI image a low spatial resolution warp is used to adjust the EPI image to maximize alignment to the anatomical images. Using a T2w image alone as a target for non-linear warping becomes highly unreliable for detailed corrections. However in our experience, using a T2w image to for an initial low spatial resolution unwarping target slightly increases the quality of the initial estimate of the synthetic EPI (at the very least it doesn’t seem to hurt any).

--initial_warp_field INITIAL_WARP_FIELD

INITIAL_WARP_FIELD is a string specifying the initial warp field used for Synth’s alternating minimization optimization process. It is meant for use as a way of inputting field map estimates to seed Synth’s optimization process.

--distortion_correction_smoothing DISTORTION_CORRECTION_SMOOTHING (default: 2x1x0x0)

Smoothing factors for SyN warp.

--distortion_correction_shrink_factors DISTORTION_CORRECTION_SHRINK_FACTORS (default: 4x3x2x1)

Shrink factors for SyN warp.

--distortion_correction_step_size DISTORTION_CORRECTION_STEP_SIZE ... (Number of Arguments: ∞) (default: [3.0, 1.0, 0.1])

Gradient descent step sizes for distortion correction.

--warp_direction WARP_DIRECTION (default: none)

Warp direction (x, y, z, or none)

Noise mask options#

Note

Properly detecting regions of the EPI data set that are primarily noise (due to signal drop out) is a very important step in generating high quality synthetic EPI image used for distortion correction. The following options allow the user to fine tune certain aspects of the noise region detection process and the resulting noise region weight masks that reduce the contribution of noisy regions when estimating the synthetic EPI image. If the synthetic EPI images produced by omni_synthunwarp are do not appear to you eye to be sufficiently similar to the real EPI data that you are tying to correct, adjusting these parameters may improve things for you.

--noise_mask_iterations NOISE_MASK_ITERATIONS (default: 12)

NOISE_MASK_ITERATIONS is an integer that sets the number of refining iterations used in the the noise mask generating LDA procedure. The initial ‘guess’ for what voxels contain valid signal is typically a binary brain only mask derived from the subjects anatomical images and then aligned to the EPI image. This initial guess is then refined using an iterative temporal linear discriminant analysis approach. In our our experiments a stable noise mask is typically achieved in 8-10 iterations. For good measure, we set the default value just a little higher than this. The appropriate number of iterations may vary depending on the data type (resting state vs diffusion type EPI data) as well as the number of samples (frames) present in the data. If you want to make every second count, you can probably reduce the default without causing too much havoc. If the synthetic images produced by omni_synthpreproc do not appear sufficiently accurate for your tastes, we advise that you look closely at the noise mask volumes that are being estimated for your data set to make sure that voxels that are being labelled as noise are sensible. Do this by loading up the EPI data in your favorite viewer and using the estimated noise mask images as an overlay.

--noise_mask_dilation_size NOISE_MASK_DILATION_SIZE (default: 2)

NOISE_MASK_DILATION_SIZE is an integer value that determines how many voxels to dilate the noise mask before writing it to a file. This option can be used to create more “conservative” noise masks that label voxels as suspect by simply by virtue of their proximity to real noise voxels. It is left to the user to contemplate the morality of this guilt-by-association approach.

-s NOISE_MASK_SIGMA, --noise_mask_sigma NOISE_MASK_SIGMA (default: 2)

NOISE_MASK_SIGMA defines the standard deviation of a Gaussian kernel used to smooth the binary noise mask before writing it to a file. This option is helpful for creating weight volumes rather than simply binary labels. Gaussian smoothing is performed after any noise mask dilation

Other options#

--config_file CONFIG_FILE

A TOML config file that specifies the arguments to use for this program. This provides an alternative way to specify arguments to the program. Note that this file follows the TOML standard: https://toml.io/en/. Arguments set for a particular program should follow under a table heading with the name of the program (e.g. [omni_synthpreproc]). Alternatively, arguments for multiple programs can be set using the [Global] table heading. To generate a config file for this program see the --generate_config option. Note that arguments in the config are loaded in BEFORE arguments specified on the command-line. This means when the same argument is specified in both the command line and the config file, the program will use the argument value specified on the command-line. In addition, if the same argument is provided in the [Global] and [omni_synthpreproc] tables, the argument under [omni_synthpreproc] takes precedence.

--generate_config GENERATE_CONFIG

Path to a location (with .toml extension) to write a config file for this program. This will generate a TOML file with all options set to their current values.

-n NUMBER_OF_THREADS, --number_of_threads NUMBER_OF_THREADS (default: 8)

An integer number representing the number of of threads to use for OpenMP, OpenBLAS, and ITK based components of the program. Generally a larger number is better if you can manage it, but past 16 or so there may be diminishing returns.

-v, --version

Show program’s version and exit.

-h, --help

show this help message and exit