Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[MISC] Generalize rules that labels must be used consistently #1328

Open
wants to merge 10 commits into
base: master
Choose a base branch
from
Open

[MISC] Generalize rules that labels must be used consistently #1328

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
0f383a2
add consistency definition
Remi-Gau Oct 17, 2022
f500e59
rm mention of consistency for other labels
Remi-Gau Oct 17, 2022
0b26a61
rm consistent from schema
Remi-Gau Oct 17, 2022
8bea7df
update microscopy sample label paragraph
Remi-Gau Oct 17, 2022
9d30948
Update src/schema/objects/common_principles.yaml
Remi-Gau Oct 18, 2022
e4b4365
Update src/schema/objects/common_principles.yaml
Remi-Gau Oct 18, 2022
a360f38
Merge remote-tracking branch 'upstream/master' into consistency
Remi-Gau Apr 15, 2024
fe5397b
Merge branch 'master' into consistency
Remi-Gau Apr 18, 2024
c8a4844
Update src/schema/objects/common_principles.yaml
Remi-Gau Apr 19, 2024
b165609
Merge branch 'master' into consistency
Remi-Gau Apr 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/modality-specific-files/magnetic-resonance-imaging-data.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -689,7 +689,7 @@ MUST be used to distinguish both images.
In such a case, two files could have the following names:
`sub-01_acq-singleband_dwi.nii.gz` and `sub-01_acq-multiband_dwi.nii.gz`.
The user is free to choose any other label than `singleband` and
`multiband`, as long as they are consistent across subjects and sessions.
`multiband`.

### REQUIRED gradient orientation information

Expand Down
6 changes: 3 additions & 3 deletions src/modality-specific-files/microscopy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,8 @@ Consistent with other data types in BIDS, the session entity is optional.

The [`sample-<label>`](../appendices/entities.md#sample) entity is REQUIRED for
Microscopy data and is used to distinguish between different samples from the same subject.
The label MUST be unique per subject and is RECOMMENDED to be unique throughout the dataset.
Contrary to other labels, the `sample-<label>` MUST be unique per subject
and is RECOMMENDED to be unique throughout the dataset.
Copy link
Collaborator

@yarikoptic yarikoptic Jan 23, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do not see why I am to be disallowed to use sample-1, sample-2 and so on across my subjects if I do not have any other logical description for samples besides some index (label is superset of index AFAIK).
It seems that the intent here to demand some UUIDs, but I do not see really why here and why only for samples.

Moreover, as we ATM have mandatory sub- leading folder anyways, I do not understand really what "unique per subject" means really.


For example: Three brain slices (`sample-01` to `sample-03`) extracted from subject `sub-01`,
imaged by scanning electron microscopy (SEM) in PNG format
Expand Down Expand Up @@ -133,8 +134,7 @@ MAY be used to distinguish a different set of parameters used for acquiring the
For example, two images of the same sample acquired by bright-field microscopy (BF) in PNG format at
different magnification of 40x and 60x.
In such case two files could have the following names: `sub-01_sample-01_acq-40x_BF.png` and
`sub-01_sample-01_acq-60x_BF.png`, however the user is free to choose any other label as long as
they are consistent across subjects and sessions.
`sub-01_sample-01_acq-60x_BF.png`.

The [`stain-<label>`](../appendices/entities.md#stain) entity MAY be used to distinguish
image files from the same sample using different stains or antibodies for contrast enhancement.
Expand Down
3 changes: 0 additions & 3 deletions src/modality-specific-files/positron-emission-tomography.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,6 @@ Volumes MUST be stored in chronological order (the order they were acquired in).

The OPTIONAL [`task-<label>`](../appendices/entities.md#task) is used to
indicate a task subjects were asked to perform in the scanner.
Those labels MUST be consistent across subjects and sessions.
For task based PET, a corresponding [`task events`](./task-events.md) file MUST be provided
(please note that this file is not necessary for resting scans).

Expand All @@ -93,8 +92,6 @@ but REQUIRED to distinguish between tracers if multiple are used.
The label used is arbitrary and each file requires a separate JSON sidecar
with details of the tracer used (see below).
Examples are `trc-18FFDG` for fludeoxyglucose or `trc-11CPIB` for Pittsburgh compound B.
Other labels are permitted, as long as they are consistent across subjects and sessions
and consist only of the legal label characters.

If more than one run of the same task and acquisition (tracer) are acquired during
the same session, the [`run-<index>`](../appendices/entities.md#run) entity MUST be used:
Expand Down
3 changes: 3 additions & 0 deletions src/schema/objects/common_principles.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,9 @@ label:
for example, it is `rest` in `task-rest` following `task-<label>` specification.
Note that labels MUST not collide when casing is ignored
(see [Case collision intolerance](SPEC_ROOT/common-principles.md#case-collision-intolerance)).
Labels MUST be consistent across subjects and sessions and data types.
For example, an `acq` entity label `hires` used on the `anat` data of a given subject
MUST mean the same thing as `acq-hires` in `func` files of any other subject.
Comment on lines +90 to +92
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MUST is IMHO too strong of a word here since we do not even define the meaning of "mean" in this case -- is it EXACTLY the same resolution? the same shimming? clearly it cannot be "the same everything" since then functional must be an anatomical ;) Other example could be _desc for which we provision descriptions.tsv per each subject/session hence allowing for different "meaning"s (e.g. exact filtering parameters) for the same overall descriptor filt.

Hence

Suggested change
Labels MUST be consistent across subjects and sessions and data types.
For example, an `acq` entity label `hires` used on the `anat` data of a given subject
MUST mean the same thing as `acq-hires` in `func` files of any other subject.
Labels SHOULD be consistent across subjects and sessions and data types.
For example, an `acq` entity label `hires` used on the `anat` data of a given subject
SHOULD mean the same thing as `acq-hires` in `func` files of any other subject.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

might be additional factor -- IIRC bids-validator would issue a WARNING whenever "same" (e.g. _task-movie_run_1) files across subjects have different "qualities" (e.g. length), not ERROR. If changed to MUST, it then MUST issue an ERROR rendering some previously valid BIDS datasets invalid, breaking change.

modality:
display_name: Modality
description: |
Expand Down
6 changes: 1 addition & 5 deletions src/schema/objects/entities.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,7 @@ acquisition:
For example, this should be used when a study includes two T1w images -
one full brain low resolution and one restricted field of view but high resolution.
In such case two files could have the following names:
`sub-01_acq-highres_T1w.nii.gz` and `sub-01_acq-lowres_T1w.nii.gz`;
however, the user is free to choose any other label than `highres` and `lowres` as long
as they are consistent across subjects and sessions.
`sub-01_acq-highres_T1w.nii.gz` and `sub-01_acq-lowres_T1w.nii.gz`.

In case different sequences are used to record the same modality
(for example, `RARE` and `FLASH` for T1w)
Expand Down Expand Up @@ -384,8 +382,6 @@ task:
a given task may have different sets of stimuli (for example, randomized order) and participant responses
across subjects, sessions, and runs.

The `task-<label>` MUST be consistent across subjects and sessions.

Files with the `task-<label>` entity SHOULD have an associated
[events file](SPEC_ROOT/modality-specific-files/task-events.md#task-events),
as well as certain metadata fields in the associated JSON file.
Expand Down