enh: add doctests to exercise the B0FieldIdentifier implementation

Author: oesteban

sdcflows/conftest.py

@@ -40,9 +40,10 @@
 }
 
 data_dir = Path(__file__).parent / "tests" / "data"
-
-layouts["dsA"] = BIDSLayout(data_dir / "dsA", validate=False, derivatives=False)
-layouts["dsB"] = BIDSLayout(data_dir / "dsB", validate=False, derivatives=False)
+layouts.update({
+    folder.name: BIDSLayout(folder, validate=False, derivatives=False)
+    for folder in data_dir.glob("ds*") if folder.is_dir()
+})
 
 
 def pytest_report_header(config):
@@ -66,6 +67,7 @@ def add_np(doctest_namespace):
 
     doctest_namespace["dsA_dir"] = data_dir / "dsA"
     doctest_namespace["dsB_dir"] = data_dir / "dsB"
+    doctest_namespace["dsC_dir"] = data_dir / "dsC"
 
 
 @pytest.fixture

sdcflows/tests/data/dsC/dataset_description.json

@@ -0,0 +1,11 @@
+{
+    "Name": "Test Dataset A, only empty files",
+    "BIDSVersion": "",
+    "License": "CC0",
+    "Authors": ["Esteban O."],
+    "Acknowledgements": "",
+    "HowToAcknowledge": "",
+    "Funding": "",
+    "ReferencesAndLinks": [""],
+    "DatasetDOI": ""
+}

sdcflows/tests/data/dsC/sub-01/anat/sub-01_FLAIR.nii.gz

@@ -0,0 +1,4 @@
+{
+    "PhaseEncodingDirection": "j-",
+    "TotalReadoutTime": 0.005
+}

sdcflows/tests/data/dsC/sub-01/anat/sub-01_T1w.nii.gz

@@ -0,0 +1,4 @@
+{
+    "PhaseEncodingDirection": "i",
+    "TotalReadoutTime": 0.005
+}

sdcflows/tests/data/dsC/sub-01/anat/sub-01_T2w.nii.gz

@@ -0,0 +1,4 @@
+{
+    "PhaseEncodingDirection": "j",
+    "TotalReadoutTime": 0.005
+}

sdcflows/tests/data/dsC/sub-01/dwi/sub-01_dir-AP_dwi.nii.gz

@@ -0,0 +1,4 @@
+{
+    "PhaseEncodingDirection": "i-",
+    "TotalReadoutTime": 0.005
+}

sdcflows/tests/data/dsC/sub-01/dwi/sub-01_dir-AP_sbref.json

@@ -0,0 +1,10 @@
+{
+    "PhaseEncodingDirection": "j",
+    "TotalReadoutTime": 0.005,
+    "IntendedFor": [
+        "dwi/sub-01_dir-AP_dwi.nii.gz",
+        "dwi/sub-01_dir-AP_sbref.nii.gz",
+        "func/sub-01_task-rest_bold.nii.gz",
+        "func/sub-01_task-rest_sbref.nii.gz"
+    ]
+}

sdcflows/tests/data/dsC/sub-01/dwi/sub-01_dir-AP_sbref.nii.gz

@@ -0,0 +1,5 @@
+{
+	"B0FieldIdentifier": "pepolar4pe",
+	"PhaseEncodingDirection": "j-",
+	"TotalReadoutTime": 0.005
+}

sdcflows/tests/data/dsC/sub-01/dwi/sub-01_dir-LR_dwi.nii.gz

@@ -0,0 +1,5 @@
+{
+	"B0FieldIdentifier": "pepolar4pe",
+	"PhaseEncodingDirection": "i",
+	"TotalReadoutTime": 0.005
+}

sdcflows/tests/data/dsC/sub-01/dwi/sub-01_dir-LR_sbref.json

@@ -0,0 +1,5 @@
+{
+	"B0FieldIdentifier": "pepolar4pe",
+	"PhaseEncodingDirection": "j",
+	"TotalReadoutTime": 0.005
+}

