[ENH] BEP001 - New entities: inv & mt

[agahkarakuzu]

---

Headnote

A while ago we started #508, where you can find information on the overall purpose of BEP001. The PR #508 was closed as discussions called for some major revisions and to split BEP001 pull requests into manageable parts.

---

Dear BIDS community,

In #668, we proposed the common principle of entity-linked file collections, which requires the addition of several new entities (inv, flip, mt) for the common use cases of quantitative MRI applications. Recently, flip has been merged #672 🎊 .

In this Part-4 of BEP001 pull requests, we would like to propose including the two remaining entities:

Entity	Corresponding metadata	Purpose
inv	InversionTime	To be used with the file-collections.
mt	MTState*	To be used with the file-collections.

* Several metadata fields have been added under the Sequence Specifics section for the MT-based application, including this key.

With echo, flip and part already present, this last addition opens the way for introducing 8 commonly used qMRI methods (e.g. MP2RAGE and MPM), which in turn enables the calculation of 13+ parametric maps! As the BEP001 team, we did our best to focus on introducing qMRI applications that we believe find the most common user base.

After merging this PR, #671 and #668, we will make pull requests to introduce suffixes for these methods and quantitative maps along with a qMRI appendix.

On behalf of the BEP001 core team:

Gilles de Hollander (@Gilles86), Alberto Lazari (@lazaral), Christophe Phillips (@ChristophePhillips), Kirstie Whitaker (@KirstieJane), Tibor Auer (@tiborauer).

Best regards.

[sappelhoff]

just commenting on the markdown structure: the table pipes on lines 55 to 60 will have to be aligned

[sappelhoff]

I still cannot push to this PR (same issue as in some previous PR) :-)

@agahkarakuzu can you please give me "maintain" or "admin" rights for the bids-bep001 organization: https://github.com/bids-bep001

?

[agahkarakuzu]

@sappelhoff unfortunately I can't because I am not the owner :/ if this need base to master, I can do that again.

[sappelhoff]

no, I just took a minute to align the table pipes and was hoping that I could push that change to the PR, but I can't :( so I think you'll have to do it yourself.

Or paste this below line 45:

| **Key name**                | **Requirement level** | **Data type**                          | **Description**                                                                                                                                                                                                                                                           |
|-----------------------------|-----------------------|----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| PulseSequenceType           | RECOMMENDED           | [string][]                             | A general description of the pulse sequence used for the scan (for example, MPRAGE, Gradient Echo EPI, Spin Echo EPI, Multiband gradient echo EPI).                                                                                                                       |
| ScanningSequence            | RECOMMENDED           | [string][] or [array][] of [strings][] | Description of the type of data acquired. Corresponds to DICOM Tag 0018, 0020 `Scanning Sequence`.                                                                                                                                                                        |
| SequenceVariant             | RECOMMENDED           | [string][] or [array][] of [strings][] | Variant of the ScanningSequence. Corresponds to DICOM Tag 0018, 0021 `Sequence Variant`.                                                                                                                                                                                  |
| ScanOptions                 | RECOMMENDED           | [string][] or [array][] of [strings][] | Parameters of ScanningSequence. Corresponds to DICOM Tag 0018, 0022 `Scan Options`.                                                                                                                                                                                       |
| SequenceName                | RECOMMENDED           | [string][]                             | Manufacturer's designation of the sequence name. Corresponds to DICOM Tag 0018, 0024 `Sequence Name`.                                                                                                                                                                     |
| PulseSequenceDetails        | RECOMMENDED           | [string][]                             | Information beyond pulse sequence type that identifies the specific pulse sequence used (for example, "Standard Siemens Sequence distributed with the VB17 software," "Siemens WIP ### version #.##," or "Sequence written by X using a version compiled on MM/DD/YYYY"). |
| NonlinearGradientCorrection | RECOMMENDED           | [boolean][]                            | Boolean stating if the image saved has been corrected for gradient nonlinearities by the scanner sequence.                                                                                                                                                                |
| MTState                     | RECOMMENDED           | [boolean][]                            | Boolean stating whether the magnetization transfer pulse is applied. Corresponds to DICOM tag (0018, 9020) `Magnetization Transfer`.                                                                                                                                      |
| MTOffsetFrequency           | RECOMMENDED           | [number][]                             | The frequency offset of the magnetization transfer pulse with respect to the central H1 Larmor frequency in Hertz (Hz).                                                                                                                                                   |
| MTPulseBandwidth            | RECOMMENDED           | [number][]                             | The excitation bandwidth of the magnetization transfer pulse in Hertz (Hz).                                                                                                                                                                                               |
| MTNumberOfPulses            | RECOMMENDED           | [number][]                             | The number of magnetization transfer RF pulses applied before the readout.                                                                                                                                                                                                |
| MTPulseShape                | RECOMMENDED           | [string][]                             | Shape of the magnetization transfer RF pulse waveform. Accepted values: `HARD`, `GAUSSIAN`, `GAUSSHANN` (gaussian pulse with Hanning window), `SINC`, `SINCHANN` (sinc pulse with Hanning window), `SINCGAUSS` (sinc pulse with Gaussian window), `FERMI`.                |
| MTPulseDuration             | RECOMMENDED           | [number][]                             | Duration of the magnetization transfer RF pulse in seconds.                                                                                                                                                                                                               |

