Replace terms "modality_label" and "contrast_label" with "suffix"

[tsalo]

Within the MRI section, two terms are used to indicate suffixes, which I think confuses the issue.

In the "Anatomy imaging data" section, the term modality_label is used twice. First in the filename template and again in the table.

In the "Task (including resting state) imaging data" section, the term contrast_label is used twice. First in the table and again in the filename template.

These terms seem to just be one-offs, in that they're limited to their respective sections and not used regularly. Instead, within the common principles, the term suffix is used. I think we should simply replace these terms with suffix. At minimum, we should probably replace the term "modality" with something else, given that "modality" already has a definition in the specification that is much broader than the way it is used here.

There is a proposal in #508 that partially addresses this (see https://github.com/bids-standard/bids-specification/pull/508/files#r445625768 for the relevant lines), but it only deals with modality_label. Plus, as far as I can tell, even before 1.4.0, modality_label was just used in the same two spots and was never actually defined.

[effigies]

Agreed.

[tsalo]

After reading a bit more, it seems like modality is never defined, but is used in three ways- (1) the imaging system (e.g., MRI, EEG), (2) the specific data content (e.g., BOLD, T1w), which is synonymous with the suffix, and (3) the mod entity, which relates to the data content, but is called modality in pybids.

I think the cleanest solution is to treat modality as the data content (i.e., synonymous with suffix), with the explicit clarification that suffix is the specification's term of choice for this concept. Basically, we drop (1), acknowledge (2), and enforce (3).

In my opinion, this means renaming the folders "Modality agnostic files" and "Modality specific files" to something without the word "modality". What about "technology"?

Additionally, the term modality would be reviewed throughout the spec and replaced with suffix whenever appropriate, and we would also add a common principle for modality that specifically says that it is... operationalized, I guess, as suffix.

EDIT: Alternatively, we could edit the definition of suffix in common principles to clarify that suffix refers to the modality.

[yarikoptic]

In my opinion, this means renaming the folders "Modality agnostic files" and "Modality specific files" to something without the word "modality". What about "technology"?

+1 on that

What about "Data type" instead of "Modality" as we already have them under schema/datatypes and schema/auxdatatypes?
Or even just into "Common files" and "Data types" sections?

[tsalo]

Data types refer to divisions at the folder level though (e.g., func, anat). Outside of MRI, the data types and modalities are the same, I think (e.g., for the technology EEG there is only one data type- eeg), but in order to adopt it across the specification we'd have to split MRI into separate, data type-specific files. And then there'd be no inherent connection between data types of the same technology.

[yarikoptic]

IMHO it is only the "data type" (see prev comment) notion vs "modality" which is the main conflict here. And they kinda could be flipped back and forth and it would still make sense.

Note: we do have _eeg and _ieeg suffixes, and I think it is ok for some "suffixes" (AKA "modalities") to have 1-to-1 correspondence to "data types".

EDIT: Alternatively, we could edit the definition of suffix in common principles to clarify that suffix refers to the modality.

while phrasing description of "suffix" in common principles I et al (in #152) tried to stay away from any specific semantic (such as modality) since IIRC some would not fit nicely "into" its semantic IMHO, e.g. _events, _electrodes, _phase1 etc...

Having said that I indeed most often saw _suffix as indicator of a "modality" and text in e.g. 04-modality-specific-files/01-magnetic-resonance-imaging-data.md indeed uses word "modality" to refer to those suffixes, not the conceptual data types (anat, dwi, ...) and indeed

we have one off `_mod-` (only for `_defacemask`) to "absorb" `modality_label` but it is about "modality" since suffix in those files is `modality_label`

$> git grep '_mod' 
04-modality-specific-files/01-magnetic-resonance-imaging-data.md:        sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_mod-<label>]_defacemask.nii[.gz]
04-modality-specific-files/01-magnetic-resonance-imaging-data.md:For example, `sub-01_mod-T1w_defacemask.nii.gz`.
schema/entities.yaml:    E.g., sub-01_mod-T1w_defacemask.nii.gz.

I think modality_label and contrast_label are "subclasses" of a more generic generic suffix. We could try to add to our terms some definitions of "modality" and "contrast" but they feel data type specific, so most likely would be hard to provide a generic definition?

[yarikoptic]

Data types refer to divisions at the folder level though (e.g., func, anat).

YES, and it another side-effect of original accent on MRI that multiple data types for MRI (anat, func) got their own folder without reflection of being "mri" specific. We do have eeg and ieeg which are also "functional". But overall I think those folders have clear correspondence to the sections + subsections of the mri section ;-)

[tsalo]

IMHO it is only the "data type" (see prev comment) notion vs "modality" which is the main conflict here. And they kinda could be flipped back and forth and it would still make sense.

I agree that we need better definitions to distinguish these two concepts. I can open a separate issue about this in the near future. Since "data type" is defined under Common Principles, it seems reasonable to define "modality" there as well. I would even be comfortable just updating the "suffix" definition to say something like "Suffixes generally refer to data modalities."

I also still think it would be a good idea to have some kind of definition of "technology", although that can be folded into the planned issue.

Note: we do have _eeg and _ieeg suffixes, and I think it is ok for some "suffixes" (AKA "modalities") to have 1-to-1 correspondence to "data types".

I agree. I don't see any problem with one-to-one relationships between the different types, although I still don't want to conflate suffixes with technologies by using unclear terminology.

I think modality_label and contrast_label are "subclasses" of a more generic generic suffix. We could try to add to our terms some definitions of "modality" and "contrast" but they feel data type specific, so most likely would be hard to provide a generic definition?

I am comfortable with the idea of the suffix entity having subclasses, but I have a few problems with how that concept is currently implemented.

1. This is not defined in Common Principles (or, indeed, anywhere). If suffix separates cleanly into specific subclasses, then we should state that in the entity definition and list those subclasses. It would also be nice to give each subclass a definition, but I'd be happy with just having clear rules about where and how they're used for now.
2. Each term is only used twice, and BEP001 is planning to drop one of the terms. These terms are not in broad use, so seeing them pop up in these two sections is confusing.
3. Although they may be valid subclasses, I'm not sure what we get from referring to the suffixes as "modality_label" or "contrast_label" in the cases where they're used. The only benefit I see is in the filename templates, where it makes it somewhat clearer that only the suffixes in the table can be used as suffixes in the filenames.
   • That said, referring to some suffixes as one kind of subclass vs. another is going to be pretty hard in the schema, unless they're defined from the top.
   • BEP001 is just replacing the term "modality_label" with "suffix", both in the table and the filename template. I think the new format is still pretty interpretable.

[tsalo]

It looks like we've handled this one over the last couple of years, so I'm going to close it. Further discussion about the modality terminology can go in #593.