[ENH] Add human statement to emphasize that _desc is the last entity

[yarikoptic]

Partially addresses #1895

attn @arokem

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.71%. Comparing base (4411fde) to head (4442a48).
⚠️ Report is 75 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1915   +/-   ##
=======================================
  Coverage   82.71%   82.71%           
=======================================
  Files          20       20           
  Lines        1608     1608           
=======================================
  Hits         1330     1330           
  Misses        278      278           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[arokem]

Thanks! I don't think this quite covers the issue raised in #1895 though, because this points to a specific example, without stating explicitly that this is the convention for other cases as well. Does that make sense?

[yarikoptic]

Good observation @arokem ! our problem is that we do not really introduce _desc anywhere before. For now I just adjusted original description that it doesn't really close that issue, but I think for this could be a quick enhancement.

[effigies]

I realized the other day that I now wish that we had put hemi- last. e.g., this would be preferable:

sub-01_desc-custom_hemi-L_white.surf.gii
sub-01_desc-custom_hemi-R_white.surf.gii
sub-01_desc-freesurfer_hemi-L_white.surf.gii
sub-01_desc-freesurfer_hemi-R_white.surf.gii

to

sub-01_hemi-L_desc-custom_white.surf.gii
sub-01_hemi-L_desc-freesurfer_white.surf.gii
sub-01_hemi-R_desc-custom_white.surf.gii
sub-01_hemi-R_desc-freesurfer_white.surf.gii

It seems to me that desc- is not a grouping entity, like echo- or part- (or hemi-) and generally we probably want grouping entities toward the back and distinguishing entities toward the front.

So if we have something like components and a mixing matrix that are distinguished by entity, we might prefer:

sub-01_task-rest_desc-ICA_<key>-components_<suffix>.<ext>
sub-01_task-rest_desc-ICA_<key>-mixing_<suffix>.<ext>

This is not grounded in a particular BEP, but just a thing to consider before we codify this.

[yarikoptic]

I think your motivation @effigies relates to fresh

• Introducing chaining rule for derivatives #1949

as a more generic rule of entities composition.

generally we probably want grouping entities toward the back and distinguishing entities toward the front.

well, sub- is a very groupping entity ;) overall it all depends on the case and there might be no universally best order. May be could be in part or fully addressed as part of the

• Make it possible to specify folders layout to be other than sub-{label}/[ses-{label}/] bids-2-devel#54
• (some drafty beginning of work on it): https://github.com/bids-standard/bids-specification/pull/1809/files#diff-efe09d8f5bbcea3e5772ac9f06f13e149454fbdfc00b1aa286a25aac7c2d7303R185

as that one already would require change of the order of entities in the folders/filenames. Hence could as well be extended to the customization of entities to fit "the best" order.

[effigies]

To be clear, by "grouping entity", I mean one that can be varied without changing the overall meaning of the files. Different parts or echos indicate multiple files that should be considered together. Different tasks or subs need separate consideration.

[effigies]

Dismissing my review request, as I don't think this should be in the spec, and I don't have a suggestion to make that would get me to approve this. I won't block, however, so others are welcome to review.

IMO this should be part of contribution guidelines.

[yarikoptic]

I will place "groupping" aspect aside for now, and that our order of entities is not necessarily "groupping friendly" if we think about _part (IMHO _echo is a different story). It is just a matter of spec ATM that desc is the last entity.

To be true to myself and to my hate of duplication, here indeed we are doing exactly that -- duplicating machine-readable schema in English. But, at large, the entire text for bids-specification is just that -- human explanation of what we are encoding in the schema and we cannot always test that it corresponds. But true to other comments, we might need/want to complement this in "contribution guidelines" . But "contribution guidelines" are themselves decoupled from the schema! And we already collected some number of NOTES and WARNINGS in the schema, so I will enhance this PR with changes to schema as well to NOTE that it should stay the last. Anyone preparing a BEP will be doomed to note that whenever adding a new entity.

[neuromechanist]

In terms of derivative ExG data that I have worked on, this pretty much makes sense.