Update B0fieldIdentifier/Source when having multiple fieldmap runs

[marcelzwiers]

When sessions are interrupted, typically a new fieldmap is acquired. The IntendedFor dynamic value can already limit it's search scope to adjacent runs. The B0FieldIdentifier/Source pairs should get the same possibility (either from within bidscoin or as a post-processing tool), e.g. by adding a run-suffix to the B0Field tags

[mateuszpawlik]

I guess there is no timeline for this feature?

[marcelzwiers]

It will probably be in the next release, but I don't know when that will be. I also haven't thought very much about the best approach to solve this issue

[marcelzwiers]

The new <<session>> value disambiguates this for multi-session data, perhaps I can put it in the same machinery (e.g. <<run>>)

[marcelzwiers]

So just to be clear, for a template bidsmap with {B0FieldIdentifier: tag} and {B0FieldSource: tag}, the desired output for e.g. a repeated (aborted) acquisition paradigm of three functional runs + one fieldmap would be something like:

|-- fmap
|   |-- sub-001_run-1_magnitude1.json        <- {B0FieldIdentifier: tag1}   (SeriesNumber = 01)
|   |-- sub-001_run-1_magnitude2.json        <- {B0FieldIdentifier: tag1}   (SeriesNumber = 01)
|   |-- sub-001_run-1_phasediff.json         <- {B0FieldIdentifier: tag1}   (SeriesNumber = 01)
|   |-- sub-001_run-2_magnitude1.json        <- {B0FieldIdentifier: tag2}   (SeriesNumber = 08)
|   |-- sub-001_run-2_magnitude2.json        <- {B0FieldIdentifier: tag2}   (SeriesNumber = 08)
|   `-- sub-001_run-2_phasediff.json         <- {B0FieldIdentifier: tag2}   (SeriesNumber = 08)
|
`-- func
    |-- sub-001_task-rest_run-1_bold.json    <- {B0FieldSource: tag1}       (SeriesNumber = 02)
    |-- sub-001_task-rest_run-2_bold.json    <- {B0FieldSource: tag1}       (SeriesNumber = 03)
    |-- sub-001_task-rest_run-3_bold.json    <- {B0FieldSource: tag2}       (SeriesNumber = 09)
    |-- sub-001_task-rest_run-4_bold.json    <- {B0FieldSource: tag2}       (SeriesNumber = 10)
    `-- sub-001_task-rest_run-5_bold.json    <- {B0FieldSource: tag2}       (SeriesNumber = 11)

For the fieldmaps this is straightforward to implement (just increment the tag), but unfortunately it is not so easy for the functional scans...

[mateuszpawlik]

I'm no expert but this is how I understand the BIDS specification. When you assign the IntendedFor values in the maps, cannot you inject B0FieldIdentifiers to the functional JSONs?

[marcelzwiers]

That is not possible, because the semantics that IntendedFor can specify (one-to-many) is a subset of what the B0 tags can specify (many-to-many) -- hence the deprecation of IntendedFor

[marcelzwiers]

I implemented this feature in the latest commit. Since you are the main user and presumably have a real-life case at hand, could you perhaps test it out to see if it does what you want? For usage see:

https://bidscoin.readthedocs.io/en/latest/bidsmap.html#fieldmaps-b0fieldidentifier-b0fieldsource

[mateuszpawlik]

I'll try to do some testing today. If I remember correctly, our problem was triggered by multiple fieldmaps in a single session (interrupted session). We used run: <<>> in the BIDS section of the fieldmaps, but we couldn't use it for B0FieldIdentifier/Source values.

[mateuszpawlik]

I tried with some generated data and the newest version on master branch:

SeriesNumber	sequence type
1	fmap magnitude1 and magnitude2 (at our scanner it is one sequence)
2	fmap pahsediff
3	func
4	fmap magnitude1 and magnitude2
5	fmap pahsediff
6	func
7	func

My template bidsmap

Options: 

  bidscoin:
    version: 4.3.1
    bidsignore: [extra_data/]
    subprefix: sub-
    sesprefix: ses-
    unknowntypes: [extra_data]
    ignoretypes: [exclude]
    unzip:
  plugins:
    dcm2niix2bids: 
      command: dcm2niix
      args: -b y -z n -i n
      anon: n
      meta: [.json, .tsv, .tsv.gz]

DICOM:

  subject: <<filepath:/sub-(.*?)/>>
  session: <<filepath:/sub-.*?/ses-(.*?)/>>

  func:
  - provenance:
    attributes:
      SeriesDescription: (?i)^func.*
    bids:
      suffix: bold
      run: <<>>
      task: rest
    meta:
      TaskName: rest
      B0FieldSource:
      - magnitude1_<<session:[0:]>>
      - magnitude2_<<session:[0:]>>
      - phasediff_<<session:[0:]>>

  fmap:
  - provenance:
    attributes: &fmap_dicomattr
      ImageType:
      SeriesDescription:
      EchoNumbers:
    bids: &fmap_bidsattr
      suffix: magnitude1
      run: <<>>
    meta: &fmap_metaattr
      IntendedFor: <<task:[0:]>>
      B0FieldIdentifier: magnitude1_<<session:[0:]>>
  - provenance:
    attributes:
      <<: *fmap_dicomattr
      SeriesDescription: (?i)^fmap.*
      ImageType: .*'M'.*
    bids:
      <<: *fmap_bidsattr
      suffix: magnitude2  # Due to magnitude1 and magnitude2 images in the same series (Siemens). dcm2niix will deal with it correctly.
    meta:
      <<: *fmap_metaattr
      B0FieldIdentifier: magnitude2_<<session:[0:]>>
  - provenance:
    attributes:
      <<: *fmap_dicomattr
      SeriesDescription: (?i)^fmap.*
      ImageType: '[''ORIGINAL'', ''PRIMARY'', ''P'', ''ND'']'
    bids:
      <<: *fmap_bidsattr
      suffix: phasediff
    meta:
      <<: *fmap_metaattr
      B0FieldIdentifier: phasediff_<<session:[0:]>>

The limits of B0FieldSource are not updated in the final json files. I see the debug logs Updating the b0fieldtag ... for fmaps but not for funcs. Could the reason be the set of niifiles in

bidscoin/bidscoin/bidscoiner.py

Line 449 in 2a0dd3a

for niifile in niifiles:

For example, for B0FieldSource: magnitude2_<<session:[0:]>> in the template bidsmap, I get "B0FieldSource": "magnitude2_<<ses1:[0:]>>" in the json file.

A question about the result of <<session>> dynamic value: the part after underscore in, for example, <<ses01_1>> is the run id, right? The docs don't explain that part:

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.

It also seems I have a problem with our magnitude fmaps being in one sequence. I don't know how to get different identifiers for them. But that's most probably not related.

Please let me know what I can do.

[marcelzwiers]

Ai, that's a bummer. In the new code, I treat IntendeFor and the B0Field tags more or less in the same way. Is the IntendedFor still working for you? One (rare) omission is that B0FieldIdentifiers outside the fmap folder are missed (I'll add a warning for this). You say you have generated data that can produce this issue, can you share it with me? That helps me tremendously!

[marcelzwiers]

It also seems I have a problem with our magnitude fmaps being in one sequence. I don't know how to get different identifiers for them. But that's most probably not related.

You want to give them different tags, so that suggests you mean that you have magnitude images from two fieldmaps in one folder? I have never seen that (and I'm pretty sure Siemens would never do that), shouldn't they have different SeriesNumbers? If the two magnitude images in the same folder are from the same fieldmap, then you want to use the same tag, no?

[marcelzwiers]

For example, for B0FieldSource: magnitude2_<session:[0:]> in the template bidsmap, I get "B0FieldSource": "magnitude2_<ses1:[0:]>" in the json file.

This should not happen and looks like a bug

A question about the result of <> dynamic value: the part after underscore in, for example, <<ses01_1>> is the run id, right? The docs don't explain that part

Yes, for e.g. ses-01, then <<session>> is replaced with 01 (the session label). But if you add a range specifier, then a separating underscore is appended to the session label, followed by the run-index of the bidsmap. So <<session:[]>> for a run-2 bidsmap will result in 01_2