[effigies]

Looks good. One thought:

[sappelhoff]

@sappelhoff unfortunately I can't because I am not the owner :/ if this need base to master, I can do that again.

@agahkarakuzu then who is the owner of that organization? There are no "public" members, so I cannot check myself. see: https://github.com/orgs/bids-bep001/people

It'd be good to give BIDS maintainers admin or at least maintainer rights for that organization. Otherwise we cannot make edits to PRs that are done from branches owned by the bids-bep001 organization.

cc @Gilles86

[Gilles86]

@KirstieJane is the sole owner of the bid-bep001 Github organization. Maybe she can help?

[agahkarakuzu]

This is also a bit on me, the initial idea was to merge our PRs to the bep001 branch on bids-organization (what we did in the first big PR and @KirstieJane gave me write access to it).However, splitting PRs and their co-occurrence made that approach a bit uneasy.

If @KirstieJane sees fit, adding a BIDS maintainer to the bep001 organization would be helpful to keep things going. I think we have 3-4 PRs left to cover the whole BEP001 proposal.

[neurolabusc]

@agahkarakuzu @sappelhoff @KirstieJane @tsalo I have been trying to add support for some of these changes to dcm2niix. I have a few issues

1. The BIDS Specification lists the field MTState as being boolean (true, false), and notes it corresponds to DICOM tag (0018, 9020). However, the DICOM tag lists three states: ON_RESONANCE, OFF_RESONANCE and NONE. Am I correct that the BIDS MTState should list true for either ON_RESONANCE or OFF_RESONANCE?
2. The field MRTransmitCoilSequence refers to a DICOM sequence (0018,9049) not a tag. Is this really intended? I would have thought that is specific DICOM tag would be more explicit, e.g. TransmitCoilType (0018,9051)
3. MatrixCoilMode documentation refers to DICOM tag 0018,9078. Can anyone provide any sample DICOM images that use this tag?
4. The documentation for the following BIDS fields do not provide DICOM tags: MixingTime, MTPulseDuration, SpoilingState, SpoilingType, SpoilingGradientMoment, SpoilingGradientDuration, MTOffsetFrequency, MTPulseBandwidth, MTNumberOfPulses, MTPulseShape, CoilCombinationMethod, NonlinearGradientCorrection, NegativeContrast, RepetitionTimePreparation. Are any of these details stored in DICOM images (e.g. Siemens proprietary CSA header, or GE protocol data block)? Are there any example DICOM files that are available that demonstrate these tags? Without exemplars, converters (dcm2niix, dicm2nii, etc.) will not be able to support these fields, and users will have to enter them manually. It seems that BIDS is now including a lot of meta data that people would like to have, without consideration whether this information is stored. It might be worth coordinating with the Research Collaboration Managers of Philips, GE and Siemens to identify relevant meta data.

[agahkarakuzu]

Hi @neurolabusc, thank you so much for looking into this! Happy to see that dcm2niix is catching up with the BIDS releases!

1. MTState is true when OFF_RESONANCE for the applications we cover, but not sure if different vendors have different conventions for this. For example, on Siemens ScanOptions: MT or SequenceVariant containing MTC value are other ways to infer that MT is true.
2. I found this. I don't know how exactly this one ended up on the list, but looks intentional.
3. The default would be CP (circular polarization), and the entries would look like Auto (CP), Auto (Dual), Auto (Triple). The value is set based on whether or which iPAT (parallel acceleration) is selected. At least on Siemens, this is the case, they all begin with Auto because channel clusters are automatically set by the system. I am not really aware of other possible entries.
4. Many of these fields are user and vendor specific. As you noted, manual entry would be a good option for a while. Often, none of these values can be found in the header.

For MP2RAGE things are clearer:

RepetitionTimePreparation: This corresponds to the RepetitionTime.
RepetitionTimeExcitation: If available, corresponds to EchoSpacing. If not (usually the case), twice the EchoTime can be used.

Again, these are for Siemens.

[neurolabusc]

@agahkarakuzu

