[ENH] BEP001 - RepetitionTimeExcitation and RepetitionTimePreparation

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

The current definition of the RepetitionTime field was subject to a long discussion, because:

1. The definition of the term is specific to the task imaging data; therefore, not applicable for other MRI modalities that are not designed to collect volumetric data within a single TR.
2. If made to the current RepetitionTime field, the change required by (1) would break retro-compatibility for the main user-base of the BIDS.

To have best of both worlds, we came up with a solution by introducing 2 more metadata fields: RepetitionTimeExcitation and RepetitionTimePreparation. These definitions i) do not interfere with the current definition of the RepetitionTime, retaining compatibility with massive amount of fMRI data and ii) cover the basis for simple (e.g. T1w) or more complex MRI acquisitions (e.g. MP2RAGE) with proper definitions.

In this Part-2 of BEP001 pull requests, we propose including these metadata fields to enable new anatomy imaging applications without affecting the existing datasets. In a recent meeting, we also realized that these definitions can be useful for the BEP005 team, hence pinging #669.

Big thanks to @KirstieJane for carefully adjusting the wording in these suggested changes and to @mathieuboudreau for his help with the terms.

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]

I understand why this proposal is necessary for BIDS 1.X, but, to clarify, would this change be adequately superseded in BIDS 2.0 by the proposal in bids-standard/bids-2-devel#18? I think it's important that we have a corresponding proposal for a cleaner, backwards-incompatible definition of RepetitionTime that works for all groups for 2.0, even if 2.0 won't be released any time soon.

[agahkarakuzu]

@tsalo when backwards compatibility is no longer an issue, replacing RepetitionTime definition with that of RepetitionTimeExcitation (with minor edits to generalize) and declaring RepetitionTimeExcitation as deprecated would solve it.

On the other hand, RepetitionTimePreparation would still be needed. It would only require it to be used together with RepetitionTime instead of RepetitionTimeExcitation.

[tsalo]

Thank you for the clarification. Assuming this is merged with minimal changes, we should make sure that plan is reflected in the bids-2-devel issue.

[effigies]

LGTM, just reformatting to specify the requirement level and data type in separate columns. We're also going to need to update the table fences in both tables to satisfy the linter.

[Remi-Gau]

Makes sense to me.

[patsycle]

Nice addition! I noticed that only a 'number' is allowed, why not an array of numbers? For example, that would be prefered for BEP005 (asl), but I assume this might be the case for other extensions?

[agahkarakuzu]

@patsycle so far we discussed about the metadata fields that will have an associated entity such as flip and echo. Array option will be inserted somewhere in BEP001 PRs, where exactly that information is going to be inserted is also a question for BIDS maintainers.

Should it be under Data Type column in the table, given as number OR array of numbers ?

Wherever that information is going to be, it should be clear that it is a convenience for ASL data, not a generic approach. Because generic approach should call for minimal or no modification to the core definitions/types, I think. Therefore file collections would be the first venue for future applications to look for when adding an application that depends on collecting data with multiple parameters. This was another reason why BEP001 was designed more like a decorator rather than modifying common parameters/types to achieve desired outputs.

[patsycle]

@agahkarakuzu Indeed, I guess this is under DataType as this is already the case for SliceTiming and VolumeTiming. We will take a look at it already and we can further discuss on Friday.

[Gilles86]

@patsycle, I would like to stress that both SliceTiming and VolumeTiming contain arrays that pertain to parameters that necessarily have to be arrays. By definition, they cannot be a single number. This is very different for the RepetitionTime-fields, as well as all almost other fields in this table. By default, they are defined over all Volumes/Slices. This default easily reaches the 80/20-rule.

I would like to warn against now generalizing all number-fields in this table to array of numbers or even number OR array of numbers, just to accommodate ASL acquisitions. If we choose that road, what do we do with the SliceTiming? Do we put array of numbers OR array of array of numbers there, just in case the timing of the slices changes from volume to volume?

And what about the validator? Does it now have to check every single field in the json-sidecar against the number of volumes in the nifti-file?

We already have a mechanism for iterations over parameters with the echo-<echo>, flip-<flip angle>, etc key-value pairs. By making things so flexible as number OR array-of-numbers, we introduce a lot of ambiguity into the standard and this is exactly what we want to avoid.

I appreciate that the ASL-community would like to stick to their standard practice and put volumes with different acquisition parameters in the same 4D nifti-file and I think we should try to accommodate this within BIDS, to aid broad adoption. However, I don't think practices in ASL should dictate practices in the rest of the field of (q)MRI. Especially not if we just spend 3+ years working out that such a practice leads to problematic edge cases in multiple domains (e.g., when you iterate over more than one parameter like in MPM or MP2RAGE-ME) and hardens the life of BIDS-app developers (if there are multiple ways to store a MP2RAGE in BIDS-format, most of your development time is gonna be invested in very bug-sensitive bookkeeping code).

Can't we make special cases for the fields where this is absolutely necessary for ASL in the table you put under *_asl.json file in your pull request?

[effigies]

Created bids-bep001#5 to suggest language for variable RTE/RTP. There was discussion about whether this would be enough to make it clear that qMRI sequences ought to parameterize their volumes by filename rather than metadata, so I would appreciate suggestions for additional language.

[patsycle]

@agahkarakuzu @effigies Probably stupid question, but what are the next steps for this? I guess Agah has to move the suggestions from bids-bep001#5 to here. And after that? Will this one be merged at the same time as BEP005 or will it first go into BEP005?

[effigies]

@patsycle I would suggest merging this into master, not into BEP-005, when it's ready. But BEP-005 should proceed as if this is merged, to avoid having to wait on it. (If it's useful to merge into BEP-005 so that the document can be read as a whole, that's fine, too.)

[agahkarakuzu]

@patsycle I will move my commits from bids-bep005 pull request to here soon. But I think the changes you can make to the FlipAngle and EchoTime on BEP005 are independent from these changes time- and practice-wise. We are aiming that when both #671 and #652 are merged, there is a coherent language/convention.

[patsycle]

@effigies @agahkarakuzu Good, thanks for the information. Agah, I added your suggestions for FlipAngle and EchoTime in BEP005.

[agahkarakuzu]

Thank you @patsycle! Happy that now we have archetype definitions in the main text to clarify when and which convention applies.

[effigies]

A couple very quick thoughts and a question. I'll look again more thoroughly ASAP.

[effigies]

Since only RTP needs to have an array, I think this looks good as-is. Please consider the rewording suggestions for "interval", but otherwise I think this is very clear.

[sappelhoff]

The link check failure is due to the as of yet missing ASL link: [ASL](#arterial-spin-labeling-perfusion-data)

I'd be fine merging this, given that we are planning to merge ASL very soon and that apart from qMRI and ASL, not many other PRs are expected to be worked on these days.