[ENH] add PlainAcquisitionLabel IntendedFor method

docs/heuristics.rst

@@ -173,6 +173,9 @@ The parameters that can be specified and the allowed options are defined in ``bi
      - 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``)
+   * ``'PlainAcquisitionLabel'``: similar to ``'CustomAcquisitionLabel'``, but does not change
+     behavior for ``func`` modality and always bases decision on the ``_acq-`` label. Helps in
+     cases when there are multiple tasks and a shared ``fmap`` for some of them.
    * ``'Force'``: forces ``heudiconv`` to consider any ``fmaps`` in the session to be
      suitable for any image, no matter what the imaging parameters are.
 

heudiconv/bids.py

@@ -77,6 +77,7 @@ class BIDSError(Exception):
     "ImagingVolume",
     "ModalityAcquisitionLabel",
     "CustomAcquisitionLabel",
+    "PlainAcquisitionLabel",
     "Force",
 ]
 # Key info returned by get_key_info_for_fmap_assignment when
@@ -755,6 +756,10 @@ def get_key_info_for_fmap_assignment(
             custom_label = BIDSFile.parse(op.basename(json_file))["acq"]
         # Get the custom acquisition label, acq_label is None if no custom field found
         key_info = [custom_label]
+    elif matching_parameter == "PlainAcquisitionLabel":
+        # always base the decision on <acq> label
+        plain_label = BIDSFile.parse(op.basename(json_file))["acq"]
+        key_info = [plain_label]
     elif matching_parameter == "Force":
         # We want to force the matching, so just return some string
         # regardless of the image

heudiconv/tests/test_bids.py

@@ -179,6 +179,24 @@ def test_get_key_info_for_fmap_assignment(
             json_name, matching_parameter="CustomAcquisitionLabel"
         )
 
+    # 7) matching_parameter = 'PlainAcquisitionLabel'
+    A_LABEL = gen_rand_label(label_size, label_seed)
+    for d in ["fmap", "func", "dwi", "anat"]:
+        (tmp_path / d).mkdir(parents=True, exist_ok=True)
+
+    for dirname, fname, expected_key_info in [
+        ("fmap", f"sub-foo_acq-{A_LABEL}_epi.json", A_LABEL),
+        ("func", f"sub-foo_task-foo_acq-{A_LABEL}_bold.json", A_LABEL),
+        ("func", f"sub-foo_task-bar_acq-{A_LABEL}_bold.json", A_LABEL),
+        ("dwi", f"sub-foo_acq-{A_LABEL}_dwi.json", A_LABEL),
+        ("anat", f"sub-foo_acq-{A_LABEL}_T1w.json", A_LABEL),
+    ]:
+        json_name = op.join(tmp_path, dirname, fname)
+        save_json(json_name, {SHIM_KEY: A_SHIM})
+        assert [expected_key_info] == get_key_info_for_fmap_assignment(
+            json_name, matching_parameter="PlainAcquisitionLabel"
+        )
+
     # Finally: invalid matching_parameters:
     assert (
         get_key_info_for_fmap_assignment(json_name, matching_parameter="Invalid") == []