1. If MTState is true when OFF_RESONANCE, what is MTState for ON_RESONANCE, and NONE?
2. This precisely illustrates the problem, 0018,9049 is a sequence, with some optional items and some required. This makes parsing the BIDS tag MRTransmitCoilSequence difficult. Can I suggest a clear one-to-one mapping from DICOM to BIDS to make the BIDS fields explicit. For example, BIDS field TransmitCoilType reflects DICOM tag 0018,9051 (and likewise TransmitCoilName -> 0018,1251; TransmitCoilManufacturerName -> 0018,9050).
3. Do you have DICOM images that illustrate these different settings? In order to implement and validate support for these tags, we need to describe how they are stored. Since you are using Siemens, I assume they are stored in the CSA header, to allow one to Phoenix the settings to a new system. For example, does the BIDS tag MatrixCoilMode correspond to the CSA ucCoilCombineMode, and since the CSA tag only provides a number, what is the mapping between that number and the desired data stored in BIDS?
4. In my opinion, we should be very considerate when proposing new fields to the BIDS standard. Specifically, we should consider what is available in the source data, working together with the manufacturers to ensure a unified definition and the opportunity for future automated extraction. We hope this will lead to years of curated data. There is huge opportunity for unintended consequences if we leave the burden on the person who acquires the data to manually generate these and interpret their definition. Specifically, engineers at GE (e.g. @mr-jaemin), Philips (e.g. @drmclem) and the Siemens research collaboration managers associated with my center have done a great job in supporting automated BIDS/NIfTI conversion. We should pro-actively engage these experts early on in the process.

[agahkarakuzu]

@neurolabusc

