Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
tsalo opened this issue Aug 3, 2020 · 10 comments
Labels
deprecation Proposals to remove entities, suffixes, etc. that are currently implemented. entities Changes to entities. suffixes Changes to suffixes.

Comments

@tsalo
Copy link
Member

tsalo commented Aug 3, 2020

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 tsalo added deprecation Proposals to remove entities, suffixes, etc. that are currently implemented. entities Changes to entities. suffixes Changes to suffixes. labels Aug 3, 2020
@tsalo
Copy link
Member Author

tsalo commented Aug 3, 2020

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
Copy link
Member Author

tsalo commented Aug 20, 2020

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
Copy link

oesteban commented Dec 8, 2020

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
Copy link
Member Author

tsalo commented Dec 9, 2020

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 bids-standard/bids-specification#424 would be much more accurate, so I'll post them here.

From bids-standard/bids-specification#424 (comment):

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 bids-standard/bids-specification#424 (comment):

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
Copy link

oesteban commented Dec 9, 2020

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 B0 measurement (i.e., the old _fieldmap).

@oesteban
Copy link

oesteban commented Dec 9, 2020

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
Copy link
Member Author

tsalo commented Feb 6, 2021

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
Copy link
Contributor

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
Copy link
Member Author

tsalo commented Sep 20, 2024

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.

@tsalo tsalo changed the title Deprecate phase and magnitude suffixes in favor of part and echo entities Deprecate phase and magnitude suffixes in favor of part and echo entities for field maps Sep 20, 2024
@yarikoptic
Copy link
Contributor

Sounds good!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
deprecation Proposals to remove entities, suffixes, etc. that are currently implemented. entities Changes to entities. suffixes Changes to suffixes.
Projects
None yet
Development

No branches or pull requests

3 participants