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

[ENH] BEP001 - Quantitative MRI #508

Closed
wants to merge 112 commits into from
Closed

[ENH] BEP001 - Quantitative MRI #508

wants to merge 112 commits into from

Conversation

agahkarakuzu
Copy link
Contributor

Dear BIDS community,

The field of anatomical MRI has recently seen a bloom of techniques that allow us
to characterize brain tissue in new ways and visualize brain structure that remained
invisible before.

This new set of techniques has become known as quantitative MRI (qMRI),
offering the possibility of quantifying brain tissue in physical units, such as
T1, T2 and T2* in seconds. Quantitative MRI provides neuroimaging researchers
with numerous novel applications such as the delineation of specific subcortical nuclei
in the subcortex, parcellation of the visual system based on laminar myeloarchitecture and measuring the myelination of white matter bundles in an absolute scale, just to count a few.

Unfortunately, these data are not easily collected and need computational modeling
to come to full bloom. Of course, BIDS could offer some amazing tools to help
researchers make both qMRI data and software more easily accessible. However,
currently BIDS cannot accommodate qMRI data as it confines the description of
anatomical images to grayscale T1- or T2-weighted images.

Thanks to the contributions from dozens of researchers over the course
of 3 years, we are very happy to make this pull request for the BIDS extension
proposal 001
to provide support for a wide range of anatomical MRI applications.
This extension will facilitate:

  1. the adoption of qMRI techniques in the research community
  2. the development of accessible software to process qMRI data.

To make this possible, we propose to extend the concept of suffix, in the domain
of anatomical (anat) data. Specifically, anatomical images can now be described
in one of the following 3 suffix sub-categories:

  1. Conventional MRI suffixes for traditional MRI contrasts, e.g., _T1w and _T2w
  2. Grouping suffixes to group together multi-contrast images collected for qMRI
    applications, e.g., _MP2RAGE and _MPM
  3. Quantitative map suffixes for the quantitative parametric images such as
    _T1map (s), _T2map (s) and _Chimap (ppm).

Categories (2) and (3) allow data set curators to clearly indicate
which images should be considered together in further (computational) processing,
and which images have interpretable units, respectively.

To further accommodate researchers using qMRI, we also introduced some new metadata
fields
that are particularly important when fitting biophysical models to MRI data
and guidelines on which metadata are necessary for some more common qMRI protocols.

Most of these metadata fields should not be controversial, but some of you might
be surprised that we introduced two new fields, called RepetitionTimePreparation
and RepetitionTimeExcitation. These do not replace, but extend the original
RepetitionTime-field. Please note that the original definition of RepetitionTime
in the main specification, which reads as follows:

The time in seconds between the beginning of an acquisition of one volume and
the beginning of acquisition of the volume following

does not generalize to most anatomical MRI protocols. Moreover, in some qMRI
applications, e.g. in the increasingly common MP2RAGE protocol, a (set of) readout
block(s) with multiple excitation pulses is nested in a larger sequence block with,
for example, an inversion pulse. Therefore, we need two definitions of repetition
time: one for the time between preparation blocks, and one for the time between
excitation pulses within each readout block.

Another addition of BEP-001 that might raise some eyebrows is that we moved three
anatomical suffixes (_T2star, _FLASH, and _PD) to a legacy table. This means
that using these suffixes is still valid BIDS, but we recommend against using them,
because these suffixes are ambiguous and do not adhere to the structure of the other
anatomical suffixes. Please note that these three suffixes are currently not very
common anyway and that we extensively explain why we recommend against them in the
legacy table.

To conclude, we are very excited to, after years of hard work -not just by us,
but also many others- to share this extension proposal with the larger BIDS community!
We hope that you can give us some constructive feedback. This would allow us to
improve the extension further and finally offer researchers from across the globe
the opportunity to combine the wonders of BIDS and quantitative MRI.

Finally you can find 8 real-life qMRI example data sets organized according to
our BIDS extension proposal at https://osf.io/k4bs5/.

BEP001 GitHub repository: https://github.com/bids-bep001/bids-specification

We would like to note that this PR includes changes that are highly relevant to #424 by @tsalo. The corresponding discussions can be found here.

Kind regards,

Gilles de Hollander (@Gilles86), Agah Karakuzu (@agahkarakuzu), Alberto Lazari (@lazaral), Christophe Phillips (@ChristophePhillips), Kirstie Whitaker (@KirstieJane)

