Deprecate phase and magnitude suffixes in favor of part and echo entities for field maps

[tsalo]

If bids-standard/bids-specification#424 is merged, then there will be an entity that delineates magnitude/phase in the specification. There already is one that delineates multi-echo data (echo). These two entities can replace the existing func suffix “phase” and the existing fmap suffixes “phase1”, “phase2”, “magnitude1”, and “magnitude2”. I’m not sure how best to label “phasediff” with the current proposal, but I’m sure we can figure out a way.

Original title: Deprecate phase, phase1, phase2, phasediff, magnitude1, magnitude2 suffixes in favor of part and echo entities Original authors: @tsalo

[tsalo]

To clarify with examples:

• fmap/
  • sub-X_run-1_magnitude1.nii.gz --> sub-X_run-1_echo-1_part-mag_epi.nii.gz
  • sub-X_run-1_magnitude2.nii.gz --> sub-X_run-1_echo-2_part-mag_epi.nii.gz
  • sub-X_run-1_phase1.nii.gz --> sub-X_run-1_echo-1_part-phase_epi.nii.gz
  • sub-X_run-1_phase2.nii.gz --> sub-X_run-1_echo-2_part-phase_epi.nii.gz
• func/
  • sub-X_task-Y_run-1_bold.nii.gz --> sub-X_task-Y_run-1_part-mag_bold.nii.gz
  • sub-X_task-Y_run-1_phase.nii.gz --> sub-X_task-Y_run-1_part-phase_bold.nii.gz

[tsalo]

Does anyone have any idea how we would want to support phase-difference images here?

Would a new suffix like epiDiff work? Or maybe a new entity?

[oesteban]

Phase[diff] are typically not acquired with EPI (which would imply analytically invert a generally nondiffeomorphic deformation).

_fieldmap are not acquired with EPI.

Why epi - which is the only sequence-mapped suffix allowed under fmap/ that doesn't actually measure the field map?

[tsalo]

Why epi - which is the only sequence-mapped suffix allowed under fmap/ that doesn't actually measure the field map?

The reason is that I don't know that much about the sequences going into field maps 😞. I just assumed phase-difference field maps were EPIs with short echo times. It sounds like the two ideas you proposed in https://github.com/bids-standard/bids-specification/pull/424 would be much more accurate, so I'll post them here.

From https://github.com/bids-standard/bids-specification/pull/424#issuecomment-741196216:

fmap/
   sub-1_part-mag_echo-1_gre.nii.gz       # gre = gradient-recalled echo; equiv. magnitude1
   sub-1_part-mag_echo-2_gre.nii.gz       # equiv. magnitude2
   sub-1_part-phase_echo-1_gre.nii.gz     # equiv. phase1
   sub-1_part-phase_echo-2_gre.nii.gz     # equiv. phase2
   sub-1_part-mag_sei.nii.gz              # sei = spiral-echo imaging; equiv. to magnitude
   sub-1_part-phase_sei.nii.gz            # equiv. to _fieldmap
   sub-1_part-mag_gre.nii.gz              # equiv. to _magnitude1 corresponding to phasediff
   sub-1_part-phase_gre.nii.gz            # equiv. to phasediff

From https://github.com/bids-standard/bids-specification/pull/424#issuecomment-741208903:

fmap/
   sub-1_part-mag_echo-1_phasediff.nii.gz       # equiv. magnitude1
   sub-1_part-mag_echo-2_phasediff.nii.gz       # equiv. magnitude2
   sub-1_part-phase_echo-1_phasediff.nii.gz     # equiv. phase1
   sub-1_part-phase_echo-2_phasediff.nii.gz     # equiv. phase2
   sub-1_part-mag_phasediff.nii.gz              # equiv. to _magnitude1 corresponding to phasediff
   sub-1_part-phase_phasediff.nii.gz            # equiv. to phasediff
   sub-1_part-mag_fieldmap.nii.gz               # equiv. to magnitude
   sub-1_part-phase_fieldmap.nii.gz             # equiv. to _fieldmap

One thing I would note about the gre/sei idea is that I think the SWI BEP includes a GRE suffix and BEP001 includes an MEGRE suffix, so I'd make both suffixes upper-case.

Regarding the phasediff suffix idea, I think phasediff is a little confusing. I'd automatically interpret it as the difference of phase images, as it's defined in the current specification. Having part-mag with that would be a little weird.

[oesteban]

The reason is that I don't know that much about the sequences going into field maps 😞. I just assumed phase-difference field maps were EPIs with short echo times. It sounds like the two ideas you proposed in bids-standard/bids-specification#424 would be much more accurate, so I'll post them here.

