omni_synthtarget#

Overview#

The SynthTarget algorithm. Solves the joint synthetic transformation/affine registration problem. See algorithm 1 of the Synth paper.

Example commands#

# Example 1
omni_synthtarget EPI.nii.gz 'rbf(0;4)+rbf(1;10)' Tw1.nii.gz T2w.nii.gz

# Example 2
Somni_synthtarget EPI.nii.gz 'rbf(0;5)+rbf(1;5)' Tw1.nii.gz T2w.nii.gz \
-p 16 -c -u ToneCurveMask.nii.gz

Argument types#

In order to run, omni_synthtarget requires a minimum of three positional input arguments.

Required arguments#

target_image

The first positional argument consists of a file name for an image that will be approximated by a synthetic image. This will most likely be a single reference EPI image taken from a resting state, task, or diffusion weighted data set.

Note

The presence of extreme intensity outliers in either the target image or the set of input images can reduce the performance of quality of synthetic images produced by SynthTarget. We recommend that input images be “despiked” prior to use. One approach to this is to measure the distribution of voxel intensities and “clip” extreme values that exceed some statistical threshold, say 3 standard deviations. Alternatively images can be run through an appropriate sigmoidal softmax function to compress extreme values. Other spatial denoising approaches may prove superior to either of these methods.

Note

It is highly recommended that the target image is rescaled so that the minimum value at any voxel is 0 and the highest value is 1. While synth_target will happily run without that rescaling, the default values for error tolerances and gradient step size are unlikely to be optimal and model convergence will be something of a crapshoot.

Note

We recommend that all images used for the target_image or as an input_image be properly debiased. The presence of bias fields can have a significant and deleterious effect on the accuracy of synthetic image estimation. If the synthetic image output looks wacky, closely examining the images for residual low spatial frequency intensity modulation should be one of the first troubleshooting steps taken. In the current pipeline, synthpreproc, we use N4BiasFieldCorrection to accomplish this. Often the knot spacing on the default spline model must be adjusted to be appropriate for the input data set.

Note

Image contrast for T1w, T2w and EPI images can vary greatly depending on acquisition parameters. For situations in which image contrast is low –that is when the differences between the average intensities of voxels representing different tissues and fluids are minimal– one can run into a problem with the radial basis function decomposition in which the majority of the image is represented by a single radial basis function component. In this situation the resulting model is not flexible enough to correctly model the intensity mapping relationship between source and target images. A solution could be to increase the order of the radial basis function decomposition, effectively increasing the number of intensity bins to divide that divide up the source images. However, going this route so can also significantly increase memory usage and slow performance. Often, a better solution is to perform a histogram normalization step on the source and target images. This procedure essentially “stretches” the distribution of voxel intensities in the images so that they are more evenly spaced along the interval of maximum and minimum values. Histogram normalized images can be more effectively decomposed by a given number of radial basis function components. We recommend that this procedure, or something similar, be applied to all images used as input to SynthTarget.

interaction_model

The second positional argument is a string enclosed by single quotations specifying the radial basis function model that will be used to construct the synthetic image from the input and target images.

Example 1: A simple case in which a single input image is used to construct a synthetic target image using a six component radial basis function decomposition: ‘rbf(0;6)’

Here the ‘rbf’ refers to the kind of intensity model to be used (radial basis function), the zero refers to the source image to which the the RBF decomposition is applied, the 6 refers to the number of radial basis function components (evenly spaced intensity bins) to use.

Example 2: A case in which two input images are used to construct the synthetic target image. The first input image is decomposed into 12 radial basis function components and the second image is decomposed into 4 radial basis function components: ‘rbf(0;12) + rbf(1;4)’

Example 3: A case in which two input images are used to construct the synthetic target image. The first image is decomposed into 4 radial basis components and the second is decomposed into 7 components. This time, we wish to model potential interactions between the two input images. Conceptually, this allows for the intensity mapping between one input image and the target image to vary as a function of the voxel intensity of the second input image: ‘rbf(0;4)+rbf(1;7)+rbf(0;4)*rbf(1;7)’