agahkarakuzu and others added 30 commits April 22, 2020 05:15
* Suffix has a wider semantic scope than "modality"
* So that it can better represent different types of anatomy imaging applications
* The removed table was an incoherent collection of MRI terms, in which sequence names (e.g. FLASH), weighting labels (e.g. T1w), parametric maps (e.g. T1map) and unspecified MR attributes (e.g. PD) were collapsed under the term "modality". 
* Format specified by a sequence name does not necessarily ensure interchangeability, given that the same sequence can generate different contrasts.  
* Descriptions were missing for 8/14 entries. 
* Existing descriptions were not comprehensive.
* A brief description, expanding on the scope of anatomy imaging using MRI
* Added as a subsection to the Anatomy imaging data section.
* Why a bundle of images may be needed. 
* Introduce the term `grouped scan collections` 
* Why suffix is made adaptive to the type of anatomy imaging method.
* Suffix is divided into 3 categories for: 
     * Conventional MRI
     * Grouped scans
     * qMRI maps 
* Add note about legacy suffixes
* For existing datasets
* Function description
* VFA, IRT1, MP2RAGE, MESE, MEGRE, MTR, MTS, MPM, B1DAM
* Reference to the entity table and qMRI appendix 
* Note regarding the use of constituent images of a grouping suffix for structural data processing.
* Function description
* T1map, T2map, T2starmap, R1map, R2map, R2starmap, PDmap, MTRmap, MTsat, UNIT1, T1rho, MWFmap, PDT2map, B1plusmap
[ENH] Suffix entity & Legacy table
* Substitute commit to #6, including changes by @Gilles86.
[ENH] Suffix type II: Grouping suffix
@sappelhoff
Copy link
Member

i think bids does not specify anywhere how timing and other numeric information should be encoded in the json file

I think so too, yes. What's worse is that we generally don't specify which "data types" (string, array, object, numeric, ...) to use in the JSON files. On the plus side, the validator checks some of these data types --> but apparently not everything ... or "not everything well enought".

Sounds to me like we should open an issue and discuss how to remedy this problem with a small PR.

@@ -161,6 +396,75 @@ can also be used to make that distinction. At what level of detail to make the
distinction (e.g. just between RARE and FLASH, or between RARE, FLASH, and
FLASHsubsampled) remains at the discretion of the researcher.

#### The `echo` entity
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does not specify any units in this section.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@satra should not units be specified in the EchoTime entry of the Timing Parameters metadata table? On the other hand, I totally agree with your comment regarding data types, happy to adapt BEP001 once there is a solution.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@agahkarakuzu - you are correct the units are in the timing table. perhaps what's needed is a link between the mention in this section and the link to the table. i know this is being discussed in a separate issue, so for this BEP, please feel free to resolve this issue for now.

