[ENH] BEP001 - qMRI maps and some additional metadata

[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,

So far 4 BEP-001 PRs have been merged in the scope of 1.5.0 milestone. These PRs introduced i) a new common principle file-collections, ii) the entities it will use (inv, mt,flip; part and echo were present) and iii) (finally) resolved the long-discussed RepetitionTime issue.

Quick side note for maintainers (@effigies, @sappelhoff ), #681 is not listed there, you may want to add it to the milestone for completeness. EDIT SA: done.

Drawing upon these recent additions, in this Part-5/6 of BEP001 pull requests, we would like to propose including a list of (19) parametric maps and to clean up the existing table of anatomical images, which lacked descriptions and contained some ambiguous suffixes. Lastly, we added some metadata fields.

Thanks to the concept of the file collections and the qMRI appendix (to be added), I think this PR is going to bring a lot of new use cases and clarity to the anatomy imaging data without inflating the section itself too much.

Relevant (minor) changes

• Add legacy table to list deprecated suffixes (T2, PD and FLASH).
• Improve the definition of NumberShots and fix some typos
• Add template in the file collections appendix to clarify naming of files in a file collection.
• Change modality_label with suffix in the anat template as the term modality becomes overloaded otherwise.
• Update anat.yml

Before updating the /schema/datatypes/anat.yml further, I wanted to have @tsalo 's opinion about whether or not to include file-collection associated suffixes (e.g. MPM, MP2RAGE) and entities (flip,inv,mt) to this file. I did not run the bids_schema yet to update the entity table.

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.

[tsalo]

Before updating the /schema/datatypes/anat.yml further, I wanted to have @tsalo 's opinion about whether or not to include file-collection associated suffixes (e.g. MPM, MP2RAGE) and entities (flip,inv,mt) to this file. I did not run the bids_schema yet to update the entity table.

Yes, please include those suffixes in that file. It doesn't have to happen in this PR if you consider it out-of-scope, but it should happen at some point.

[agahkarakuzu]

Yes, please include those suffixes in that file. It doesn't have to happen in this PR if you consider it out-of-scope, but it should happen at some point.

Thank you @tsalo, which command should I run to generate the entity table?

I will soon address all the comments you made above.

[tsalo]

Here is what you'll need to run:

bids-specification/tools/bids_schema.py

Lines 453 to 454 in ad73668

	>>> python bids_schema.py entitytable ../src/schema/ \
	>>> ../src/99-appendices/04-entity-table.md

However, if by some miracle we get #610 merged before this PR, you won't need to run anything at all.

[sappelhoff]

However, if by some miracle we get #610 merged before this PR, you won't need to run anything at all.

I'd love to get that merged, but it may be more reasonable to do once the ASL PR is merged. (and then a proper rebasing and getting the #610 pr to date again is done) WDYT?

The other option would be to merge #610, but then to make lots of new formatting requests to the ASL PR. Not sure here what would be best.

[tsalo]

@sappelhoff Perhaps we can try to fit it between ASL and PET, then? Not sure how that will interact with qMRI, but it's not a big deal if it comes after.

[sappelhoff]

@sappelhoff Perhaps we can try to fit it between ASL and PET, then? Not sure how that will interact with qMRI, but it's not a big deal if it comes after.

Yes, we should definitely do it BEFORE PET 👍

[agahkarakuzu]

@tsalo @sappelhoff I run the bids_schema at 72227e3, worked beautifully! Well, tests are failing for some reason, not sure if it has anything to do with this.

[effigies]

@agahkarakuzu I'm going to push some small styling fixes in the next few minutes that should fix at least some tests, if you want to wait before committing more...

[agahkarakuzu]

Sure @effigies, please go ahead. I will look at those changes and try to watch out for them in upcoming commits.

[effigies]

The build failures are due to a reference to 99-appendices/11-qmri.md. Done for now.

[agahkarakuzu]

The build failures are due to a reference to 99-appendices/11-qmri.md. Done for now.

@tsalo @effigies @sappelhoff I can add 11-qmri.md in this PR if it is not too much.

[effigies]

The build failures are due to a reference to 99-appendices/11-qmri.md. Done for now.

@tsalo @effigies @sappelhoff I can add 11-qmri.md in this PR if it is not too much.

I will defer to their judgment. I haven't read much yet, so don't have a sense of the scope. I was just trying to get it so it would build and I could read the rendered version before commenting on the source.

[sappelhoff]

@tsalo @effigies @sappelhoff I can add 11-qmri.md in this PR if it is not too much.

I think that'd be manageable, as it's all contained in a single file with all additions (no complex deletions/additions/replacements)

[effigies]

Okay, I've looked through it and though it's large, it's quite focused. I think we could include an appendix without overburdening the PR.

Some comments at this point.

[effigies]

LGTM.

[tsalo]

I just have a couple of questions and flagged typos remaining, although they're all collapsed together in the Conversations tab.

[agahkarakuzu]

@tsalo I collapsed all the comments (especially the ones with minor fixes) with commit hashes. I’ll go through them again to see which questions/suggestions I missed.

[effigies]

Went back to look at the remaining issues, so while I was at it, I summarized (and expand slightly) @tsalo's comments so they an be at the front of the conversation:

1. MTsat, UNIT1 seem like they do not qualify for the table following "Structural MR images whose intensity is represented in a non-arbitrary scale constitute parametric maps. Currently supported parametric maps include:". Should they be moved to the "Currently supported non-parametric structural MR images"? ([ENH] BEP001 - qMRI maps and some additional metadata #690 (comment))
2. Non-parametric anatomical grouping suffixes from "File collections" should be noted in "Anatomy imaging data", but in less detail, linking to the appendix. ([ENH] BEP001 - qMRI maps and some additional metadata #690 (comment))
3. TB1map and RB1map should be moved to a new parametric table under "Fieldmap data" ([ENH] BEP001 - qMRI maps and some additional metadata #690 (comment)), and the current table should be listed as non-parametric tables? (, [ENH] BEP001 - qMRI maps and some additional metadata #690 (comment))
4. Non-parametric fieldmap grouping suffixes from "File collections" should be noted in "Fieldmap data", but in less detail, linking to the appendix. ([ENH] BEP001 - qMRI maps and some additional metadata #690 (comment))
5. Define grayscale ([ENH] BEP001 - qMRI maps and some additional metadata #690 (comment))
6. Typos M2AGE and "Meta-data" ([ENH] BEP001 - qMRI maps and some additional metadata #690 (comment) and [ENH] BEP001 - qMRI maps and some additional metadata #690 (comment))

[agahkarakuzu]

Thank you @effigies, this was really helpful! I went through the list and addressed them. Items 2, 3 and 4 are quite similar, collectively suggesting to represent all the suffixes in the file collections in the MRI page as well. I noted some concerns about listing suffixes like VFA under the non-parametric table and those like TB1map under the Fieldmap Data table. For the remaining, I pushed commits following suggestions by @tsalo.

[tsalo]

LGTM

[effigies]

@agahkarakuzu @tsalo @Gilles86 I'm inclined to squash this into a single commit, but if any of you would prefer the whole history be preserved in the git tree, I can do a simple merge.

[Gilles86]

afaic you can just squash it :)

[agahkarakuzu]

@effigies I+1 for squash-merge

[sappelhoff]

so, does that conclude BEP001? :-)

how can we celebrate this properly?

[agahkarakuzu]

@sappelhoff hard to believe, but yes! I made myself some espresso to read rendered version on latest :)

[effigies]

Multiple measurements of whiskey?