Perform motion correction separately for each image type

[tsalo]

Closes #266 and closes #181 (I think it was already fixed, but this uses rmsdiff directly, so I consider it fixing the issue as well).

Changes proposed in this pull request

• Create new aslprep.interfaces.utility module with interfaces that are specific to ASL, but not directly related to CBF.
  • ReduceASLFiles drops volumes that won't be used by ASLPrep. For example, if an ASL file has control, label, and deltam volumes, then it will remove the deltam volumes, since ASLPrep tries to use the rawest data (control-label pairs).
  • RMSDiff calls FSL's rmsdiff command.
  • PairwiseRMSDiff calls the RMSDiff interface on each pair of matrix files to get a relative RMS time series.
  • CombineMotionParameters takes the parameter files and transform files from each of the volume type-specific MCFLIRT runs and stitches them back together according to the volume order defined in the aslcontext file.
  • SplitOutVolumeType separates out a specific volume type out of the ASL file. This splits up the ASL file for volume type-specific motion correction in the next node.
  • SplitReferenceTarget separates out the best volume type for reference image generation from the ASL file. This is called in the reference volume generation workflow.
• Add new functions to aslprep.utils.misc:
  • select_processing_target determines the appropriate volume types to process. If control-label pairs are available, then this is "controllabel". If control-label pairs aren't available, but deltam volumes are, then it's "deltam". And if nothing else is available, it's "cbf".
  • reduce_metadata_lists takes a metadata dictionary and drops any unused volumes' values from any list fields (e.g., PostLabelingDelay in some scenarios). This is called within ReduceASLFiles.
• Modify init_asl_preproc_wf.
  1. First, after validating the ASL file, reduce it to only include volume types that will be used in the processing (ReduceASLFiles). This reduced ASL file and associated metadata and aslcontext files will be used throughout the rest of the workflow.
  2. Within the reference workflow, only build the reference volume from a single volume type (M0 > control > deltam > cbf).
  3. Remove aslbuffer_stc and directly pass the ASL file from reduce_asl_file to asl_split. Without multi-echo data or slice-timing correction, we don't need this buffer node.
  4. Run motion correction on each remaining volume type (not included separate M0 scans) and stitch the resulting parameter and transform files back together according to the aslcontext file.
  5. Remove aslbuffer_me. Without multi-echo data, we don't need this buffer node.
• In the GE ASL workflow, the only real change is that now we pass the aslcontext file through to various subworkflows that need it (e.g., for reference image generation).
• Move init_asl_reference_wf from aslprep.niworkflows.func.util to new aslprep.workflows.asl.util.
• Move init_validate_asl_wf from aslprep.niworkflows.func.util to new aslprep.workflows.asl.util.

[codecov-commenter]

Codecov Report

Patch coverage: 84.22% and project coverage change: +0.51 🎉

Comparison is base (9dd615f) 49.52% compared to head (b994ebe) 50.04%.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #275      +/-   ##
==========================================
+ Coverage   49.52%   50.04%   +0.51%     
==========================================
  Files         132      134       +2     
  Lines       12215    12472     +257     
==========================================
+ Hits         6050     6241     +191     
- Misses       6165     6231      +66     

Impacted Files	Coverage Δ
aslprep/niworkflows/func/util.py	51.16% <ø> (+5.38%)	⬆️
aslprep/workflows/asl/ge_utils.py	97.36% <ø> (ø)
aslprep/interfaces/confounds.py	62.06% <37.14%> (-37.94%)	⬇️
aslprep/utils/misc.py	63.38% <76.19%> (+0.88%)	⬆️
aslprep/workflows/asl/util.py	81.35% <81.35%> (ø)
aslprep/interfaces/utility.py	92.04% <92.04%> (ø)
aslprep/workflows/asl/hmc.py	97.29% <95.83%> (-2.71%)	⬇️
aslprep/niworkflows/interfaces/registration.py	64.89% <100.00%> (-0.41%)	⬇️
aslprep/workflows/asl/base.py	92.12% <100.00%> (+0.24%)	⬆️
aslprep/workflows/asl/cbf.py	81.13% <100.00%> (-0.24%)	⬇️
... and 3 more

... and 2 files with indirect coverage changes

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.