Add 'Force' as matching_parameter option for fmap matching

Author: pvelasco

docs/heuristics.rst

@@ -117,6 +117,8 @@ The parameters that can be specified and the allowed options are defined in ``bi
    * ``'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).
+   * ``'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

heudiconv/bids.py

@@ -55,7 +55,11 @@ class BIDSError(Exception):
 AllowedFmapParameterMatching = [
     'Shims',
     'ImagingVolume',
+    'Force',
 ]
+# Key info returned by get_key_info_for_fmap_assignment when
+# matching_parameter = "Force"
+KeyInfoForForce = "Forced"
 # List defining allowed criteria to assign a given fmap to a non-fmap run
 # among the different fmaps with matching parameters:
 AllowedCriteriaForFmapAssignment = [
@@ -616,6 +620,10 @@ def get_key_info_for_fmap_assignment(json_file, matching_parameter='ImagingVolum
         nifti_file = glob(remove_suffix(json_file, '.json') + '.nii*')
         nifti_header = nb_load(nifti_file).header
         key_info = [nifti_header.affine, nifti_header.dim[1:3]]
+    elif matching_parameter == 'Force':
+        # We want to force the matching, so just return some string
+        # regardless of the image
+        key_info = [KeyInfoForForce]
 
     return key_info
 

heudiconv/tests/test_bids.py

@@ -32,6 +32,7 @@
     select_fmap_from_compatible_groups,
     SHIM_KEY,
     AllowedCriteriaForFmapAssignment,
+    KeyInfoForForce,
 )
 
 import pytest
@@ -128,7 +129,13 @@ def mock_nibabel_load(file):
     )
     assert key_info == [MY_AFFINE, MY_DIM[1:3]]
 
-    # 4) invalid matching_parameters:
+    # 4) matching_parameters = 'Force'
+    key_info = get_key_info_for_fmap_assignment(
+        json_name, matching_parameter='Force'
+    )
+    assert key_info == [KeyInfoForForce]
+
+    # Finally: invalid matching_parameters:
     with pytest.raises(ValueError):
         assert get_key_info_for_fmap_assignment(
             json_name, matching_parameter='Invalid'