RF: Split PEPolar fieldmaps by intent, if available

[effigies]

Encountered a dataset (cc @demidenm) with 6 fieldmaps, identifiable with IntendedFor. SDCFlows combined them into a two fieldmaps with three scans in each direction.

I understand that one goal was to provide better, more uniform fieldmaps, but I don't think that should come at the cost of ignoring clear intent. If the user wants to combine the fieldmaps to use on all images, they may do so explicitly.

This approach also groups fieldmaps with missing IntendedFor or with an empty list as a value. It would be the responsibility of downstream code to interpret whether to apply these fieldmaps to any EPI data.

[effigies]

The failure is related to the HCP test dataset.

❯ sdcflows-find-estimators -v /data/nipreps/test_data/HCP101006/
[sdcflow.wrangler - DEBUG]: Found PHASEDIFF estimation from 2 sources:
- sub-101006/fmap/sub-101006_phasediff.nii.gz
- sub-101006/fmap/sub-101006_magnitude1.nii.gz
[sdcflow.wrangler - DEBUG]: Failed to construct unnamed PEPOLAR estimation from 1 sources:
- sub-101006/fmap/sub-101006_dir-LR_epi.nii.gz
Error: Insufficient sources to estimate a fieldmap.
[sdcflow.wrangler - DEBUG]: Failed to construct unnamed PEPOLAR estimation from 1 sources:
- sub-101006/fmap/sub-101006_dir-RL_epi.nii.gz
Error: Insufficient sources to estimate a fieldmap.
[sdcflow.wrangler - DEBUG]: Found single PE fieldmap sub-101006/fmap/sub-101006_dir-LR_epi.nii.gz
[sdcflow.wrangler - DEBUG]: Single PE target func/sub-HCP101006_task-rest_dir-RL_bold.nii.gz not found
[sdcflow.wrangler - DEBUG]: Single PE target func/sub-HCP101006_task-rest_dir-RL_sbref.nii.gz not found
[sdcflow.wrangler - DEBUG]: Found single PE fieldmap sub-101006/fmap/sub-101006_dir-RL_epi.nii.gz
[sdcflow.wrangler - DEBUG]: Single PE target func/sub-HCP101006_task-rest_dir-LR_bold.nii.gz not found
[sdcflow.wrangler - DEBUG]: Single PE target func/sub-HCP101006_task-rest_dir-LR_sbref.nii.gz not found
[sdcflow.wrangler - DEBUG]: Skipping fmap-less estimation
Estimation for </data/nipreps/test_data/HCP101006> complete. Found:
	sub-101006
		FieldmapEstimation(sources=<2 files>, method=<EstimatorType.PHASEDIFF: 3>, bids_id='auto_00000')
			None	fmap/sub-101006_phasediff.nii.gz
			None	fmap/sub-101006_magnitude1.nii.gz

Some of this is bad metadata (should be sub-101006 in the IntendedFor field, not sub-HCP101006). However, I believe the intent is to use epi + sbref to form the fieldmap and then correct the sbref and BOLD file. The current IntendedFor with our defined rules would create one fieldmap from epi + sbref, and one from epi + bold. I would suggest we add a new rule for this case where sbref is considered a fieldmap by courtesy, and the intended target is any BOLD/DWI files that match the sbref.

[effigies]

With nipreps-data/HCP101006#2, I get

