BEP-038: Atlases #1714

effigies · 2024-02-28T16:23:10Z

This PR proposes the inclusion of BEP-038 into the BIDS specification.

The BEP is hosted on its own branch in the main repository, and BEP leads have been given write permissions to the branch. If you are a BEP lead and having issues writing to the branch, please let a maintainer know and we can make sure you have access.

At present this is a starting point, and I anticipate significant rewriting and reorganization before final merge. There is extensive discussion in #1281 that needs to be turned into concrete proposals. I would suggest keeping the discussion on this PR minimal so that newcomers can follow the thread. When opening PRs against this branch, please include a reference to this PR (#1714) so that it shows up in the thread.

I made a first draft of the atlas BEP based on the Google doc

Added atlas content

All the content of the BEP038 Google document has been ported to the atlas.md file. Additionally atlas and a definition of what of means was added as an entity. There are still smaller things to fix as some links, references and the tables still need to be inserted.

Fixed details such as linking to entities and suffixes as well as clarified some of the example text. The tables need still to be fixed.

[BEP038] Style and similar cleanups

CPernet · 2024-03-31T07:52:57Z

@erdalkaraca @tsalo this has passed the review period now, can this be checked and merged? thx

oesteban · 2024-04-01T19:16:55Z

I'm working on a review. Please hold on.

effigies · 2024-04-01T19:33:15Z

I also have not finished my review/proposed changes. I am unlikely to get to it before the meeting next week as I am traveling for another meeting this week.

effigies · 2024-04-04T19:52:58Z

This BEP currently needs:

Schema implementation of required checks and filename rules
Examples implementing all significant (ideally all) features proposed to https://github.com/bids-standard/bids-examples
Implementation of all rules in https://github.com/bids-standard/bids-validator and tested on the examples.
A two week public review period announced on all communication channels.

I'm converting this to draft to reflect this status. I'm going to temporarily restrict comments, pending synchronous discussion.

…ctor

[BEP038] Schema refactor

tools/schemacode/src/bidsschematools/schema.py

tsalo · 2025-10-30T18:57:06Z

src/derivatives/atlas.md