sdcflows/tests/data/dsC/sub-01/dwi/sub-01_dir-LR_sbref.nii.gz

@@ -0,0 +1,5 @@
+{
+	"B0FieldIdentifier": "pepolar4pe",
+	"PhaseEncodingDirection": "i-",
+	"TotalReadoutTime": 0.005
+}

sdcflows/tests/data/dsC/sub-01/dwi/sub-01_dir-PA_dwi.nii.gz

@@ -0,0 +1,3 @@
+{
+	"Units": "rad/s"
+}

sdcflows/tests/data/dsC/sub-01/dwi/sub-01_dir-PA_sbref.json

@@ -0,0 +1,3 @@
+{
+	"EchoTime": 0.005
+}

sdcflows/tests/data/dsC/sub-01/dwi/sub-01_dir-PA_sbref.nii.gz

@@ -0,0 +1,3 @@
+{
+	"EchoTime": 0.00746
+}

sdcflows/tests/data/dsC/sub-01/dwi/sub-01_dir-RL_dwi.nii.gz

@@ -0,0 +1,4 @@
+{
+	"EchoTime1": 0.00500,
+	"EchoTime2": 0.00746
+}

sdcflows/tests/data/dsC/sub-01/dwi/sub-01_dir-RL_sbref.json

@@ -0,0 +1,5 @@
+{
+	"TaskName": "Rest",
+	"PhaseEncodingDirection": "j-",
+	"TotalReadoutTime": 0.05
+}

sdcflows/tests/data/dsC/sub-01/dwi/sub-01_dir-RL_sbref.nii.gz

@@ -214,6 +214,31 @@ def find_estimators(*, layout, subject, fmapless=True, force_fmapless=False):
     FieldmapEstimation(sources=<2 files>, method=<EstimatorType.ANAT: 5>,
                        bids_id='auto_00012')]
 
+    When the ``B0FieldIdentifier`` metadata is set for one or more fieldmaps, then
+    the heuristics that use ``IntendedFor`` are dismissed:
+
+    >>> find_estimators(
+    ...     layout=layouts['dsC'],
+    ...     subject="01",
+    ... )  # doctest: +ELLIPSIS
+    [FieldmapEstimation(sources=<5 files>, method=<EstimatorType.PEPOLAR: 2>,
+                        bids_id='pepolar4pe')]
+
+    The only exception to the priority of ``B0FieldIdentifier`` is when fieldmaps
+    are searched with the ``force_fmapless`` argument on:
+
+    >>> fm.clear_registry()  # Necessary as `pepolar4pe` is not changing.
+    >>> find_estimators(
+    ...     layout=layouts['dsC'],
+    ...     subject="01",
+    ...     fmapless=True,
+    ...     force_fmapless=True,
+    ... )  # doctest: +ELLIPSIS
+    [FieldmapEstimation(sources=<5 files>, method=<EstimatorType.PEPOLAR: 2>,
+                        bids_id='pepolar4pe'),
+    FieldmapEstimation(sources=<2 files>, method=<EstimatorType.ANAT: 5>,
+                       bids_id='auto_00000')]
+
     """
     from .. import fieldmaps as fm
     from bids.layout import Query
@@ -313,6 +338,8 @@ def find_estimators(*, layout, subject, fmapless=True, force_fmapless=False):
 
     from .epimanip import get_trt
 
+    # Sessions may not be defined at this point if some id was found.
+    sessions = layout.get_sessions()
     for ses, suffix in sorted(product(sessions or (None,), fmapless)):
         candidates = layout.get(suffix=suffix, session=ses, **base_entities)
 
@@ -324,6 +351,7 @@ def find_estimators(*, layout, subject, fmapless=True, force_fmapless=False):
         for candidate in candidates:
             meta = candidate.get_metadata()
             pe_dir = meta.get("PhaseEncodingDirection")
+
             if not pe_dir:
                 continue