RFC: New heuristics table

[oesteban]

In the context of nipreps/dmriprep#97, I'm trying to design a more generalizable set of heuristics when deciding the SDC estimation strategy. This is also related to nipreps/dmriprep#70.

This is likely to replace the fieldmap_wrangler eventually:

sdcflows/sdcflows/workflows/base.py

Lines 258 to 294 in 02a824e

	def fieldmap_wrangler(layout, target_image, use_syn=False, force_syn=False):
	"""Query the BIDSLayout for fieldmaps, and arrange them for the orchestration workflow."""
	from collections import defaultdict
	fmap_bids = layout.get_fieldmap(target_image, return_list=True)
	fieldmaps = defaultdict(list)
	for fmap in fmap_bids:
	if fmap['suffix'] == 'epi':
	fieldmaps['epi'].append((fmap['epi'], layout.get_metadata(fmap['epi'])))
	if fmap['suffix'] == 'fieldmap':
	fieldmaps['fieldmap'].append({
	'magnitude': [(fmap['magnitude'], layout.get_metadata(fmap['magnitude']))],
	'fieldmap': [(fmap['fieldmap'], layout.get_metadata(fmap['fieldmap']))],
	})
	if fmap['suffix'] == 'phasediff':
	fieldmaps['phasediff'].append({
	'magnitude': [(fmap[k], layout.get_metadata(fmap[k]))
	for k in sorted(fmap.keys()) if k.startswith('magnitude')],
	'phases': [(fmap['phasediff'], layout.get_metadata(fmap['phasediff']))],
	})
	if fmap['suffix'] == 'phase':
	fieldmaps['phasediff'].append({
	'magnitude': [(fmap[k], layout.get_metadata(fmap[k]))
	for k in sorted(fmap.keys()) if k.startswith('magnitude')],
	'phases': [(fmap[k], layout.get_metadata(fmap[k]))
	for k in sorted(fmap.keys()) if k.startswith('phase')],
	})
	if fieldmaps and force_syn:
	# syn: True -> Run SyN in addition to fieldmap-based SDC
	fieldmaps['syn'] = True
	elif not fieldmaps and (force_syn or use_syn):
	# syn: False -> Run SyN as only SDC
	fieldmaps['syn'] = False
	return fieldmaps

The implementation will probably take the shape of a workflow, with an IdentityInterface for an outputnode where fields are the names of the EPI targets, for later selection.

Each of these fields will contain a list of fielmaps (which will be written out to the derivatives folder following the proposal in #26, with the adaptation of #26 (comment)), in the order and estimated as prescribed in the following table:

This heuristic table is to be applied per participant.

• In the case of DWI, a target can be any dwi dataset under dwi/.
• In the case of BOLD, a target will be first any sbref and then any bold in the absence of sbref with IntendedFor.

Priority	Data	Behavior
0	2+ EPIs with different PE but common IntendedFor under fmap/	i) Estimate fieldmap (pepolar); ii) Apply fieldmap to IntendedFor targets
1	1+ EPIs with common PE and IntendedFor under fmap/ with 1+ target in IntendedFor with different PE.	i) Estimate fieldmap (pepolar), using IntendedFor targets as alternative PEs; ii) Apply fieldmap to IntendedFor targets
2	2+ EPIs with different PE but no IntendedFor under fmap/	Expand IntendedFor to all targets and apply 0?
3	1+ EPIs with common PE and no IntendedFor under fmap/ with 1+ target with different PE.	Expand IntendedFor to all targets and apply 1?
4	Targets have several different PEs	i) Hierarchically find most granular matches for estimation (i.e., first dir-, then run-, then acq-, etc. and their combinations); ii) Expand a IntendedFor to corresponding matches
5	Fieldmap images with IntendedFor. Priority of fieldmaps: _fieldmap, _phasediff, _phase{1,2}.	Apply fieldmap regularization and conversion to Hz workflow
6	No data under fmap/ and targets do not have several PEs	Fieldmap-less solutions

This is to be discussed in today's dMRIPrep meeting (cc/ @nipreps/dmriprep). Requesting for comments from @mattcieslak, @effigies, @satra, @mgxd.

[mattcieslak]

One thing that will be important is picking which images from the epi fieldmaps, whether from fmaps/ or dwi/, to use. Siemens scanners add b>0 images to these, so it would be great to extend BIDS to allow for bval and bvec files in fmaps/ to prevent b>0 images from being used for distortion correction. It has also been helpful to use b=0 images from multiple timepoints in the scan if the fieldmaps are coming from long dwi scans.

Otherwise this looks great

[oesteban]

Siemens scanners add b>0 images to these, so it would be great to extend BIDS to allow for bval and bvec files in fmaps/ to prevent b>0 images from being used for distortion correction.

I've given this some thought and realized this would be really easy to encode with valid BIDS: just dump those bvecs and bvals in the sidecar JSON.

I'll try to resurrect a bunch of stalled PRs and figure out whether a new PR would be appropriate. But this should be more explicit in BIDS (and that way, for instance, the validator can be instructed to check that the number of b-vecs/vals in the sidecar matches the size of the 4th dimension).

That also made me think about the RASB PR. We are already including tables in the metadata (e.g. the SliceTiming key) - what is it different in the case of the gradient table? wouldn't it be much more compact and easy to check by the validator if it were in the sidecar?

That said, in my first implementation of nipreps/dmriprep#97, I'm using b0s extracted from two datasets under dwi/, so those it is more of an implementation detail rather than a hole in the spec.

[oesteban]

When bids-standard/bids-specification#622 goes in this heuristic table will be much easier, and should be defined by the workflows using sdcflows, so not a responsibility of this package anymore. Closing.