RF: Add 'AcquisitionLabel' as matching_parameter option for fmap matching

Remove it from the `Shims` option.
Add corresponding unit tests and documentation.

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).
+   * ``'AcquisitionLabel'``: it checks for what modality (``anat``, ``func``, ``dwi``) each
+     ``fmap`` is intended by checking the ``_acq-`` label in the filename
    * ``'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

@@ -55,6 +55,7 @@ class BIDSError(Exception):
 AllowedFmapParameterMatching = [
     'Shims',
     'ImagingVolume',
+    'AcquisitionLabel',
     'Force',
 ]
 # Key info returned by get_key_info_for_fmap_assignment when
@@ -513,30 +514,23 @@ def convert_sid_bids(subject_id):
 def get_shim_setting(json_file):
     """
     Gets the "ShimSetting" field from a json_file.
-    If not present:
-    - for fmap files: use the <acq> entity from the file name
-    - for other files: use the folder name ('anat', 'func', 'dwi', ...)
+    If no "ShimSetting" present, return error
 
     Parameters:
     ----------
     json_file : str
 
     Returns:
     -------
-    str with "ShimSetting" value or <acq> entity
+    str with "ShimSetting" value
     """
     data = load_json(json_file)
-    if SHIM_KEY in data.keys():
+    try:
         shims = data[SHIM_KEY]
-    else:
-        modality = op.basename(op.dirname(json_file))
-        if modality == 'fmap':
-            # extract the <acq> entity:
-            shims = re.search('(?<=[/_]acq-)\w+',json_file).group(0).split('_')[0]
-            if shims.lower() in ['fmri', 'bold']:
-                shims = 'func'
-        else:
-            shims = modality
+    except KeyError as e:
+        lgr.error('File %s does not have "ShimSetting".'
+                  'Please use a different "matching_parameters" in your heuristic file', json_file)
+        raise KeyError
     return shims
 
 
@@ -620,6 +614,20 @@ 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 == 'AcquisitionLabel':
+        # Check the acq label for the fmap and the modality for others:
+        modality = op.basename(op.dirname(json_file))
+        if modality == 'fmap':
+            # extract the <acq> entity:
+            acq_label = re.search('(?<=[/_]acq-)\w+', json_file).group(0).split('_')[0]
+            if any(s in acq_label.lower() for s in ['fmri', 'bold', 'func']):
+                key_info = ['func']
+            elif any(s in acq_label.lower() for s in ['diff', 'dwi']):
+                key_info = ['dwi']
+            elif any(s in acq_label.lower() for s in ['anat', 'struct']):
+                key_info = ['anat']
+        else:
+            key_info = [modality]
     elif matching_parameter == 'Force':
         # We want to force the matching, so just return some string
         # regardless of the image

heudiconv/tests/test_bids.py

@@ -60,29 +60,21 @@ def test_treat_age():
 TODAY = datetime.today()
 
 
-# Test scenarios:
-# -file with "ShimSetting" field
-# -file with no "ShimSetting", in "foo" dir, should return "foo"
-# -file with no "ShimSetting", in "fmap" dir, acq-CatchThis, should return
-#       "CatchThis"
-# -file with no "ShimSetting", in "fmap" dir, acq-fMRI, should return "func"
 A_SHIM = ['{0:.4f}'.format(random()) for i in range(SHIM_LENGTH)]
-@pytest.mark.parametrize(
-    "fname, content, expected_return", [
-        (op.join('foo', 'bar.json'), {SHIM_KEY: A_SHIM}, A_SHIM),
-        (op.join('dont_catch_this', 'foo', 'bar.json'), {}, 'foo'),
-        (op.join('dont_catch_this', 'fmap', 'bar_acq-CatchThis.json'), {}, 'CatchThis'),
-        (op.join('dont_catch_this', 'fmap', 'bar_acq-fMRI.json'), {}, 'func'),
-    ]
-)
-def test_get_shim_setting(tmpdir, fname, content, expected_return):
+def test_get_shim_setting(tmpdir):
     """ Tests for get_shim_setting """
-    json_name = op.join(str(tmpdir), fname)
-    json_dir = op.dirname(json_name)
+    json_dir = op.join(str(tmpdir), 'foo')
     if not op.exists(json_dir):
         os.makedirs(json_dir)