1. It is false when ON_RESONANCE and NONE.
2. Again, I am not fully aware of (or can't remember) why this was added in the first place. Can we trace back and see when this was added? GitLens shows that this table was updated during [ENH] Bep 005: Arterial Spin Labeling #669. @patsycle do you have any insights on this?
3. Siemens options are Adaptive Combine or Sum of squares. The tag ucCoilCombineMode is under the ASCONV header. I checked some images and found out that:
   If Adaptive Combine then ucCoilCombineMode is 2 (0x2)
   If Sum of squares then ucCoilCombineMode is 1 (0x1)
4. I totally agree with this. There are tags of critical importance, especially for several quantitative applications, but there is no easy way to access them. The ones that we introduced in BEP001 has to do mostly with spoiling or MT. In either case, we are generally talking about WIP sequences, where user knows these values because they are in contact with the methods developers. On the other hand, for stock sequences, some of these values are hidden. For example, MTOffsetFrequency. When I see sPrepPulses.ucMTC (0X1) on the ASCONV header, I know that the MTState is true, but I don't know what is the offset frequency (MTOffsetFrequency in BIDS) by reading the metadata. Or, I know that RF spoling is on (sFastImaging.ulEnableRFSpoiling), but then again, no way to know what sSpecPara.lPhaseCyclingType = 1 is actually telling me, or what is the phase increment values, etc. We added these field counting on the fact that people sharing this data know what they are, even they had to add them manually, so important information can be provided to the users. I am all in for working with vendors on such issues.

[neurolabusc]

@agahkarakuzu Thanks. Can you please test dcm2niix development version v1.0.20210616 and validate the performance:

• MTState reflects 0018,9020 where ON_RESONANCE and NONE result in false and OFF_RESONANCE results in true.
• CoilCombinationMethod is set based on Siemens CSA ucCoilCombineMode where 1 results in Sum of Squares and 2 results in Adaptive Combine. Since JSON is case sensitive, can you confirm spelling and explicitly enumerate in the BIDS specification, e.g. the specification suggests rSOS for Sum of Squares, and you wrote Sum of squares, while the Siemens PDF's list as Sum Of Squares.
• MatrixCoilMode is set based on Siemens CSA sPat.ucPATMode where 1 results in SENSE and 2 results in GRAPPA. The values SENSE and GRAPPA are both explicitly listed in the BIDS specification. Personally, I would advocate changing the specification to explicitly enumerate generic terms (e.g. Image domain PI and K-space PI) rather than manufacturer trade names (e.g. SENSE, ASSET, RAPID, SPEEDER).
• I would advocate removing MRTransmitCoilSequence from the BIDS specification. If this information is useful, list the specific DICOM tags.
• I can add other BIDS fields defined by this PR if someone can provide examples.
• As a procedural suggestion, perhaps new BEPs should address implementation and provide reference datasets of both the input DICOM images and the corresponding correct solution prior to being merged. For example, consider the slice time correction validation repository dcm_qa_stc that includes data from different vendors and illustrates edge cases. A nice property of these validation datasets that include both the DICOMs and the curated BIDS is that every build of dcm2niix is automatically tested for correct conversion (using Travis CI) to prevent regressions.

[agahkarakuzu]

Sum of Squares, and you wrote Sum of squares, while the Siemens PDF's list as Sum Of Squares.
Indeed, it is Sum of Squares in PDF, I did not pay attention while typing, my bad. If there are many fMRI datasets used rSOS as stated in the description, should we consider using it instead?

• Although they are all based on SENSE, vendors use slightly modified versions of the original implementation (e.g. Siemens mSENSE, others ASSET, SPEEDER etc.). For k-space based methods it is less crowded, GRAPPA for Siemens, ARC/TurboARC for GE. Given that (i) this is common knowledge, (ii) we don't know the exact implementation differences between these product names, and (iii) the third (hybrid) type of PI methods are not adopted by vendors, Image domain PI and K-space domain PI classification sounds reasonable. Documenting this somewhere for clarity would be helpful.
• Re MRTransmitCoilSequence I don't have a preference. I suggest finding out who added this and why before taking action.

As a procedural suggestion, perhaps new BEPs should address implementation and provide reference datasets of both the input DICOM images and the corresponding correct solution prior to being merged.

I'll do my best to cover BEP001 methods. @ChristophePhillips @lazaral do you have some DICOM images to share for the MPM data and the fieldmaps hMRI covers? Majority of the new metadata fields pertains to them. I will share one DICOM per MP2RAGE image (no need to share whole volume I guess) and document which headers map to which BIDS metadata. I'll do the same for MTS and MTR.

@neurolabusc is it possible to define simple conditions and calculations within dcm2niix to populate certain fields? For example, NumberShots can benefit from that.

I will test out the version you mentioned as soon as possible.

[agahkarakuzu]

I tested dcm2niix from development branch, compiled for commit rordenlab/dcm2niix@09dfdb7.

1. 3D FLASH with MT on

"CoilCombinationMethod": "Adaptive Combine",
"MatrixCoilMode": "GRAPPA",

The field MTState did not show up because my image did not have (0018,9020). The relevant attributes I can find are:

• `"ScanOptions": "MT" (from dcm2niix json)
• sPrepPulses.ucMTC = 0x1 (available in ASCONV)
• "SequenceVariant": "MTC\SP", (MTC, from dcm2niix json)

2. TFL B1 mapping that uses SOS coil combination and mSENSE:

"CoilCombinationMethod": "Sum of Squares",
"MatrixCoilMode": "SENSE",

[neurolabusc]

• Latest commit will detect MTState from Siemens CSA header.
• I am happy to add support for BIDS fields if they can be explicitly, consistently and automatically detected from the DICOM images. On the other hand, if user input is required, this seems beyond the remit of dcm2niix, and should be included in a scriptable wrapper like heudiconv or Dcm2Bids.

[agahkarakuzu]

Thank you @neurolabusc!

... if user input is required, this seems beyond the remit of dcm2niix

But it is possible to define a parameter based on multiple fields and conditions (without manual intervention), right?

[ChristophePhillips]

Hi @agahkarakuzu

I'll do my best to cover BEP001 methods. @ChristophePhillips @lazaral do you have some DICOM images to share for the MPM data and the fieldmaps hMRI covers? Majority of the new metadata fields pertains to them.

Yeah I should be able to pull out one DICOM file per 3D image in one of our MPM acquisition. It might be a good idea though to try and get the same from Martina Callaghan's open data set (I can ask her). This way we would have the open data in DICOM and NIfTI format. Thought?

[lazaral]

Hi @ChristophePhillips @agahkarakuzu, asking Martina for the DICOMs of the open MPM dataset is definitely a great idea. Also, if you're mostly interested in the DICOM metadata for MPMs, you can actually find a lot of them in the NIFTI's json file, since the standard hMRI pipeline copies and pastes a lot of DICOM metadata directly into the nifti json file, if I remember correctly.

The link to the openly-available dataset (with the jsons in question) is here: https://owncloud.gwdg.de/index.php/s/iv2TOQwGy4FGDDZ

[neurolabusc]

@lazaral the openly available dataset you link to is insufficient to help us:

1. It only includes the NIfTI/JSON files, and not the DICOM images that they were derived from. If we can get the DICOMs for these, we can determine and validate the correct conversion.
2. The JSON files are a direct SPM12 dump of the DICOM and CSA headers, but does not include any of the BIDS tags defined by BEP001, e.g. MixingTime, MTPulseDuration, SpoilingState, SpoilingType, SpoilingGradientMoment, SpoilingGradientDuration, MTOffsetFrequency, MTPulseBandwidth, MTNumberOfPulses, MTPulseShape, CoilCombinationMethod, NonlinearGradientCorrection, NegativeContrast, RepetitionTimePreparation. Therefore, it does not help us infer how to calculate the new BEP001 fields from the DICOM tags and CSA header. What I was hoping to do is find out a way to detect the new tags for BEP001 (which are underspecified in the current specification).

@agahkarakuzu the goal of dcm2niix is to populate all BIDS fields where we can determine them reliably and accurately from the source data. If you can tell me the formula to derive these new tags from the DICOM tags or CSA header, it would be great to include them.