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

[tsalo]

Currently, at least within functional MRI, the specification has only one entity that typically distinguishes files from the same acquisition- echo. However, @tiborauer recently noted that this entity can be used for multi-echo fMRI (the standard use) and to separate single-echo acquisitions with different echoes, and the resulting files would have exactly the same names.

Part of the problem is that “run” is defined as “an uninterrupted repetition of data acquisition that has the same acquisition parameters and task”. Thus, it would be incorrect to increment the run entity across acquisitions of the single-echo BOLD scan, since the echo time is changing. This also highlights how “run” and “acquisition” aren’t quite synonyms.

Another part of the problem is that the echo entity doesn’t really have its own definition:

Multi-echo data MUST be split into one file per echo. Each file shares the same name with the exception of the _echo- key/value.

This says how users must label multi-echo data, but not how echo should be used in general. I think we should define echo as “within-acquisition”, so that, if the only thing that varies between files is that entity, those files can be assumed to come from the same acquisition. In cases of single-echo acquisitions with varying echo times, we should clarify that some other entity should distinguish the acquisitions, such as acq or run.

Given that #508 and #425 propose a number of new entities that refer to the same acquisition (or grouped scan collection, depending on how we define things), I think we should discuss the idea of a broader concept of “within-acquisition” and “between-acquisition” entities.

BTW, I know that I repeatedly said “acquisition” throughout this issue, but please see #529 about the idea of “grouped scan collections” and how that’s different from “acquisition”. I think that the within- and between- entities here would apply to those groups instead of specifically being limited to an “acquisition”.

Tagging @agahkarakuzu and @emdupre, with whom I talked about this in a call.

[tsalo]

I think that this rule is implicitly in effect for echo based on how associated files (e.g., events files) are handled. See the Task events page, which says the following:

In case of multi-echo task run, a single _events.tsv file will suffice for all echoes.

and

For multi-echo files, the *_events.tsv file is applicable to all echos of particular run:

sub-01_task-cuedSGT_run-1_events.tsv
sub-01_task-cuedSGT_run-1_echo-1_bold.nii.gz
sub-01_task-cuedSGT_run-1_echo-2_bold.nii.gz
sub-01_task-cuedSGT_run-1_echo-3_bold.nii.gz

This sets up a rule where, for these other filetypes, the "matching" entities for a given scan/acquisition/run/whatever do not include echo. Essentially, all other entities for BOLD data are necessary to distinguish an acquisition to which an events file would apply, but echo is not.

That rule should naturally extend to other, similar entities that will be added in the future (e.g., part or channel/coil), so I think we should make it explicit.

[tsalo]

I think this concept is adequately covered by file collections and "linking entities" (see Appendix X), so I'm going to close this issue.