input_images (Number of Arguments: ∞)

The last, is a list of target image file names. The images represented in these files contains the information that will be used in order to construct the synthetic image. The most common (but certainly not the only) use case is likely to involve construction a synthetic EPI image from information contained in a subject’s pre-aligned T1w and T2w anatomical images.

Optional arguments#

-w REGRESSION_WEIGHT_MASK, --regression_weight_mask REGRESSION_WEIGHT_MASK

A file name representing a user-specified regression weight image that is used to reduce the contribution of noisy or highly distorted areas of the image when constructing the synthetic image. This file should contain a single image with the same dimensions as the those that make up those used as input images. Higher values indicate that a voxel should contribute more to the synthetic image estimate.

For example: often regions of an EPI image exhibit significant signal dropout or distortion. When used as a target image, a problem arises because, even when an undistorted input image and a target image are reasonably well aligned, there are some areas where there is no true correspondence between the images, e.g., frontal polar or inferotemporal field map distortion, or just plain old signal dropout in the EPI. By downweighting these regions with the regresson mask, their influence on the synthetic image estimate is reduced.

While the user is free to construct whatever weight volume best serves their purposes, a good place to start is with the omni_synthnoisemask utility, which takes care of a great deal of the legwork and book keeping required to create a good weight image.

-a AFFINE, --affine AFFINE

Initial affine transform to use for optimization.

-o OUTPUT_PREFIX, --output_prefix OUTPUT_PREFIX

SynthTarget estimates affine alignment parameters that optimally register source and target images. A text file containing the affine matrix is saved as OUTPUT_PREFIX.affine. A text file containing the coefficients for the radial basis function model that produces the synthetic image is saved as OUTPUT_PREFIX.regress.

A pre-existing affine matrix may be useful in the following situations:

  1. It can be used as an initial estimate for another iteration of SynthTarget (see -a option).

  1. It can be used as an unchanging affine alignment solution when re-estimating a synthetic image (-a option combined with –no_register flag). This can be particularly useful when re-estimating a synthetic image from a partially undistorted target image. For example, suppose you have created an initial synthetic target image based on an orignal distorted target image. You then correct the distortion by some amount using your favorite non-linear warping software. You can then re-estimate an improved synthetic image based on the partially undistorted target image without needing to reestimate the affine parameter (which tends to increase processing time).

Note

If your intent is to iteratively re-estimate a synthetic image after unwarping a distorted target (as in SynthUnwarp), it is essential that you employ the -a and –no_register flag after the initial registration. Failing to do so can result in a situation where small errors in the affine alignement of the synthetic image are “corrected” by the subsequent non-linear registration step. The partially corrected target image will then have this affine error baked into it. If SynthTarget is run again using the new target image, and is allowed to reestimate the affine parameters, it will do so while adding some new affine error. This new error combines with the previous affine error baked in by the non-linear warping step. A chase then ensues in which affine errors from SynthTarget keep growing after each iteration only to be corrected by the non-linear warping step. Sufficiently iterated, large affine registration errors can develop. So make sure you use -a and –no_register if you are going to use SynthTarget in this way.

-r REGRESSION_OUTPUT, --regression_output REGRESSION_OUTPUT

The file REGRESSION_OUTPUT.nii.gz stores the unblurred estimate of the synthetic image. If the input images are high resolution anatimical T1w and T2w images and the target image is a low resolution EPI, then this image can be considered a super-resolution version of the EPI image estimated at the resolution of the input images. While interesting to look at, it should not be used as a non-linear registration target. This is because the non-linear registration target should have and effective spatial resolution that is similar to the image that is being aligned to it. Thus, the appropriate image to use as a registration target is the one output by the -f flag (or in some cases, the -b flag).

-b SYNTH_IMAGE, --synth_image SYNTH_IMAGE

The file SYNTH_IMAGE.nii.gz stores a full synthetic image that is aligned to the input image(s). The key difference between this image and the one output by the -r option is that this image has the Epanachnikov blurring operator applied. This image is the real undistorted synthetic target image.

