ANTS coregistration implementation

[mathesong]

Summary

This PR adds ANTs rigid registration as a third option for PET-to-anatomical coregistration, alongside the existing FreeSurfer mri_coreg and mri_robust_register
methods. It also fixes critical bugs in the ANTs implementation and refactors the registration method interface for clarity.

Motivation

Users reported that the existing registration methods (mri_coreg and mri_robust_register) produced poor results for certain PET datasets. External testing with
ANTs rigid registration showed excellent alignment for these same datasets. This PR integrates ANTs registration into PETPrep to provide users with a robust
alternative registration method.

Changes

1. Added ANTs Registration Method

New command-line option:

--pet2anat-method {mri_coreg,robust,ants}

Implementation details:

• Uses ANTs Registration with rigid transform (6 DoF)
• Parameters optimized based on successful external testing:
  • Mutual Information metric with 32 bins
  • Multi-resolution optimization: [1000, 500, 250] iterations
  • Shrink factors: [4, 2, 1]
  • Gaussian smoothing: [2, 1, 0] voxels
  • Center-of-mass initialization
  • Winsorize intensities [0.005, 0.995]
• Critical fix: Brain mask properly passed to ANTs via fixed_image_masks parameter (not pre-masked image)

Files modified:

• petprep/workflows/pet/registration.py - Added ANTs branch with proper masking
• petprep/workflows/pet/fit.py - Added ANTs to method mapping
• petprep/interfaces/reports.py - Added ANTs case to report generation
• petprep/interfaces/tests/test_reports.py - Added ANTs to test parametrization

2. Fixed Critical ANTs Masking Bug

Problem: Initial implementation passed a pre-masked T1w image to ANTs, causing suboptimal registration.

Solution: ANTs now receives:

• Unmasked T1w as fixed_image
• Brain mask separately via fixed_image_masks parameter
• This matches the behavior of successful external ANTs commands

Impact: Registration quality now matches external ANTs results.

3. Fixed Report Generation Bug

Problem: The FunctionalSummary report generator had an else clause that labeled ALL non-standard methods (including ANTs) as "FreeSurfer mri_robust_register".

Solution: Added explicit cases for each method:
if registration == 'mri_coreg':
reg = f'FreeSurfer mri_coreg - {dof} dof'
elif registration == 'ants_registration':
reg = 'ANTs rigid registration (6 DoF)'
elif registration == 'mri_robust_register':
reg = 'FreeSurfer mri_robust_register (NMI cost)'

4. Refactored Registration Method Interface

Breaking change: Renamed method choices for accuracy and removed deprecated flag.

Before:
--pet2anat-robust # deprecated boolean flag

After:
--pet2anat-method {mri_coreg,robust,ants}

Rationale:

• The default method uses FreeSurfer's mri_coreg, NOT FSL's FLIRT
• The --pet2anat-robust flag was never released, so clean removal is preferred over deprecation
• Clearer naming prevents user confusion

Files modified:

• petprep/cli/parser.py - Updated choices, removed deprecated flag
• petprep/config.py - Changed default from 'flirt' to 'mri_coreg'
• petprep/workflows/pet/fit.py - Updated method mapping dictionary

5. Added Standalone Helper Function

Problem: Nipype cannot serialize inline lambda functions for multiprocessing.

Solution: Added _get_first() helper function to extract first element from ANTs transform list:
def _get_first(in_list):
"""Extract first element from a list (for ANTs transform output)."""
return in_list[0]

Testing

Manual Testing

• Tested on 4 subjects with known poor registration using previous methods
• ANTs registration produced visually correct alignment matching external results
• Verified transform outputs in ITK format compatible with downstream processing
• Confirmed report generation correctly labels registration method

Unit Tests

• Updated test_fit.py to test ANTs workflow construction
• Updated test_reports.py to include ANTs in parametrized tests
• All existing tests pass with renamed methods

Usage Examples

Using ANTs registration (new):

petprep <bids_dir> <output_dir> participant
--participant-label 01
--pet2anat-method ants
--pet2anat-dof 6

Using default FreeSurfer mri_coreg:

petprep <bids_dir> <output_dir> participant
--participant-label 01
--pet2anat-method mri_coreg
--pet2anat-dof 6

Using FreeSurfer robust registration:

petprep <bids_dir> <output_dir> participant
--participant-label 01
--pet2anat-method robust
--pet2anat-dof 6

Breaking Changes

⚠️ Command-line interface change:

• --pet2anat-robust flag removed (use --pet2anat-method robust instead)

Migration:

• Old: --pet2anat-robust → New: --pet2anat-method robust
• Default behavior unchanged (still uses FreeSurfer mri_coreg)

Performance Notes

• ANTs registration typically takes 5-40 seconds per subject (comparable to other methods)
• Parallelization supported via --omp-nthreads for per-process threading
• Transform caching works correctly - changing only registration method reuses anatomical preprocessing

Dependencies

• ANTs v2.6 (already in environment - no new dependencies)
• Uses existing Nipype ANTs interfaces

Related Issues

Fixes issues where:

• FreeSurfer registration methods produced poor alignment for certain PET datasets
• Brain masking implementation differed from successful external ANTs usage