Clarify that support for the bounding term is limited to strings, and…

… that list of strings are currently not supported (Github issue #198)

bidscoin/bidscoiner.py

@@ -428,8 +428,8 @@ def addmetadata(bidsses: Path, subid: str, sesid: str) -> None:
                 jsondata.pop('IntendedFor', None)
 
             # Populate the dynamic B0FieldIdentifier/Source values with a run-index string if they contain a range specifier
-            b0fieldtag = jsondata.get('B0FieldIdentifier') or ''
-            if fnmatch(b0fieldtag, '*<<*:[[]*[]]>>*'):                  # b0fieldtag = 'tag<<session:[lowerlimit:upperlimit]>>tag'
+            b0fieldtag = jsondata.get('B0FieldIdentifier')              # TODO: Refactor the code below to deal with b0fieldtag lists instead of assuming it's a string
+            if isinstance(b0fieldtag, str) and fnmatch(b0fieldtag, '*<<*:[[]*[]]>>*'):  # b0fieldtag = 'tag<<session:[lowerlimit:upperlimit]>>tag'
 
                 # Search in all runs for the b0fieldtag and store the relative paths to the session folder
                 niifiles = set()

docs/bidsmap.rst

@@ -66,7 +66,7 @@ In case duplicated field maps are acquired (e.g. when a scan failed or a session
 
 Fieldmaps: B0FieldIdentifier/B0FieldSource
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-According to the BIDS specification, within a subject folder, fieldmaps and their target scans can also be associated by way of `B0FieldIdentifier and B0FieldSource <https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/01-magnetic-resonance-imaging-data.html#using-b0fieldidentifier-metadata>`__ tags. However, in practice if you acquire multiple scan session, fieldmaps are only associated with targets that were acquired within the same scan session. To achieve that you can add a special ``<<session>>`` dynamic value to your tags, which will be replaced with the session label during bidscoiner runtime. And similar to the IntendedFor value, you can append a colon-separated "bounding" term to the session tag, e.g. ``<<session:[0:3]>>`` to uniquely tag the fieldmap and three subsequent associated runs. So for instance, if you have ``{B0FieldIdentifier: pepolar_<<session>>}`` in your bidsmap metadata, then your actual output metadata in your ``ses-01`` subfolder will be ``{B0FieldIdentifier: pepolar_01}`` and in your ``ses-02`` subfolder it will be ``{B0FieldIdentifier: pepolar_02}``. Here is an example with a single fieldmap and three subsequent functional runs that was interrupted after two runs and re-scanned, with ``mytag<<session:[0:3]>>`` as B0FieldIdentifier/Source value::
+According to the BIDS specification, within a subject folder, fieldmaps and their target scans can also be associated by way of `B0FieldIdentifier and B0FieldSource <https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/01-magnetic-resonance-imaging-data.html#using-b0fieldidentifier-metadata>`__ tags. However, in practice if you acquire multiple scan session, fieldmaps are only associated with targets that were acquired within the same scan session. To achieve that you can add a special ``<<session>>`` dynamic value to your tags, which will be replaced with the session label during bidscoiner runtime. And similar to the IntendedFor value, you can append a colon-separated "bounding" term to the session tag, e.g. ``<<session:[0:3]>>`` to uniquely tag the fieldmap and three subsequent associated runs. So for instance, if you have ``{B0FieldIdentifier: pepolar_<<session>>}`` in your bidsmap metadata, then your actual output metadata in your ``ses-01`` subfolder will be ``{B0FieldIdentifier: pepolar_01}`` and in your ``ses-02`` subfolder it will be ``{B0FieldIdentifier: pepolar_02}``. Here is an example with a single fieldmap and three subsequent functional runs that was interrupted after two runs and re-scanned, with ``mytag<<session:[0:3]>>`` as B0FieldIdentifier/Source value (NB: ``session`` is replaced by the session-label and ``:[0:3]`` is replaced by the fieldmap run-index)::
 
     |-- fmap
     |   |-- sub-001_ses-01_run-1_magnitude1.json      <- {B0FieldIdentifier: mytag<<ses01_1>>}  (SeriesNumber = 01)
@@ -83,6 +83,8 @@ According to the BIDS specification, within a subject folder, fieldmaps and thei
         |-- sub-001_ses-01_task-rest_run-4_bold.json  <- {B0FieldSource: mytag<<ses01_2>>}      (SeriesNumber = 10)
         `-- sub-001_ses-01_task-rest_run-5_bold.json  <- {B0FieldSource: mytag<<ses01_2>>}      (SeriesNumber = 11)
 
+NB: Currently, using a bounding term is only supported when the B0FieldSource/Identifier is a string (as in the example above), not when it is a list of strings (the latter is uncommon but allowed according to the BIDS specifications)
+
 .. note::
    The ``IntendedFor`` field is a legacy way to deal with field maps. Instead, it is recommended to use the ``B0FieldIdentifier`` and ``B0FieldSource`` fields that were introduced with BIDS 1.7, or use both. If you neither specify IntendedFor nor B0FieldIdentifier/Source values then your fieldmaps are most likely not going to be used by any BIDS application