omni_pipeline#

Overview#

Example commands#

# Example 1
omni_pipeline [Dataset] [Output]

Argument types#

Required arguments#

bids_path

The directory with the input dataset formatted according to the BIDS standard.

output_path

The directory where output files should be stored.

Optional arguments#

--participant_label PARTICIPANT_LABEL ... (Number of Arguments: ∞)

The label(s) of the participant(s) that should be analyzed. The label corresponds to sub-<participant_label> from the BIDS spec (so it does not include “sub-“). If this parameter is not provided all subjects should be analyzed. Multiple participants can be specified with a space separated list.

--dryrun

Run pipeline without any outputs.

--single_rest_run

Replicates the paper and does only single rest run per subject.

--combine_sessions

Combine sessions if a session is missing an anatomical image.

--skip_validation

Skip validation of BIDS input.

--database DATABASE

Set database path for BIDS input (Default is to use BIDS input path).

--reset_database

Delete BIDS database files if they exist.

--skip_database

Skip database construction.

--log_file LOG_FILE

LOG_FILE is the path to a text file chronicling the details of each inevitably successful step along your path to registration nirvana.

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

--ref REF (default: T1)

REF sets which anatomical image is used as the reference image during registration. Valid options are ‘T1’ or ‘T2’.

Image debiasing options#

Note

Intensity bias fields affecting anatomical T1w/T2w images or the EPI images can significantly and negatively affect the quality of synthetic EPI images created to correct EPI distortion using the Synth field map-less approach. It is very important that bias fields be removed effectively, at least during the registration and distortion correction process. The following parameters can be used to tailor the BSpline model used to estimate and remove intensity bias.

Because creating synthetic EPI images relies on finding a mapping between voxel intensities of T1w/T2w source images and a EPI target image, any intensity bias remaining in the images can reduce the accuracy of the synthetic image. Be mindful that over fitting the bias field can also mess up the intensity mapping relationship. Over fitting is most likely to occur by allowing too many knots in the spline model, or placing them too closely together. The telltail sign that this has occurred is when the debiased images look like they have been highpass filtered, like they lack all low spatial frequency information. If this happens, try increasing the distance between spline knots (parameterized by the first number in the debais_params_anat and debias_params_func strings). Typing N4BiasFieldCorrection -h in the command line is also going to be very helpful.

--debias_params_anat DEBIAS_PARAMS_ANAT (default: [100,3,1x1x1,3])

DEBIAS_PARAMS_ANAT is a string representing BSpline model parameters used to estimate the low spatial frequency intensity modulating bias field present in the T1w and T2w anatomical images. The N4BiasFieldCorrection algorithm is used to estimate this bias field. The DEBIAS_PARAMS_ANAT string is passed directly into the -b parameter of the N4BiasFieldCorrection utility. Type N4BiasFieldCorrection -h in the command line for more information on this parameter.

--debias_params_func DEBIAS_PARAMS_FUNC (default: [200,3,3x3x3,3])

DEBIAS_PARAMS_FUNC is a string representing BSpline model parameters used to estimate the low spatial frequency intensity modulating bias field present in the EPI images. The DEBIAS_PARAMS_FUNC string is passed directly into the -b parameter of the N4BiasFieldCorrection utility. Type N4BiasFieldCorrection -h in the command line for more information on this parameter.

Binary brain mask options#

Note

omni_pipeline makes heavy use of binary brain masks at multiple stages during preprocessing. For instance, a binary anatomical brain mask aligned to the EPI images plays a key role as an initial estimate for which voxels contain valid signal and which ones are likely to contain noise when constructing signal-to-noise masks. It also contributes to a weight volume that increases the importance of brain voxels when creating the synthetic EPI image used in field map-less distortion correction.

--bet_method BET_METHOD (default: Norm)

