Troubleshooting
Table 1 lists common problems, their likely causes and remedies. A quality-assurance checklist follows.
Table 1
Common Problems, Causes and Remedies
| Symptom | Likely cause | Remedy |
|---|---|---|
| Warped atlas displaced anteriorly or posteriorly | Poor T1 → MNI registration, or mismatched coverage (skull-stripped participant image with a whole-head template) | Check brain extraction; use the brain template; overlay the warped template on the T1 before warping labels |
| Left and right appear reversed | Incorrect transform, header orientation error, mislabelled hemisphere | Check with fslorient and fslhd; overlay known asymmetric anatomy |
| Atlas mask empty after warping | Threshold too strict after linear interpolation, or grid mismatch | Inspect the probability map before thresholding; derive a 25% map from the _overlap_prop file (downloads page); warp the binary map with nearest-neighbour interpolation |
| Mask includes ventricle or gray matter | Registration error or excessive dilation | Reduce dilation; inspect in native space |
| VTA in the cerebral peduncle or pons | Local registration failure | Rerun registration for the participant; consider a midbrain-weighted mask via -x |
tckgen reaches far fewer streamlines than the target | Cutoff too high for the field strength; corridor too narrow; seed or target disconnected from the corridor | Run the pilot sweep; confirm the seed and target lie within the inclusion zone; try a 25% map derived from the _overlap_prop file, or one additional voxel of dilation |
| Tract appears thick at a permissive cutoff | Expected before cleaning | Compare cleaned bundles; if still thick, reduce dilation |
| Cleaning removes nearly all streamlines | Two bundles cleaned as one, or a sparse raw tract | Apply the QuickBundles division; check the raw streamline count |
| Profile endpoints reversed in some participants | Orientation failed | Assign node 0 by the seed region; check centroid orientation per participant |
| Whole-tract NDI implausibly high or low | Grid mismatch, partial volume, global tissue differences | Confirm a common grid; add a whole-white-matter NDI covariate; inspect the overlay |
AMICO FileNotFoundError during parallel runs | Kernel directory regenerated by every job | Generate kernels once on one participant before starting the pool |
pip install pyAFQ fails on zipp | Outdated system package | pip install --user --upgrade zipp |
| Coverage audit flags every corridor as too small | Corridors are below 1% of brain volume by design | Raise the threshold or disregard the flag |
Note. MNI = Montreal Neurological Institute; VTA = ventral tegmental area; NDI = neurite density index.
Symptoms that appear at Step 1 or Step 2 often originate upstream, in the brain mask, the skull strip or the T1-to-diffusion transform; those steps are documented in the Diffusion MRI Preprocessing tutorial.
Quality-assurance checklist
- Record atlas version, threshold, dilation, interpolation, transforms, cutoff, scalar maps, covariates and software versions.
- Inspect the atlas in MNI space before warping.
- Inspect every warped region over the T1 and diffusion images.
- Check voxel counts and volumes after warping.
- Save at least one overlay image per participant and step.
- Inspect streamlines in native space and compare with the atlas in MNI space.
- Verify node ordering and coverage.
- Check missingness by tract and participant before group models.