[ENH] BEP001 - New entity: flip

[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 addition of several new entities (inv, flip, mt) for the common use cases of quantitative MRI applications. In this Part-3 of BEP001 pull requests, we would like to propose a new entity:

Entity	Corresponding metadata	Purpose
flip*	FlipAngle	To distinguish constituents of a file-collection if the files differ as a function of the FlipAngle acquisition parameter.

* We abstained from using its common abbreviation fa, as it may be confused with the FA (fractional anisotropy) term from dwi realm.

We set the requirement level of this entity to MUST for the applications falling within the definition of entity-linked file collections, not for all the applications that may collect data at multiple FlipAngle values. This is because splitting files may not be the most convenient/preferred approach for some applications, such as ASL #669. I took liberty to adjust the definition of the echo in that respect.

I will be waiting for this PR to be discussed and resolved before sending PRs for the remaining entities inv and mt.

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.

[effigies]

LGTM. Cleaning yaml lint...

Changes made

[agahkarakuzu]

Thank you @effigies! Looks like all the CI requirements are satisfied now.

[tsalo]

I think this revised definition is worded a little confusingly. Rather than "constituents of an entity-linked file collection", I would say "files that are part of an entity-linked file collection". Instead of "differ as a function of EchoTime", I think you could say "have different EchoTimes.

[tsalo]

Also, I think the definition should go before the usage and warning. Something like "The _echo-<index> key/value pair represents the EchoTime metadata field." Then you can go into when and how it should be used.

[agahkarakuzu]

I agree, re-wording this now.

[effigies]

I think rebasing on master should resolve the CI failures.

[sappelhoff]

@agahkarakuzu do you have the "allow edits from maintainers" box in the GitHub user interface ticked? I cannot seem to push to your fork's branch. (wanted to rebase on master)

[agahkarakuzu]

@sappelhoff I don't see that box on the PR page, probably because I am not an owner but a member. I'll try to solve that.

[effigies]

@agahkarakuzu It's a checkbox when you create a new PR:

I don't know that it can be changed after the fact.

[agahkarakuzu]

@effigies it was not available to me while I was creating the PR neither. I can rebase to an upstream master clone branch on our fork, would that work?

[agahkarakuzu]

@effigies I gave it a try, hope that it won't mess it up.

[effigies]

Last semantic change was Monday, so this can be merged this coming Monday if we get another review.

Recommend squashing to keep things clean.

[sappelhoff]

Aaand it's in! Thanks a lot everyone and especially @agahkarakuzu for preparing the PR.

[agahkarakuzu]

Thank you @sappelhoff I will be sending PRs for the remaining entities this week, I think this was a good starting point towards merging bep001!