+         "anat": {
+            "atlas-Diedrichsen2009_description.json": "",
+            "tpl-SUIT_T1w.nii.gz": "",
+            "tpl-SUIT_dseg.json": "",
+            "tpl-SUIT_dseg.label.gii": "",
+            "tpl-SUIT_dseg.nii.gz": "",
+            "tpl-SUIT_dseg.tsv": "",
+            "tpl-SUIT_probseg.nii.gz": "",
+            "tpl-SUIT_flat.surf.gii": "",
+            "tpl-SUIT_sulc.shape.gii": "",


Suggested change

"anat": {

"atlas-Diedrichsen2009_description.json": "",

"tpl-SUIT_T1w.nii.gz": "",

"tpl-SUIT_dseg.json": "",

"tpl-SUIT_dseg.label.gii": "",

"tpl-SUIT_dseg.nii.gz": "",

"tpl-SUIT_dseg.tsv": "",

"tpl-SUIT_probseg.nii.gz": "",

"tpl-SUIT_flat.surf.gii": "",

"tpl-SUIT_sulc.shape.gii": "",

"atlas-Diedrichsen2009_description.json": "",

"anat": {

"tpl-SUIT_T1w.nii.gz": "",

"tpl-SUIT_atlas-Diedrichsen2009_dseg.json": "",

"tpl-SUIT_atlas-Diedrichsen2009_dseg.label.gii": "",

"tpl-SUIT_atlas-Diedrichsen2009_dseg.nii.gz": "",

"tpl-SUIT_atlas-Diedrichsen2009_dseg.tsv": "",

"tpl-SUIT_atlas-Diedrichsen2009_probseg.nii.gz": "",

"tpl-SUIT_flat.surf.gii": "",

"tpl-SUIT_sulc.shape.gii": "",

tsalo · 2025-10-30T18:58:38Z

src/derivatives/atlas.md

+            "tpl-SUIT_atlas-Buckner2011_seg-17n_dseg.label.gii": "",
+            "tpl-SUIT_atlas-Buckner2011_seg-17n_dseg.nii.gz": "",
+            "tpl-SUIT_atlas-Buckner2011_seg-17n_dseg.tsv": "",
+            "tpl-SUIT_atlas-Buckner2011_seg-17n_stat-confidence_probseg.nii.gz": "",


The stat-<label> entity is used throughout but isn't defined in the schema.

tsalo · 2025-10-30T18:59:07Z

src/derivatives/atlas.md

+         "anat": {
+            "atlas-Buckner2011_description.json": "",
+            "atlas-Diedrichsen2009_description.json": "",


Suggested change

"anat": {

"atlas-Buckner2011_description.json": "",

"atlas-Diedrichsen2009_description.json": "",

"atlas-Buckner2011_description.json": "",

"atlas-Diedrichsen2009_description.json": "",

"anat": {

Actually the location of the atlas description file isn't consistent throughout the BEP, and the entities in use mean that the inheritance principle doesn't apply AFAICT.

tsalo · 2025-10-30T19:00:43Z

src/derivatives/atlas.md

+        atlas-<label>_description.json
+        [cohort-<label>/]
+           [<datatype>/]
+               tpl-<label>_[cohort-<label>][_space-<label>][_atlas-<label>][seg-<label>][_scale-<label>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>


Suggested change

tpl-<label>_[cohort-<label>][_space-<label>][_atlas-<label>][seg-<label>][_scale-<label>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>

tpl-<label>[_cohort-<label>][_space-<label>][_atlas-<label>][_seg-<label>][_scale-<label>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>

tsalo · 2025-10-30T19:01:22Z

src/derivatives/atlas.md

+    tpl-<label>/
+        [cohort-<label>/]
+           [<datatype>/]
+               tpl-<label>_[cohort-<label>][_space-<label>][_atlas-<label>][seg-<label>][_scale-<label>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>


Suggested change

tpl-<label>_[cohort-<label>][_space-<label>][_atlas-<label>][seg-<label>][_scale-<label>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>

tpl-<label>[_cohort-<label>][_space-<label>][_atlas-<label>][_seg-<label>][_scale-<label>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>

tsalo · 2025-10-31T14:43:05Z

src/schema/meta/templates.yaml

      segmentation: optional
+      scale: optional

  probseg:


Shouldn't tsv be an allowed extension for probsegs?

tsalo · 2025-10-31T14:55:33Z

src/schema/rules/files/deriv/imaging.yaml

+  $ref: rules.files.deriv.imaging.anat_discrete_surface
+  entities:
+    $ref:
+      - meta.templates.deriv.volumetric.entities


Suggested change

- meta.templates.deriv.volumetric.entities

- meta.templates.atlas.base.entities

The current entities rules don't allow template.

melanieganz and others added 17 commits January 23, 2024 09:23

First draft of the atlas spec

9878702

I made a first draft of the atlas BEP based on the Google doc

Added proper content

8304769

Added atlas content

Fixed details

81d5ccc

Fixed details such as linking to entities and suffixes as well as clarified some of the example text. The tables need still to be fixed.

case 3 files renamed

7626992

update wording and fix typos in atlas.md

11ed800

add draft for outlining desc- usage

1129d8d

add ref to template and lnter

6881c9c

Remove trailing whitespace, normalize indentation to two spaces

e2b3ddb

Run codespell and aspell

f7a268d

Replace i.e. and e.g.

a96ab79

Line break at sentences, format nested list as markdown

18e2bcc

Replace unicode quotes with ASCII

803f0d4

Include atlas.md in table of contents

dda4790

Semantic line breaks, mostly at commas

ba30c0e

FIX: Whitespace in schema.objects.entities.atlas.description

9c803d7

Merge pull request #1 from effigies/bep038

33e55b5

[BEP038] Style and similar cleanups

effigies added the BEP label Feb 28, 2024

effigies requested review from erdalkaraca and tsalo as code owners February 28, 2024 16:23

Merge branch 'master' into bep038

9baaeec

melanieganz mentioned this pull request Mar 5, 2024

BEP Proposal: Atlas specification #1281

Open

effigies marked this pull request as draft April 4, 2024 19:53

bids-standard locked as too heated and limited conversation to collaborators Apr 4, 2024

christinerogers marked this pull request as ready for review April 5, 2024 17:02

sappelhoff marked this pull request as draft April 5, 2024 17:12

effigies added 7 commits June 20, 2025 07:04

feat(schema): Expand use of raw templates

64d16fe

rf: Dereference while looking up references

723c265

Merge branch 'multiref' into bep038

c8cc8af

rf(schema): Move atlas definitions into derivatives

a017a1e

Add description suffix

9a8dd63

Merge remote-tracking branch 'upstream/master' into bep038

2bb65c1

Merge remote-tracking branch 'upstream/bep038' into bep38-schema-refa…

3ba6693

…ctor

effigies mentioned this pull request Jun 20, 2025

[BEP038] Schema refactor #2145

Merged

effigies added 2 commits June 20, 2025 14:45

Merge pull request #2145 from effigies/bep38-schema-refactor

e5e0c07

[BEP038] Schema refactor

Apply suggestions from code review

aa50928

effigies commented Jun 20, 2025

View reviewed changes

tools/schemacode/src/bidsschematools/schema.py Outdated Show resolved Hide resolved

effigies added 3 commits June 20, 2025 14:51

Update tools/schemacode/src/bidsschematools/schema.py

f830888

Apply suggestions from code review

7af68de

Merge remote-tracking branch 'upstream/master' into bep038

f6b62f5

effigies added this to the 1.11.0 milestone Aug 27, 2025

kabilar mentioned this pull request Aug 27, 2025

Naming of population-level derivatives lincbrain/linc-docs#50

Open

PolarBean mentioned this pull request Oct 1, 2025

[Feature] Consider contributing to the BIDS atlas pull request to ensure compatibility with brainglobe brainglobe/brainglobe-atlasapi#650

Open

effigies added 3 commits October 30, 2025 14:01

Merge commit 'dd1e5d23' into bep038

2afe0b0

Merge commit '6d002b21' into bep038

6ff150d

Merge remote-tracking branch 'upstream/master' into bep038

4262905

tsalo reviewed Oct 30, 2025

View reviewed changes

effigies added 3 commits October 30, 2025 16:17

fix: Drop cohort from non-atlas derivatives

84bd2e5

fix: Move atlas description to the top of the dataset

0c6e99c

schema: Add atlas description association

b2ffc8e

tsalo reviewed Oct 31, 2025

View reviewed changes

src/schema/meta/templates.yaml

segmentation: optional

scale: optional

probseg:

Copy link

Member

tsalo Oct 31, 2025

Choose a reason for hiding this comment

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

Shouldn't tsv be an allowed extension for probsegs?

tsalo reviewed Oct 31, 2025

View reviewed changes

	tpl-<label>_[cohort-<label>][_space-<label>][_atlas-<label>][seg-<label>][_scale-<label>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>
	tpl-<label>[_cohort-<label>][_space-<label>][_atlas-<label>][_seg-<label>][_scale-<label>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>

	- meta.templates.deriv.volumetric.entities
	- meta.templates.atlas.base.entities

BEP-038: Atlases #1714

Are you sure you want to change the base?

BEP-038: Atlases #1714

Uh oh!

Conversation

effigies commented Feb 28, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Rendered draft

Related discussions

Associated PRs

Uh oh!

CPernet commented Mar 31, 2024

Uh oh!

oesteban commented Apr 1, 2024

Uh oh!

effigies commented Apr 1, 2024

Uh oh!

effigies commented Apr 4, 2024

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

11 participants

effigies commented Feb 28, 2024 •

edited

Loading