bids-specification
bids-specification copied to clipboard
mention that session level folder can be dropped from derivatives if not relevant
The spec for derivatives mentions:
https://bids-specification.readthedocs.io/en/latest/derivatives/introduction.html#file-naming-conventions
When the derivatives chain involves outputs derived from a single raw input,
source_entities MUST be the entire source filename,
with the omission of the source suffix and extension.
One exception to this rule is filename entities that are no longer relevant.
As far as I understand this has been interpreted in fmriprep (and maybe other tools) to mean that the session entity and folder can be dropped when one file results from an operation done on several files from several sessions in the source data.
For example (see below), T1w image that would be the mean of T1w images from the 2 sessions. But it also lead to having datatype folder that are are the same level as session folders: something technically valid in BIDS but fairly rare in raw dataset that it may surprise BIDS users when they encounter it.
├── derivatives
│ └── sub-01
│ ├── anat
│ │ └── sub-01_T1w.nii
│ ├── ses-01
│ └── ses-02
└── sub-01
├── ses-01
│ └── anat
│ └── sub-01_ses-01_T1w.nii
└── ses-02
└── anat
└── sub-01_ses-02_T1w.nii
I am wondering if examples should be added to the derivatives section to illustrate this.
pinging @effigies and @oesteban who may know better than me on this.
@Remi-Gau I think you are right, that's the interpretation of fMRIPrep and I also agree on that "weirdness" in the sense that what happens when the participant (subject, sub-) is no longer applicable?
We have touched laterally on this when discussing group-level results and it looks like in the end BIDS Derivatives will have some sort of group entity to aggregate subjects (this is related to templates/atlases btw, but let's leave it aside for a moment).
So, if for subjects we may have say grp-control
where subjects X, Y, Z were assigned and spatially normalized, why we don't have a similar concept for aggregation of sessions?
Something like a study- entity (or better, session group, sesgrp-?) or a special value for the session entity to indicate that it aggregates sessions (less interesting as a solution, IMHO)
I think BIDS Derivatives really needs to open the can of worms with higher-than-first-level derivatives (e.g. the T1w template you gave for example).
Acutally I also realized that given the current state of the spec, it would be actually hard to give a "concrete" example like the one above for this entity/folder dropping, because we don't have yet an official way to describe mean anat images.
The problem is two-fold:
- The few things we have in derivatives only apply to (basic) first-level analysis/processes.
- Those few first-level analyses/processes we cover are missing many components (e.g., mean anat images, although I would argue on that particular one because in fMRIPrep we just call it
<matches>_T1w
and it works very intuitively IMHO)