of the MRI signal is represented in voxel data. The `part-<label>` key/value pair is
associated with the DICOM tag
[0008,9208](https://dicom.innolitics.com/ciods/enhanced-mr-image/enhanced-mr-image/00089208).
Allowed label values for this entity are `phase`, `mag`, `real` and `imag`,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should part-complex be supported too?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tsalo while we were discussing about adding real and imag as supported part values for complex data, mixed type did not appear to be a common choice among many people. Do you know cases where it can be useful?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's definitely not common to store complex data. The only thing I'm aware of that uses complex data right off the bat is dwidenoise, but it is supposed to be the first thing used (before any other preprocessing).

@agahkarakuzu
Copy link
Contributor Author

agahkarakuzu commented Jul 29, 2020

Converging to a solution for Grouping Suffix

A few weeks ago @tsalo @emdupre and I had a zoom call to lay out the issues with the grouping suffix concept that may interfere with other modalities, which is nicely summarized in this gdoc and mentioned by #529 #530.

Today we had a BEP001 meeting with @Gilles86 @tiborauer @ChristophePhillips @lazaral and took this issue in serious consideration. I would like to share our solution with you and solicit your feedback!

we talked about the idea of divorcing the idea of grouped scans from specific suffixes, given that some suffixes in BEP001 refer to multiple files from the same acquisition and some refer to multiple files from different acquisitions

In the BEP001 meeting we mostly agreed with this comment by @tsalo. There is no need to specify a suffix as a grouping suffix exclusively, given that some suffixes such as bold may or may not play such a "grouping" role depending on the application. Instead, it would be much more constructive to create an appendix that elaborates on when and with which entities do we use suffixes for logical grouping of parametrically linked images in the context of various experiments from ME-fMRI to qMRI applications. In this regard, as suggested by #529 , introducing the concept of logical grouping of parametrically linked images via suffixes to the common principles can be favorable and there is no need for a singular categorical expression such as grouping suffix.

On the other hand, we agreed that it is imperative to draw the line between parametric and non-parametric image suffixes for obvious reasons. In sum, we can list our solution as follows:

  • Suffixes are going to be classified based solely on the (qualitative/quantitative) nature of the data:
    • Suffixes for parametric images
    • Suffixes for non-parametric images
  • All the suffixes will be given in the same table, an additional column will be added to denote whether the suffix is associated with a parametric or a non-parametric data.
  • The entity table will be updated to clarify priority levels per suffix.
  • Whenever a suffix is used with an entity that iterates over MRI acquisition parameters (i.e., echo, inv,fa and mt) to create a logical bundle of images to be consumed by a pipeline, intent of the application will be mentioned in a new appendix: Logical grouping conditions for parametrically linked images (open for title suggestions).
    • This Appendix may serve as a gateway linking to the relevant sections of other appendixes or may centralize all the logical grouping cases under different sections.
    • If this concept is to be added to the common principles, the new common principle should refer to the logical grouping conditions for parametrically linked images appendix.
  • The anatomy imaging data section will be simplified by removing the text that becomes redundant following the changes above and by moving relevant explanations under the qMRI Appendix section wherever possible.

Group entities into "within-acquisition" and "between-acquisition

We could not get to discuss this in detail, but there are cases where one entity can fall under either group depending on the suffix/application. For example, inv for mp2rage is within acquisition, whereas inv for IRT1 is between-acquisitions. Same would apply to echo under various conditions. Whereas mt and fa are pretty commonly between-acquisition. These are all the entities that we have at the moment to denote changes in acquisition parameters. If 1-->N entity-->entity_type mapping is not a problem, we can denote them on a per-application basis in the entity table.

We believe that this solution has potential to find the common ground as it does not have major practical consequences for any parts interested in the additions brought by BEP001. Please share your opinions with us, so that we can get the ball rolling. You can start by reacting to this comment:

Icon Means
👍 Sounds good, commit the changes
👀 Not bad, I have some suggestions to improve
👎 Nope, not a good idea at all

@tsalo
Copy link
Member

tsalo commented Jul 30, 2020

To clarify #530, I only used the term "acquisition" because there isn't an established term for grouped collections yet. It would work in conjunction with #529 (and the above), meaning that entities would essentially be split into "sufficient to distinguish grouped scans" and "insufficient to separate groups of scans". Essentially, if the only thing distinguishing two files is one of these within-acquisition entities (e.g., echo or fa), then it should be assumed that they come from the same group. An additional entity like acq or run would be necessary to denote that they're from different groups.

**If the provenance record of the qMRI map generation is available:**

In this case, qMRI maps SHOULD be stored in the `derivatives` folder, but MAY
be symbolic linked to the corresponding raw data directory to facilitate the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are pretty strong arguments against symbolic linking (please see #526). One solution that @effigies proposes is to use the dataset description file to characterize the dataset as derivatives. I don't think there's any room for a distinction based on provenance in this case.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you @tsalo for the pointer, I was following that discussion and planning to bring this up in our next BEP001 meeting. We will soon have another meeting before taking actions to address comments and implement changes I suggested above.

@agahkarakuzu
Copy link
Contributor Author

Hi everyone,

After long discussions with many people involved, we finally have a roadmap to refactor this PR and split it into manageable bits. I think we settled on several important issues such as not introducing a grouping suffix concept that is confined to anatomy imaging data, not using symbolic links, about how to introduce new entities and suffixes, and how to organize quantitative maps. Firstly, thank you so much for your help!

These decisions call for a major revision to this PR, both contextually and structurally. To make development easier, we decided on closing this PR, then sending smaller (revised) BEP001 PRs starting with the common principle of logical grouping of parametrically linked acquisitions, which is to be followed by the introduction of new entities and new anatomy imaging suffixes in line with the new conventions brought by the latest BIDS release.

If maintainers and other people involved in this PR agree (+1s would be a good indicator), I will soon close this PR and start working on a new fork on bids-bep001 organization.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.