Skip to content

Add BEP038-compliant atlas examples of commonly used publicly available atlases#518

Merged
effigies merged 9 commits intobids-standard:bep038from
PeerHerholz:add-atlas-examples-peer
Nov 4, 2025
Merged

Add BEP038-compliant atlas examples of commonly used publicly available atlases#518
effigies merged 9 commits intobids-standard:bep038from
PeerHerholz:add-atlas-examples-peer

Conversation

@PeerHerholz
Copy link
Copy Markdown
Member

@PeerHerholz PeerHerholz commented Oct 31, 2025

Add seven atlas examples following BEP038 specification:

  • atlas-AAL
  • atlas-Destrieux
  • atlas-DiFuMo (two different scales)
  • atlas-HarvardOxford (probseg and dseg)
  • atlas-Juelich (probseg and dseg)
  • atlas-Schaefer (two different scales)
  • atlas-Talairach

These examples demonstrate various atlas structures and can be used for testing and validation of BEP038 implementations. However, they are most likely not fully compliant yet as some of the metadata might be missing/inaccurate and some files might have to be re-arranged.

@PeerHerholz
Add BEP038-compliant atlas examples
6b43dab 
Add seven atlas examples following BEP038 specification:

- atlas-AAL
- atlas-Destrieux
- atlas-DiFuMo (two different scales)
- atlas-HarvardOxford (probseg and dseg)
- atlas-Juelich (probseg and dseg)
- atlas-Schaefer (two different scales)
- atlas-Talairach

These examples demonstrate various atlas structures and can be used
for testing and validation of BEP038 implementations. However, they are most likely not fully compliant yet as some of the metadata might be missing/inaccurate and some files might have to be re-arranged.
@PeerHerholz PeerHerholz requested review from effigies and tsalo October 31, 2025 16:07
@PeerHerholz PeerHerholz self-assigned this Oct 31, 2025
tsalo
tsalo requested changes Oct 31, 2025
View reviewed changes
Copy link
Copy Markdown
Member

@tsalo tsalo left a comment

Choose a reason for hiding this comment

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

I have a few initial comments, but I think it'll be easier to review this once a couple of issues with the schema are fixed in the BEP's BIDS spec PR.

atlas-Destrieux/atlas-Destrieux_description.json
Copy link
Copy Markdown
Member

@tsalo tsalo Oct 31, 2025

Choose a reason for hiding this comment

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

I think you need SampleSize.

@PeerHerholz
Copy link
Copy Markdown
Member Author

PeerHerholz commented Oct 31, 2025

Hey @tsalo,

thanks for the quick feedback and sorry for the problems! Those are indeed errors in the toolbox I use to create the examples. I can update this and address the outlined issues as soon as you say so.

@PeerHerholz
Copy link
Copy Markdown
Member Author

PeerHerholz commented Oct 31, 2025

Hey again,

I think I addressed all issues, adapted the code and regenerated all examples. I can push them whenever the work on the schema is ready.

@tsalo
Copy link
Copy Markdown
Member

tsalo commented Oct 31, 2025

I don't know when @effigies will have time to make changes to the PR on the specification repo, so I recommend pushing your changes now.

@PeerHerholz
update examples and add new ones
dada75b 
This commit updates the existing examples based on the reviews and adds a few new ones to outline different options.
@PeerHerholz
Copy link
Copy Markdown
Member Author

PeerHerholz commented Oct 31, 2025

Hey @tsalo,

thanks for the information, I just pushed the changes.

@tsalo
Copy link
Copy Markdown
Member

tsalo commented Oct 31, 2025

The validation errors in https://github.com/bids-standard/bids-examples/actions/runs/18981357741/job/54214463305?pr=518 are helpful and most will need to be addressed. You'll still get errors on any probseg.tsv files for now, but I think most of the rest are valid errors.

@PeerHerholz
update atlas examples to fix validation errors
6125ea4 
This commit aims at addressing the validation errors occurred for the last version of the examples. This refers to:

- samplesize is required
- funding needs to be list
- resolution missing from json
- tpl skullstripped or not
- naming pattern re seg and scale
@PeerHerholz
Copy link
Copy Markdown
Member Author

PeerHerholz commented Nov 3, 2025

Hey @tsalo,

thanks for the pointer. I updated the code to hopefully address all validation errors (or at least most of them). This includes:

  • samplesize is required
  • funding needs to be list
  • resolution missing from json
  • tpl skullstripped or not
  • naming pattern re seg and scale

For some of the atlases some of the metadata information is off/wrong as I wasn't sure/couldn't find it. I'll dig deeper into that in the next couple of days, as I wanted to focus on the validation first.