When BET_METHOD is T1, the subjects T1w image is used to create the binary brain mask, using the BET tool. When BET_METHOD is Norm, the voxel-wise Euclidean norm of the (normalized and pre-aligned) T1w and T2w (sqrt(T1w.^2 + T2w.^2))) images is used as input to the BET tool.

Note

We have observed in some data sets (particularly for subjects with large lesions) BET masks based on the T1w image can exhibit significant errors. Accuracy is much improved when the composite image produced by enabling the ‘Norm’ option are used as inputs to BET. In our test, this approach is quite reliable, but if your brain masks look odd, try switching back to the T1 option.

--fractional_intensity_threshold_anat FRACTIONAL_INTENSITY_THRESHOLD_ANAT (default: 0.5)

FRACTIONAL_INTENSITY_THRESHOLD_ANAT is a key parameter used in creating binary brain masks using the BET and BET2 utilities. This option sets the fractional intensity threshold used for the anatomical images selected by the --bet_method option. For more information type ‘bet -h’ in the command line.

--fractional_intensity_threshold_func FRACTIONAL_INTENSITY_THRESHOLD_FUNC (default: 0.5)

FRACTIONAL_INTENSITY_THRESHOLD_FUNC sets the threshold used by the BET utility when creating a binary brain mask for the distorted EPI data sets. Type bet -h in the command line for more information.

Simultaneous slice time and motion correction options#

Note

omni_pipeline can use either 3dAllineate or SpaceTimeRealign for motion correction.

The SpaceTimeRealign algorithm to implement simultaneous slice time and motion correction. Corrections produced by this algorithm appear to be very high quality, but in its present single-threaded form it can be quite time consuming to run. The following options allow the user to tailor the performance of the SpaceTimeRealign algorithm to suit their tolerance for delay and thumb-twiddling.

SpaceTimeRealign aligns frames using a subsample pyramid resolution scheme, performing coarse alignment at low resolution and fine alignment at high resolution. At each resolution level the alignments can be refined over a variable number of ‘loops’. Processing time can be reduced by decreasing the number of refining loops for each resolution level or choosing a coarser highest resolution.

Example: omni_pipeline ... --subsample 5 3 2 --loops 3 2 1 .... would perform three alignment refining iterations at 5x subsample; two iterations at 3x subsample; and one iteration at 1x sampling resolution (native EPI resolution)

--moco MOCO (default: allineate)

Motion correction method to use. Current options are allineate and realign4d. 3dAllineate is much faster than realign4d, but does not do slice time correction.

-l LOOPS ..., --loops LOOPS ... (Number of Arguments: ∞) (default: [1, 1, 1])

The LOOPS parameter is a list of integers (the same size as the list of integers used for the --subsample parameter) that dictates the number of refining iterations at the corresponding subsampling resolution.

--subsample SUBSAMPLE ... (Number of Arguments: ∞) (default: [5, 3, 1])

SUBSAMPLE is a list of integers (at least one value) describing the subsampling sequence used when performing simultaneous slice time and motion correction. The number of elements in this list of integers must match the number of integers used for the -l or --loops parameters.

--borders BORDERS ... (Number of Arguments: 3) (default: [1, 1, 1])

Sets the border width for SpaceTimeRealign.

Synthtarget options#

Note

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

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

Atlas options#

--data_resolution DATA_RESOLUTION

A number representing the desired isotropic dimensions in millimeters of the final output data set. Not setting DATA_RESOLUTION uses the native resolution of the input EPI data as the resolution of the final aligned output.

--atlas ATLAS (default: mni)

ATLAS selects the final image space to which output data are aligned. Available built-ins are mni and trio. You can also specify a path to atlas file, but you will also need to specify the atlas_label argument. When this argument is omitted, the MNI atlas is selected.

--atlas_label ATLAS_LABEL (default: atlas)

Label suffix for atlas aligned files in output when a custom path is specified.

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_pipeline]). 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_pipeline] tables, the argument under [omni_pipeline] 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