[FIX] Re-align the text and the schema for filenames in derivatives

[mguaypaq]

I initially set out to add the desc entity to the filename templates for segmentations (in the 'Segmentations' subsection), since the BIDS spec says here that:

When necessary to distinguish two files that do not otherwise have a distinguishing entity, the _desc- entity SHOULD be used.

But then I noticed that this repository also contains a YAML version of the spec, and the desc entity already appears there. What's more, I noticed that the atlas filename entity has the opposite problem: it appears in the text (added in #997), but not in the YAML.

I also noticed that the [ses-<label>/] folder layer was missing from the filename templates in the text about Derivatives (probably because they can't use the nifty MACROS___make_filename_template construct), so I fixed that too.

This pull request fixes all three problems.

I'm not sure if this pull request counts as a [FIX] or a [SCHEMA]: it feels to me like a bugfix, but technically it does touch the YAML files.

(This is my first contribution, but I'll wait until it's accepted before adding myself to the Recent Contributors page on the wiki.)

[codecov]

Codecov Report

Patch and project coverage have no change.

Comparison is base (01be684) 87.83% compared to head (1866012) 87.83%.
Report is 1 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1567   +/-   ##
=======================================
  Coverage   87.83%   87.83%           
=======================================
  Files          16       16           
  Lines        1356     1356           
=======================================
  Hits         1191     1191           
  Misses        165      165           

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

[tsalo]

Thank you for addressing this. I think the one lingering problem is that the set of allowed entities will depend on the extension (i.e., nifti vs. gifti vs. cifti).

I also think we're not far from being able to generate these filename templates with macros (the way we do for the raw BIDS filename templates), but your fixes are much appreciated in the meantime.

[Remi-Gau]

@effigies @tsalo
before @mguaypaq spends too much time on this, do we think it will be possible in the "near" future to use the schema directly to render those filename templates?

Also to estimate how thorough we want to be on this.

[effigies]

I would like to put the brakes on adding atlas- for the time being. This was a very small, last-minute addition to derivatives that seemed harmless at the time, but one result from the June 2023 meeting in Copenhagen was the realization that it is a very narrow definition of atlas. @melanieganz is going to be proposing changing its name to parc- (for "parcellation") in this narrow context to free up atlas- to be used in the sense of BEP38, and that's a discussion that needs to be had out (i.e., is anybody actually using atlas- as it currently is stated, or can we "safely" sweep it under the rug).

I would be pro-converting these to filename templates like the rest. It will need a new macro, since <pipeline_name> and <source_entities> won't be handled by the current one.

I don't know if we want to do something like:

meta.derivatives.masks.vol_mask:
  suffixes:
    - mask
  extensions:
    - .nii
    - .nii.gz
    - .json
  entities:
    space: optional
    resolution: optional
    label: optional
    description: optional

meta.derivatives.masks.surf_mask:
  suffixes:
    - mask
  extensions:
    - .label.gii
    - .json
  entities:
    space: optional
    density: optional
    label: optional
    description: optional

meta.derivatives.masks.volsurf_mask:
  suffixes:
    - mask
  extensions:
    - .dlabel.nii
    - .json
  entities:
    space: optional
    resolution: optional
    density: optional
    label: optional
    description: optional

rules.files.deriv.imaging.func_mask:
  $ref: rules.files.raw.func.func
  suffixes:
    $ref: meta.derivatives.masks.vol_mask.suffixes
  entities:
    $ref: rules.files.raw.func.func.entities
    $ref: meta.derivatives.masks.vol_mask.entities

That would allow us to write the macro to work on meta.derivatives.masks.* instead of on rules.files.deriv.imaging.*_mask, which will be fully expanded by the time we get to the rendering code.

[Remi-Gau]

switching to draft PR

[mguaypaq]

I have addressed all the feedback, so that the text and yaml line up with each other. Could I get another round of reviews?