$ sdcflows-find-estimators -v /data/nipreps/test_data/HCP101006/
[sdcflow.wrangler - DEBUG]: Found PHASEDIFF estimation from 2 sources:
- sub-101006/fmap/sub-101006_phasediff.nii.gz
- sub-101006/fmap/sub-101006_magnitude1.nii.gz
[sdcflow.wrangler - DEBUG]: Failed to construct unnamed PEPOLAR estimation from 1 sources:
- sub-101006/fmap/sub-101006_dir-LR_epi.nii.gz
Error: Insufficient sources to estimate a fieldmap.
[sdcflow.wrangler - DEBUG]: Failed to construct unnamed PEPOLAR estimation from 1 sources:
- sub-101006/fmap/sub-101006_dir-RL_epi.nii.gz
Error: Insufficient sources to estimate a fieldmap.
[sdcflow.wrangler - DEBUG]: Found single PE fieldmap sub-101006/fmap/sub-101006_dir-LR_epi.nii.gz
[sdcflow.wrangler - DEBUG]: Found single PE target sub-101006/func/sub-101006_task-rest_dir-RL_sbref.nii.gz
[sdcflow.wrangler - DEBUG]: Found PEPOLAR estimation from 2 sources:
- sub-101006/fmap/sub-101006_dir-LR_epi.nii.gz
- sub-101006/func/sub-101006_task-rest_dir-RL_sbref.nii.gz
[sdcflow.wrangler - DEBUG]: Found single PE fieldmap sub-101006/fmap/sub-101006_dir-RL_epi.nii.gz
[sdcflow.wrangler - DEBUG]: Found single PE target sub-101006/func/sub-101006_task-rest_dir-LR_sbref.nii.gz
[sdcflow.wrangler - DEBUG]: Found PEPOLAR estimation from 2 sources:
- sub-101006/fmap/sub-101006_dir-RL_epi.nii.gz
- sub-101006/func/sub-101006_task-rest_dir-LR_sbref.nii.gz
[sdcflow.wrangler - DEBUG]: Skipping fmap-less estimation
Estimation for </data/nipreps/test_data/HCP101006> complete. Found:
	sub-101006
		FieldmapEstimation(sources=<2 files>, method=<EstimatorType.PHASEDIFF: 3>, bids_id='auto_00000')
			None	fmap/sub-101006_phasediff.nii.gz
			None	fmap/sub-101006_magnitude1.nii.gz
		FieldmapEstimation(sources=<2 files>, method=<EstimatorType.PEPOLAR: 2>, bids_id='auto_00001')
			i	fmap/sub-101006_dir-LR_epi.nii.gz
			i-	func/sub-101006_task-rest_dir-RL_sbref.nii.gz
		FieldmapEstimation(sources=<2 files>, method=<EstimatorType.PEPOLAR: 2>, bids_id='auto_00002')
			i-	fmap/sub-101006_dir-RL_epi.nii.gz
			i	func/sub-101006_task-rest_dir-LR_sbref.nii.gz

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 88.00000% with 3 lines in your changes missing coverage. Please review.

Project coverage is 88.48%. Comparing base (acfb2d6) to head (78c2342).
Report is 306 commits behind head on master.

Files with missing lines	Patch %	Lines
sdcflows/utils/wrangler.py	88.00%	2 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #342      +/-   ##
==========================================
+ Coverage   88.26%   88.48%   +0.21%     
==========================================
  Files          25       25              
  Lines        2080     2110      +30     
  Branches      320      331      +11     
==========================================
+ Hits         1836     1867      +31     
+ Misses        202      201       -1     
  Partials       42       42              

Flag	Coverage Δ
travis	83.41% <88.00%> (?)
unittests	88.31% <88.00%> (+0.04%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[effigies]

@oesteban What do you think about this change, philosophically? Can consider implementation details later.

[oesteban]

I won't be able to have a close look until tomorrow. At the outset, I'm happy to improve usability when possible. If this doesn't interact with the B0 identifiers approach, then why not?

However, I would prefer people start using the identifiers as they are more explicit about the intent.

[effigies]

At the outset, I'm happy to improve usability when possible. If this doesn't interact with the B0 identifiers approach, then why not?

Will go ahead then. This should have no impact on B0Field markers.

However, I would prefer people start using the identifiers as they are more explicit about the intent.

Agreed. The context here is a dataset the user doesn't fully control. The intent is clear, whether or not it's good practice.