-f SYNTH_IMAGE_TARGET_SPACE, --synth_image_target_space SYNTH_IMAGE_TARGET_SPACE

The file SYNTH_IMAGE_TARGET_SPACE.nii.gz stores a version of the synthetic target image that is affine aligned to the original target image. This image is similar to that produced by the -b option and differs only by an affine operation. For the purposes of non-linear registration, this file is the most likely the one that will be of most use to the user.

-e ERR_TOL, --err_tol ERR_TOL (default: 0.0001)

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.

-d STEP_SIZE, --step_size STEP_SIZE (default: 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.

-i MAX_ITERATIONS, --max_iterations MAX_ITERATIONS (default: 200)

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

-c, --tone_curve

Enabling this flag will apply a final constrast enhancing “tone curve” adjustment is to the synthetic image. Enabling this option can improve (sometimes drastically) the visual similarity between synthetic and target images. The reason for this option is as follows:

A consequence of image distortion or any differences in spatial resolution or between the input_images and the target_image is that voxel intensities in a synthetic image will tend to be biased toward the overall mean of the target image. The visual effect of this bias is that overall contrast is reduced. To address this, SynthTarget includes the option to pass the final synthetic images through an invertible tone curve operation that attempts to maximize the similarity of the synthetic and target images. Tone curves are typically sigmoidal (for increasing contrast) or cubic-looking (for decreasing contrast) non-linear functions. Both types of shapes can be well-modeled by an appropriately parameterized cumulative beta distribution assuming the voxel intensities of the two images lie between 0 and 1. When the tone curve flag is set, SynthTarget estimates the parameters of the tone curve adjustment that will maximize the linear correlation coefficient between the target and synthetic images. See also, the -u flag.

-u TONE_CURVE_MASK, --tone_curve_mask TONE_CURVE_MASK

This file contains a binary (0,1) mask aligned to the input images. It is used to indicate the portion region where maximizing contrast similarity between target and synthetic images is most important. Only voxels indicated by 1s are included when determining the optimal tone curve (-c, –tone_curve).

Note

We currently recommend constructing the TONE_CURVE_MASK by taking a binary brain-only mask image that is aligned to the input images and then dilating it out by some amount so that in encompasses the brain, surrounding CSF and an portions of the skull.

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

Bandwidth for the Epanachnikov blurring kernel. In the case where input images consist of high resolution anatomical T1w and T2w images and the target image is a relatively low resolution EPI image, the difference in spatial resolution must be modeled. SynthTarget accomplishes this with an Epanachikov blurring operator which is convolved with the radial basis function decomposed components of the input images. In principle, the optimal bandwidth parameter should be derivable from theory. In practice though the the effective spatial resolution of the images is not always determined by the native image resolution. For instance, if the target image is an EPI image made by averaging several frames together, then there is additional blurring compared to an image made from a single frame. Thus, the bandwidth parameter is user-modifiable. Some guidance on values: We have found that when the input images are captured at 1mm isotropic resolution, and target image (EPI) is made by averaging several frames captured at a native 4 mm isotropic resolution, then a bandwidth parameter of 16 works well. When native EPI resolution is increased to 2.6 mm isotropic voxels, a bandwidth parameter of 10 seems to work well.

--fixed_regress FIXED_REGRESS

Fix the regression parameters with given regress file (must be dimensionally consistent with the model).

--no_register

When this flag is enabled, SynthTarget does not attempt to optimize the affine registration parameters and only the linear model parameters mapping the radial basis function components of the input images to the target image are calculated. This option is useful when input and target images are already very well-aligned and you just want to construct a synthetic estimated from the current alignment (or an initial affine alignment estimate passed in using the -a flag).

--output_intmat

Enabling this flag saves the radial basis function decomposition of the input images to the current working directory. This file is in hdf5 format and will be quite large! It can be converted into a NIFTI format file using the omni_intmat2nifti utility. The result will be a 4D NIFTI file in which each frame depicts a component of the radial basis function model used to construct the synthetic target image. Examining the output of this command can be very helpful for understanding or troubleshooting SynthTarget performance.

-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