ENH: Refactor the workflow infrastructure

[oesteban]

This PR essentially creates a new init_fmap_preproc_wf workflow factory function, inspired by the success of init_anat_preproc_wf in sMRIPrep for T1w, T2w, and FLAIR images.

The idea is to clearly split the SDC (susceptibility distortion correction) process into its two main steps (#21): estimation of the warping and unwarping of data. To do so, fieldmap data are regarded at a higher level that actually generates derivatives (ref. #26).

The new init_fmap_preproc_wf takes in some input_data and:

1. Determines what kind of fieldmap estimation strategy requires
2. Stages the correct workflow for estimation
3. Writes out the estimated and preprocessed (e.g., smoothing/despiking) fieldmap with mm/s units. This means that the actual distortion field can be generated by scaling the fieldmap with the Effective echo spacing (in seg), along the appropriate PE direction (and with the appropriate sign) from the PhaseEncodingDirection field of the target dataset.

Because there's no spec for fieldmap derivatives, we could store it as a 4D file with two timepoints. First timepoint is the actual fieldmap and the second is the corresponding anatomical reference (magnitude, epi).

The derivative file would be something like: derivatives/fmriprep-20.2.0/sub-01/fmap/sub-01_desc-preproc_fieldmap.nii.gz. Should bids-standard/bids-specification#622 be merged, then a potential name for this could be derivatives/fmriprep-20.2.0/sub-01/fmap/sub-01_[id-<B0FieldIdentifier>]_fieldmap.nii.gz with B0FieldIdentifier being the metadata entry, if present.

The corresponding JSON metadata should always propagate the IntendedFor of the source data, so that these fieldmaps can be actually applied (esp. if bids-standard/bids-specification#622 is never accepted.)

Another feature I'm seriously considering is to create a lightweight object (á la niworkflows.utils.spaces.Reference) for representing input_data argument.

Some sort of FieldmapSources object that morphs itself depending on the inputs, to offer specialized methods and metadata determined from the inputs.

I'm just proposing the idea with this draft, looking forward to getting some feedback.

[oesteban]

wdyt @effigies @mgxd @mattcieslak ?

[pep8speaks]

Hello @oesteban, Thank you for updating!

Cheers! There are no style issues detected in this Pull Request. 🍻 To test for issues locally, pip install flake8 and then run flake8 sdcflows.

Comment last updated at 2020-11-18 14:12:46 UTC

[oesteban]

I'm not sure this is really necessary. Will reopen if the final solution on top of #114 is based on this PR (see oesteban/sdcflows@enh/fieldmap-objects...oesteban:rf/issues-20-21-26)