@PeerHerholz
add SampleSize to HO, Juelich, Talairach
b5b8e38 
The previous versions of Harvard Oxford, Juelich and Talairach missed the SampleSize field.
@PeerHerholz
Copy link
Copy Markdown
Member Author

PeerHerholz commented Nov 4, 2025

Hey everyone,

after the last round of edits, this is the status:

Datasets failed validation: atlas-4S/ atlas-HOSPA/ atlas-HarvardOxford/ atlas-Juelich/ atlas-ONPNeuroMarkflorbetapir/ atlas-ONP_florbetapir_atlas/ atlas-Schaefer/ atlas-suit/ eeg_ds003645s_hed_demo/ eeg_ds003645s_hed_library/ eeg_rishikesh/ fnirs_automaticity/ genetics_ukbb/ mrs_fmrs/ pet002/ xeeg_hed_score/

Focusing on the examples I worked on, I get the following errors:

  • Harvard-Oxford

[ERROR] ALL_FILENAME_RULES_HAVE_ISSUES Multiple filename rules were found as potential matches. All of them had at least one issue during filename validation. /tpl-MNI152NLin6Asym/anat/tpl-MNI152NLin6Asym_atlas-HarvardOxford_res-2_probseg.tsv - Rules that matched with issues: rules.files.deriv.imaging.anat_probabilistic_segmentation, rules.files.deriv.imaging.anat_probabilistic_segmentation_atlas

  • Juelich

[ERROR] ALL_FILENAME_RULES_HAVE_ISSUES Multiple filename rules were found as potential matches. All of them had at least one issue during filename validation. /tpl-MNI152NLin6Asym/anat/tpl-MNI152NLin6Asym_atlas-Juelich_res-2_probseg.tsv - Rules that matched with issues: rules.files.deriv.imaging.anat_probabilistic_segmentation, rules.files.deriv.imaging.anat_probabilistic_segmentation_atlas

  • Schaefer

[ERROR] ALL_FILENAME_RULES_HAVE_ISSUES Multiple filename rules were found as potential matches. All of them had at least one issue during filename validation. /tpl-MNI152NLin6Asym/anat/tpl-MNI152NLin6Asym_atlas-Schaefer2018_seg-17Networks_scale-400_res-2_probseg.tsv - Rules that matched with issues: rules.files.deriv.imaging.anat_probabilistic_segmentation, rules.files.deriv.imaging.anat_probabilistic_segmentation_atlas /tpl-MNI152NLin6Asym/anat/tpl-MNI152NLin6Asym_atlas-Schaefer2018_seg-7Networks_scale-200_res-2_probseg.tsv - Rules that matched with issues: rules.files.deriv.imaging.anat_probabilistic_segmentation, rules.files.deriv.imaging.anat_probabilistic_segmentation_atlas

[ERROR] SIDECAR_WITHOUT_DATAFILE A json sidecar file was found without a corresponding data file /atlas-Schaefer_description.json

I'm not so sure how to deal with the ALL_FILENAME_RULES_HAVE_ISSUES problem. I'm very sorry if I missed something obvious.

@tsalo
Copy link
Copy Markdown
Member

tsalo commented Nov 4, 2025 •
edited
Loading

@PeerHerholz most of the remaining validator errors stem from the probseg.tsv files. These aren't supported in BIDS and the LabelMap field in the probseg.json should be used to label the regions instead. I had the same issue in my example HOSPA atlas, which I fixed just a bit ago.

The only other problem seems to be /atlas-Schaefer_description.json. I think the file is expected to be within the tpl-MNI152NLin6Asym folder. Personally, I don't love that organization (see #501 (comment)).

EDIT: Never mind, that one was because it was atlas-Schaefer instead of atlas-Schaefer2018. @effigies fixed it.

@effigies effigies merged commit b90da27 into bids-standard:bep038 Nov 4, 2025
12 checks passed
@effigies
Copy link
Copy Markdown
Contributor

effigies commented Nov 4, 2025

@PeerHerholz Feel free to make any further changes, just wanted to get everything in one place.

@PeerHerholz
Copy link
Copy Markdown
Member Author

PeerHerholz commented Nov 5, 2025 •
edited
Loading

Hey @tsalo and @effigies,

thanks for the pointers and support. Sorry for missing some of the details!
Please just let me know if I should do something else.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@tsalo tsalo tsalo requested changes

@effigies effigies Awaiting requested review from effigies

Assignees

@PeerHerholz PeerHerholz

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@PeerHerholz @tsalo @effigies