-    save_json(json_name, content)
-    assert get_shim_setting(json_name) == expected_return
+    json_name = op.join(json_dir, 'sub-foo.json')
+    # 1) file with no "ShimSetting", should return None
+    save_json(json_name, {})
+    with pytest.raises(KeyError):
+        assert get_shim_setting(json_name)
+
+    # -file with "ShimSetting" field
+    save_json(json_name, {SHIM_KEY: A_SHIM})
+    assert get_shim_setting(json_name) == A_SHIM
 
 
 def test_get_key_info_for_fmap_assignment(tmpdir, monkeypatch):
@@ -135,6 +127,26 @@ def mock_nibabel_load(file):
     )
     assert key_info == [KeyInfoForForce]
 
+    # 5) matching_parameter = 'AcquisitionLabel'
+    for d in ['fmap', 'func', 'dwi', 'anat']:
+        os.makedirs(op.join(str(tmpdir), d))
+    for (dirname, fname, expected_key_info) in [
+        ('fmap', 'sub-foo_acq-fmri_epi.json', 'func'),
+        ('fmap', 'sub-foo_acq-bold_epi.json', 'func'),
+        ('fmap', 'sub-foo_acq-func_epi.json', 'func'),
+        ('fmap', 'sub-foo_acq-diff_epi.json', 'dwi'),
+        ('fmap', 'sub-foo_acq-anat_epi.json', 'anat'),
+        ('fmap', 'sub-foo_acq-struct_epi.json', 'anat'),
+        ('func', 'sub-foo_bold.json', 'func'),
+        ('dwi', 'sub-foo_dwi.json', 'dwi'),
+        ('anat', 'sub-foo_T1w.json', 'anat'),
+    ]:
+        json_name = op.join(str(tmpdir), dirname, fname)
+        save_json(json_name, {SHIM_KEY: A_SHIM})
+        assert [expected_key_info] == get_key_info_for_fmap_assignment(
+            json_name, matching_parameter='AcquisitionLabel'
+        )
+
     # Finally: invalid matching_parameters:
     with pytest.raises(ValueError):
         assert get_key_info_for_fmap_assignment(
@@ -207,6 +219,7 @@ def create_dummy_pepolar_bids_session(session_path):
     # 1) Simulate the file structure for a session:
 
     # Generate some random ShimSettings:
+    anat_shims = ['{0:.4f}'.format(random()) for i in range(SHIM_LENGTH)]
     dwi_shims = ['{0:.4f}'.format(random()) for i in range(SHIM_LENGTH)]
     func_shims_A = ['{0:.4f}'.format(random()) for i in range(SHIM_LENGTH)]
     func_shims_B = ['{0:.4f}'.format(random()) for i in range(SHIM_LENGTH)]
@@ -215,7 +228,7 @@ def create_dummy_pepolar_bids_session(session_path):
     # -anat:
     anat_struct = {
         '{p}_{m}.{e}'.format(p=prefix, m=mod, e=ext): dummy_content
-        for ext, dummy_content in zip(['nii.gz', 'json'], ['', {}])
+        for ext, dummy_content in zip(['nii.gz', 'json'], ['', {'ShimSetting': anat_shims}])
         for mod in ['T1w', 'T2w']
     }
     # -dwi:
@@ -675,11 +688,13 @@ def test_find_fmap_groups(tmpdir, simulation_function):
 # B) same, with no ShimSetting
 # C) magnitude/phase, with ShimSetting
 @pytest.mark.parametrize(
-    "simulation_function", [create_dummy_pepolar_bids_session,
-                            create_dummy_no_shim_settings_bids_session,
-                            create_dummy_magnitude_phase_bids_session]
+    "simulation_function, match_param", [
+        (create_dummy_pepolar_bids_session, 'Shims'),
+        (create_dummy_no_shim_settings_bids_session, 'AcquisitionLabel'),
+        (create_dummy_magnitude_phase_bids_session, 'Shims')
+    ]
 )
-def test_find_compatible_fmaps_for_run(tmpdir, simulation_function):
+def test_find_compatible_fmaps_for_run(tmpdir, simulation_function, match_param):
     """
     Test find_compatible_fmaps_for_run.
 
@@ -688,6 +703,8 @@ def test_find_compatible_fmaps_for_run(tmpdir, simulation_function):
     tmpdir
     simulation_function : function
         function to create the directory tree and expected results
+    match_param : str
+        matching_parameter for assigning fmaps
     """
     folder = op.join(str(tmpdir), 'sub-foo')
     _, _, expected_fmap_groups, expected_compatible_fmaps = simulation_function(folder)
@@ -696,7 +713,7 @@ def test_find_compatible_fmaps_for_run(tmpdir, simulation_function):
             compatible_fmaps = find_compatible_fmaps_for_run(
                 json_file,
                 expected_fmap_groups,
-                matching_parameters='Shims'
+                matching_parameters=match_param
             )
             assert compatible_fmaps == expected_compatible_fmaps[json_file]
 
@@ -709,28 +726,42 @@ def test_find_compatible_fmaps_for_run(tmpdir, simulation_function):
 # B) same, with no ShimSetting
 # C) magnitude/phase, with ShimSetting
 @pytest.mark.parametrize(
-    "folder, expected_prefix, simulation_function", [
-        (folder, expected_prefix, sim_func)
+    "folder, expected_prefix, simulation_function, match_param", [
+        (folder, expected_prefix, sim_func, mp)
         for folder, expected_prefix in zip(['no_sessions/sub-1', 'sessions/sub-1/ses-pre'], ['', 'ses-pre'])
-        for sim_func in [create_dummy_pepolar_bids_session,
-                         create_dummy_no_shim_settings_bids_session,
-                         create_dummy_magnitude_phase_bids_session]
+        for sim_func, mp in [
+            (create_dummy_pepolar_bids_session, 'Shims'),
+            (create_dummy_no_shim_settings_bids_session, 'AcquisitionLabel'),
+            (create_dummy_magnitude_phase_bids_session, 'Shims')
+        ]
     ]
 )
-def test_find_compatible_fmaps_for_session(tmpdir, folder, expected_prefix, simulation_function):
+def test_find_compatible_fmaps_for_session(
+        tmpdir,
+        folder,
+        expected_prefix,
+        simulation_function,
+        match_param
+):
     """
     Test find_compatible_fmaps_for_session.
 
     Parameters:
     ----------
     tmpdir
+    folder : str or os.path
+        path to BIDS study to be simulated, relative to tmpdir
+    expected_prefix : str
+        expected start of the "IntendedFor" elements
     simulation_function : function
         function to create the directory tree and expected results
+    match_param : str
+        matching_parameter for assigning fmaps
     """
     session_folder = op.join(str(tmpdir), folder)
     _, _, _, expected_compatible_fmaps = simulation_function(session_folder)
 
-    compatible_fmaps = find_compatible_fmaps_for_session(session_folder, matching_parameters='Shims')
+    compatible_fmaps = find_compatible_fmaps_for_session(session_folder, matching_parameters=match_param)
 
     assert compatible_fmaps == expected_compatible_fmaps
 
@@ -785,15 +816,23 @@ def test_select_fmap_from_compatible_groups(tmpdir, folder, expected_prefix, sim
 # B) same, with no ShimSetting
 # C) magnitude/phase, with ShimSetting
 @pytest.mark.parametrize(
-    "folder, expected_prefix, simulation_function", [
-        (folder, expected_prefix, sim_func)
+    "folder, expected_prefix, simulation_function, match_param", [
+        (folder, expected_prefix, sim_func, mp)
         for folder, expected_prefix in zip(['no_sessions/sub-1', 'sessions/sub-1/ses-pre'], ['', 'ses-pre'])
-        for sim_func in [create_dummy_pepolar_bids_session,
-                         create_dummy_no_shim_settings_bids_session,
-                         create_dummy_magnitude_phase_bids_session]
+        for sim_func, mp in [
+            (create_dummy_pepolar_bids_session, 'Shims'),
+            (create_dummy_no_shim_settings_bids_session, 'AcquisitionLabel'),
+            (create_dummy_magnitude_phase_bids_session, 'Shims')
+        ]
     ]
 )
-def test_populate_intended_for(tmpdir, folder, expected_prefix, simulation_function):
+def test_populate_intended_for(
+    tmpdir,
+    folder,
+    expected_prefix,
+    simulation_function,
+    match_param
+):
     """
     Test populate_intended_for.
     Parameters:
@@ -805,11 +844,13 @@ def test_populate_intended_for(tmpdir, folder, expected_prefix, simulation_funct
         expected start of the "IntendedFor" elements
     simulation_function : function
         function to create the directory tree and expected results
+    match_param : str
+        matching_parameter for assigning fmaps
     """
 
     session_folder = op.join(str(tmpdir), folder)
     session_struct, expected_result, _, _ = simulation_function(session_folder)
-    populate_intended_for(session_folder, matching_parameters='Shims', criterion='First')
+    populate_intended_for(session_folder, matching_parameters=match_param, criterion='First')
 
     # Now, loop through the jsons in the fmap folder and make sure it matches
     # the expected result: