Merge pull request #482 from cbinyu/adds_populate_intended_for

ENH: Adds populate_intended_for for fmaps

Author: yarikoptic

.gitignore

@@ -5,3 +5,6 @@
 .idea/
 venvs/
 _build/
+build/
+.vscode/
+

docs/heuristics.rst

@@ -84,4 +84,66 @@ or::
     def grouping(files, dcmfilter, seqinfo):
         seqinfos = collections.OrderedDict()
         ...
-        return seqinfos  # ordered dict containing seqinfo objects: list of DICOMs
+        return seqinfos  # ordered dict containing seqinfo objects: list of DICOMs
+
+
+-------------------------------
+``POPULATE_INTENDED_FOR_OPTS``
+-------------------------------
+
+Dictionary to specify options to populate the ``'IntendedFor'`` field of the ``fmap``
+jsons.
+
+When a BIDS session has ``fmaps``, they can automatically be assigned to be used for
+susceptibility distortion correction of other non-``fmap`` images in the session
+(populating the ``'IntendedFor'`` field in the ``fmap`` json file).
+
+For this automated assignment, ``fmaps`` are taken as groups (``_phase`` and ``_phasediff``
+images and the corresponding ``_magnitude`` images; consecutive Spin-Echo images collected
+with opposite phase encoding polarity (``pepolar`` case); etc.).
+
+This is achieved by checking, for every non-``fmap`` image in the session, which ``fmap``
+groups are suitable candidates to correct for distortions in that image.  Then, if there is
+more than one candidate (e.g., if there was a ``fmap`` collected at the beginning of the
+session and another one at the end), the user can specify which one to use.
+
+The parameters that can be specified and the allowed options are defined in ``bids.py``:
+ - ``'matching_parameter'``: The imaging parameter that needs to match between the ``fmap``
+   and an image for the ``fmap`` to be considered as a suitable to correct that image.
+   Allowed options are:
+
+   * ``'Shims'``: ``heudiconv`` will check the ``ShimSetting`` in the ``.json`` files and
+     will only assign ``fmaps`` to images if the ``ShimSettings`` are identical for both.
+   * ``'ImagingVolume'``: both ``fmaps`` and images will need to have the same the imaging
+     volume (the header affine transformation: position, orientation and voxel size, as well
+     as number of voxels along each dimensions).
+   * ``'ModalityAcquisitionLabel'``: it checks for what modality (``anat``, ``func``, ``dwi``) each
+     ``fmap`` is intended by checking the ``_acq-`` label in the ``fmap`` filename and finding
+     corresponding modalities (e.g. ``_acq-fmri``, ``_acq-bold`` and ``_acq-func`` will be matched
+     with the ``func`` modality)
+   * ``'CustomAcquisitionLabel'``: it checks for what modality images each  ``fmap`` is intended
+     by checking the ``_acq-`` custom label (e.g. ``_acq-XYZ42``) in the ``fmap`` filename, and
+     matching it with:
+     - the corresponding modality image ``_acq-`` label for modalities other than ``func``
+     (e.g. ``_acq-XYZ42`` for ``dwi`` images)
+     - the corresponding image ``_task-`` label for the ``func`` modality (e.g. ``_task-XYZ42``)
+   * ``'Force'``: forces ``heudiconv`` to consider any ``fmaps`` in the session to be
+     suitable for any image, no matter what the imaging parameters are.
+
+
+ - ``'criterion'``: Criterion to decide which of the candidate ``fmaps`` will be assigned to
+   a given file, if there are more than one. Allowed values are:
+
+   * ``'First'``: The first matching ``fmap``.
+   * ``'Closest'``: The closest in time to the beginning of the image acquisition.
+
+.. note::
+  Example::
+
+    POPULATE_INTENDED_FOR_OPTS = {
+            'matching_parameters': ['ImagingVolume', 'Shims'],
+            'criterion': 'Closest'
+    }
+
+If ``POPULATE_INTENDED_FOR_OPTS`` is not present in the heuristic file, ``IntendedFor``
+will not be populated automatically.