How to troubleshoot registration

The RABIES defaults modify the images as little as possible and lean on the quality of the images at acquisition. They are the right starting point, but they do not produce a robust workflow for every dataset, and reaching good outcomes on your own data will often mean tuning parameters.

This guide maps failures visible in the preprocessing QC report onto the parameters that address them. Work through it in order: inhomogeneity correction feeds masking, and masking feeds every registration that follows, so a problem there will reappear downstream no matter what you change at the registration step.

Important

Before changing any parameter, confirm your images are correctly oriented — see How to check image orientation. Mis-oriented images produce registration failures that no amount of parameter tuning will fix.

Inhomogeneity correction

Relevant parameters: --anat_inho_cor, --bold_inho_cor, --anat_robust_inho_cor, --bold_robust_inho_cor. Inspect the anat_inho_cor/ and bold_inho_cor/ folders of the QC report.

Only a subset of scans have failed masking, or the mask is partially misregistered: Use --anat_robust_inho_cor/--bold_robust_inho_cor. These register all corrected images together to generate a temporary template representing the average of all scans, mask that template, and use it as the masking target in a second pass of inhomogeneity correction, which is a more robust target. The parameters for these options are the same as for --commonspace_reg below.
Inhomogeneity biases are not completely corrected, with signal drops remaining: Apply multiotsu=true. This performs a staged correction, correcting low intensities first and iteratively including higher ones, which better handles images with strong inhomogeneity gradients and very low intensities.
Tissue outside the brain is causing registration failures: If the initial correction enhanced the intensity of tissue outside the brain and masking then fails, use --anat_autobox/--bold_autobox to crop out the extra tissue automatically. You can also modify otsu_thresh, which sets the threshold for the automatic masking during the initial correction, to select a value more specific to brain tissue.
A large proportion of masking failures remain — mismatched brain sizes, non-linear warps, or the mask falling outside the brain: Apply a less stringent registration method, stepping down through SyN → Affine → Rigid → no_reg. If you reach no_reg, you may also have to adjust otsu_thresh to obtain an automatically generated brain mask covering only brain tissue.

Commonspace registration and susceptibility distortion correction

Relevant parameters: --commonspace_reg, --bold2anat_coreg. Inspect the commonspace_reg_wf.Anat2Unbiased/ and commonspace_reg_wf.Unbiased2Atlas/ folders of the QC report (or commonspace_reg_wf.Anat2Atlas/ if you used fast_commonspace=true), together with EPI2Anat/.

Many scans are misregistered, or brain edges are not well matched: First inspect the quality of inhomogeneity correction for those scans, and follow the guidance above if the correction or brain masking was poor. If good quality masks were obtained during inhomogeneity correction, bring them into the registration with masking=true. If registration errors persist, particularly at the brain edges, brain_extraction=true and keep_mask_after_extract=true further constrain edge matching by removing tissue outside the brain.

Warning

The quality of brain edge delineation depends on the masks derived during inhomogeneity correction, so brain_extraction=true is only as good as that earlier step. Fix masking first.
Scans have incomplete brain coverage, and surrounding tissue is stretched to fill the gap: Non-linear registration assumes corresponding anatomy between the moving image and the target. When brain regions are missing — the cerebellum or olfactory bulbs are the usual cases — the surrounding tissue may be improperly stretched to fill the missing area. brain_extraction=true,keep_mask_after_extract=true can largely mitigate this.

When registration cannot be salvaged

If a scan cannot be registered acceptably, exclude it rather than analysing it: see How to select which scans get processed.