Gotcha :). This is why we are working through PR, so I'm happy to see that there's not a strong opinion behind that proposal and therefore, you are looking forward to make all the changes it takes. Thanks for pushing on this -a bit abandoned- part of the MRI specifications.

One thing I would note about the gre/sei idea is that I think the SWI BEP includes a GRE suffix and BEP001 includes an MEGRE suffix, so I'd make both suffixes upper-case.

Yes, I don't love these particular two. To make it worse - for instance, Philips generates fieldmaps in Hz (meaning, they are phase-unwrapped, ready to use), and I have no clue as to whether they use GRE and use software to provide you the b0_map (that's apparently their vendored sequence name) or they use SEI. Also, it is not unthinkable at all that, e.g. Siemens, starts spitting phase difference maps with the phase unwrapped.

So, the definite, more compact way to represent these fieldmaps would be:

fmap/
   sub-1_part-mag[_echo-{1,2}]_fieldmap.nii.gz
   sub-1_part-phase[_echo-{1,2}]_fieldmap.nii.gz

And make MANDATORY two metadata fields:

{
  "Units": "rad/s",
  "PhasedWrapped": true
}

When units are not rad or rad/s, the PhaseWrapped MUST be false. Because units are "rad/s" here (and this fieldmap should not define echo-) you would know this is a phasediff and the EchoSpacing OR EchoTime1&2 metadata is MANDATORY.

When units are rad then echo- MUST be defined. echo- should also make MANDATORY to define EchoTime on the JSON sidecar. And we know this is the phase1/2 type of fieldmap.

Finally, when units are Hz (or ppm, if you want to look fancy and add a potential complication point for no clear reason), then you know this is a direct B₀ measurement (i.e., the old _fieldmap).

[oesteban]

And, if you don't want to reuse _fieldmap because of the obvious overlap with the current specs, please replace the above pattern with:

fmap/
   sub-1_part-mag[_echo-{1,2}]_B0.nii.gz
   sub-1_part-phase[_echo-{1,2}]_B0.nii.gz

with the big B (do not please suggest a small b).

And if you want to be a purist:

fmap/
   sub-1_part-mag[_echo-{1,2}]_deltaB0.nii.gz
   sub-1_part-phase[_echo-{1,2}]_deltaB0.nii.gz

or even more so:

fmap/
   sub-1_part-mag[_echo-{1,2}]_B0diff.nii.gz
   sub-1_part-phase[_echo-{1,2}]_B0diff.nii.gz

More context for this is given here: https://www.nipreps.org/sdcflows/api/sdcflows.workflows.fit.fieldmap.html

[tsalo]

I like both deltaB0 and B0diff. So it looks like this, then?

fmap/
   sub-1_echo-1_part-mag_B0.nii.gz          # equiv. magnitude1
   sub-1_echo-2_part-mag_B0.nii.gz          # equiv. magnitude2
   sub-1_echo-1_part-phase_B0.nii.gz        # equiv. phase1
   sub-1_echo-2_part-phase_B0.nii.gz        # equiv. phase2
   sub-1_part-mag_B0.nii.gz                 # equiv. magnitude
   sub-1_part-phase_B0.nii.gz               # equiv. fieldmap
   sub-1_echo-1_part-mag_B0.nii.gz          # equiv. magnitude1 corresponding to phasediff
   sub-1_part-phase_<B0diff|deltaB0>.nii.gz # equiv. phasediff
   sub-1_dir-AP_epi.nii.gz                  # same as before
   sub-1_dir-PA_epi.nii.gz                  # same as before

Two things I want to take into account from the qMRI BEP:

1. The use of w and map in suffixes to indicate that a map is "weighted" by a contrast or is quantitative, respectively. E.g., T1w vs. T1map. Should that come into play here? Maybe by having what is currently called _fieldmap as B0map and the others as B0w? Does that make sense?
2. B1+/- mapping. I know next to nothing about this, but 2.0 is an opportunity to synchronize B0 and B1+/- mapping terminology. Perhaps we can pull in some qMRI folks for that part.

[yarikoptic]

FWIW, phase is already marked deprecated for func data. But there is no deprecated labels for fmap suffixes yet. Should this be worked on further to aim for BIDS 2.0?

[tsalo]

Yes absolutely. If others agree, then I think we could propose these new suffixes in BIDS 1.x and then drop the old versions in 2.0.

[yarikoptic]

Sounds good!