Modality agnostic files confusion about top-level files

[VisLab]

In reading the spec on modality agnostic files, I am finding the description of the new samples confusing.

The purpose of this file is to describe properties of samples, indicated by the sample entity. This file is REQUIRED if sample- is present in any filename within the dataset. Each sample MUST be described by one and only one row.

This would indicate that samples can go anywhere (because of the label), but the template seems to indicate that it is like participants and at the top level.

Also, it might help to clarify at the beginning of this whole section which files must go at the top level. It is sometimes hard to read between the lines on this.

Also, I am finding confusing that the templates for README, CHANGES, and LICENSE are under dataset description rather than right above their own examples. It might be clearer to separate them.

[sappelhoff]

cc @mariehbourget

[Remi-Gau]

This would indicate that samples can go anywhere (because of the label), but the template seems to indicate that it is like participants and at the top level.

Can you suggest a rewording that would clarify this? I think I see what you mean but I can't quite think of a way to express this.

Also, it might help to clarify at the beginning of this whole section which files must go at the top level. It is sometimes hard to read between the lines on this.

Also, I am finding confusing that the templates for README, CHANGES, and LICENSE are under dataset description rather than right above their own examples. It might be clearer to separate them.

Agreed.

Maybe having a listing of all the files that can only be found at the top level would be good.

[VisLab]

Can you suggest a rewording that would clarify this? I think I see what you mean but I can't quite think of a way to express this.

How about replacing

This file is REQUIRED if sample-<label> is present in any filename within the dataset.

with:

A samples.tsv file is required at the top-level if the sample-<label> entity is present in any filename within the dataset.

---

Also, phenotype isn't listed as a top-level directory in:

https://bids-specification.readthedocs.io/en/stable/02-common-principles.html#other-top-level-directories

---

Could we put a paragraph at the beginning of this file saying what a modality agnostic file is for those of us who aren't sure? Maybe something like (this isn't very good but...):

Modality agnostic files contain information that is not specific to a particular modality, including information about dataset organization and structure as well as participant information.

[Remi-Gau]

Also, phenotype isn't listed as a top-level directory in:

https://bids-specification.readthedocs.io/en/stable/02-common-principles.html#other-top-level-directories

I believe this part at least is now fixed.