James Kent edits to bep038 (Atlas Specification) #1764

jdkent · 2024-04-05T20:57:13Z

Rendered proposal: https://bids-specification--1764.org.readthedocs.build/en/1764/atlas.html

random thoughts for notekeeping

looking at Oscar's suggestions in this comment for changes in the file structure:
#1281 (comment)

the file structure changes look like an improvement to me (nothing appears to drastically change)

CASE 1:

original

<dataset>/atlas/atlas-<label>/
  atlas-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii][.gz]
  atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv
  atlas-<label>_desc-<label>_[dseg|probseg|mask].json

<dataset>/derivatives/<pipeline>/
  atlas-<label>_space-<label>_res-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|.tsv][.gz]
  atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].tsv
  atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].json

Oscar's proposal

<dataset>/derivatives/<pipeline>/
    atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv   # These will generally be shared across templates/spaces
    atlas-<label>_desc-<label>_[dseg|probseg|mask].json
    tpl-<spacelabel>/
        tpl-<spacelabel>_atlas-<label>_res-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|.tsv][.gz]
        tpl-<spacelabel>_atlas-<label>_desc-<label>_[dseg|probseg|mask].json # This one requires specific meta
    tpl-<space2label>/
        tpl-<space2label>_atlas-<label>_res-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|.tsv][.gz]

What I like about Oscar's structure is that:

the atlas data is in one place (as opposed to being in both the raw and derivative dataset). Are there cases where a raw dataset does not make sense without an accompanying atlas?
there is increased alignment with templateflow (which I think would dovetail nicely with a template bep)
the important bits of the atlas are maintained at the top level so I'm not lost looking for atlas information. I would only add that for specific templates, one could argue that some roi's/indices/parcels could be resampled out of existence, and perhaps the tsv would want to reflect the reality of the situation.

For findability/searchability there is debate as to whether an atlas or a template should be a first class citizen. Looking at the templateflow website, it is not clear what atlases are available. Adding the tsv/json at the top level will make that much more clear, (and ideally, each atlas could be expressed in each template space, user beware!).

BIDS maintainer proposal (making an atlas as its own derivative dataset expressed in one or more spaces)

<dataset>/derivatives/<pipeline>/
    atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv   # These will generally be shared across templates/spaces
    atlas-<label>_desc-<label>_[dseg|probseg|mask].json
    space-<spacelabel>/
        space-<spacelabel>_atlas-<label>_res-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|.tsv][.gz]
        space-<spacelabel>_atlas-<label>_desc-<label>_[dseg|probseg|mask].json # This one requires specific meta
    space-<space2label>/
        space-<space2label>_atlas-<label>_res-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|.tsv][.gz]

This is a concept mapping from tpl being a reference and space being an application of the reference, so the tpl directory becomes an atlas. The order of entities is a little weird, since the folder starts with space, but then atlas becomes a first class citizen again. This use case is for packaging an atlas by itself, the primary use-cases deriving this

BIDS maintainer proposal (making an atlas as its own derivative in one space)

<dataset>/derivatives/<pipeline>/
    atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv   # These will generally be shared across templates/spaces
    atlas-<label>_desc-<label>_[dseg|probseg|mask].json
    atlas-<label>_res-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|.tsv][.gz]

where the spatial reference is defined in the .json file and the space directory is redundant.
OR
do the same thing as the previous example and include the space-<spacelabel> directory

Case 2

original

<dataset>/atlas/atlas-<label>/
  atlas-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii][.gz]
  atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv
  atlas-<label>_desc-<label>_[dseg|probseg|mask].json

<dataset>/derivatives/
  sub-01/
    func/
      sub-01_space-<label>_seg-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz]
      sub-01_space-<label>_seg-<label>_desc-<label>_[dseg|probseg|mask].tsv
      sub-01_space-<label>_seg-<label>_desc-<label>_[dseg|probseg|mask].json

Oscar's proposal

<dataset>/derivatives/
    atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv   # These will generally be shared across subjects
    atlas-<label>_desc-<label>_[dseg|probseg|mask].json
    sub-01/
        func/
            sub-01_atlas-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz]
            sub-01_atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv
            sub-01_atlas-<label>_desc-<label>_[dseg|probseg|mask].json
            sub-01_space-<label>_atlas-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz]
            sub-01_space-<label>_atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv
            sub-01_space-<label>_atlas-<label>_desc-<label>_[dseg|probseg|mask].json

I also prefer Oscar's suggestion here because:

He's not storing the atlas in the raw dataset (same as case 1)
Inheritence looks clean

There is the magic of how the atlases got into a particular space, but the spatialReference defined in the top level .json file should identify the original template used by the atlas. For practicality of sharing, I would probably also include the actual atlas image at the top level of derivatives so that people can more easily apply the necessary transformations

James' proposal

<dataset>/derivatives/
    atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv   # These will generally be shared across subjects
    atlas-<label>_desc-<label>_[dseg|probseg|mask].json
    tpl-<spacelabel>/
        tpl-<spacelabel>_atlas-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii][.gz]  # for ease of transforming the original atlas into the respective space
    sub-01/
        func/
            sub-01_atlas-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz]
            sub-01_atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv
            sub-01_atlas-<label>_desc-<label>_[dseg|probseg|mask].json
            sub-01_space-<label>_atlas-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz]
            sub-01_space-<label>_atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv
            sub-01_space-<label>_atlas-<label>_desc-<label>_[dseg|probseg|mask].json

BIDS maintainer proposal (space

<dataset>/derivatives/
    atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv   # These will generally be shared across subjects
    atlas-<label>_space-<space1label>_desc-<label>_[dseg|probseg|mask].json
    atlas-<label>_space-<space2label>_desc-<label>_[dseg|probseg|mask].json
    atlas-<label>/
        atlas-<label>_space-<space1label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii][.gz]  # for ease of transforming the original atlas into the respective space
        atlas-<label>_space-<space2label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii][.gz] 
    sub-01/
        func/
            sub-01_atlas-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz]
            sub-01_atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv
            sub-01_atlas-<label>_desc-<label>_[dseg|probseg|mask].json
            sub-01_atlas-<label>_space-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz]
            sub-01_atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].tsv
            sub-01_atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].json

If someone has multiple atlases in a dataset, it may get crowded in the top level with the number of files. so placing the files in subdirectories help with the aesthetics.

Case 3:

Original

<dataset>/derivatives/
  sub-01/
    anat/
      sub-01_atlas-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz][.ome-tiff|.png]
      sub-01_atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv
      sub-01_atlas-<label>_desc-<label>_[dseg|probseg|mask].json
      sub-01_atlas-<label>_desc-<label>_coordsystem.json

Oscar's proposal:

No change

This one also looks fine to me!

Overall I find Oscar's suggestions clean, and I'm fine with treating an atlas as a modular derivative (that does not need to reside in a BIDS-raw dataset).

BIDS Maintainer's proposal

Also no changes for this use case.

Case 4 (just referencing an external atlas)

/derivatives/
dataset_description.json # {"SourceDatasets": [ {"URL": "../../atlas-/"} ]
sub-01/
func/
sub-01_atlas-_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz]
sub-01_atlas-space-[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz]

I come from a very MRI-centric perspective, and from that perspective I think Oscar's proposed changes do not impede those use-cases (AFAICT).

should an atlas be its own type of dataset (e.g., raw, derivatives, atlas)?

What does making an atlas different than a derivative buy us? Does it make validation easier?
Does it restrict what can go in that dataset? Does it make sharing easier?

Maybe I want to include an atlas with multiple other derivatives in my pipeline output, do I need to separate out
the atlas files to make my pipeline output sharable?

jdkent · 2024-04-12T07:48:59Z

Thinking about adding an atlas_description.json to give general information about the atlas, then using atlas-_dseg.json to hold information about the resolution and spatial reference, since this is the information that is going to change the most.

Case 1 (sharing an atlas)

<dataset>/derivatives/<pipeline>/
    atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv   # These will generally be shared across templates/spaces
    atlas-<label>_desc-<label>_[dseg|probseg|mask].json  # {spatialReference: "orig_space_uri"}
    atlas-<label>_space-<spacelabel>_res-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|.tsv][.gz]
    atlas-<label>_space-<spacelabel>_desc-<label>_[dseg|probseg|mask].json # {spatialReference: "spacelabel"}
    atlas-<label>_space-<space2label>_res-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|.tsv][.gz]
    atlas-<label>_space-<space2label>_desc-<label>_[dseg|probseg|mask].json # {spatialReference: "space2label"}
    atlas-<label>_description.json

Case 2 (using a group level atlas resampled into individual spaces

<dataset>/derivatives/
    atlas-<label>_description.json
    atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv   # These will generally be shared across subjects
    atlas-<label>_space-<space1label>_desc-<label>_[dseg|probseg|mask].json # {"spatialReference": "space1label"}
    atlas-<label>_space-<space2label>_desc-<label>_[dseg|probseg|mask].json # {"spatialReference": "space2label"}
    sub-01/
        func/
            sub-01_atlas-<label>_space-<space1label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz]
            sub-01_atlas-<label>_space-<space2label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz]

case 3 (a subject-specific derived atlas, the same as the original)

N/A

the current JSON file has information that assumes the atlas is being expressed in a single space and that is primarily it.
This should be split into two files. One should be an atlas-<label>_description.json which has immutable information about how the atlas was derived.

The other one should be the atlas-<label>_dseg.json which has: SpatialReference and Resolution defined. These parameters focus on the projection of an atlas to a specific space which could be any space at any resolution, while the original atlas will be a projection of a specific space to a particular resolution (or a set of spaces/resolutions), how an atlas is used in a particular derivative dataset could be in several spaces/resolutions that are not in the originally distributed atlas.

atlas-<label>_description.json

Name	REQUIRED. Name of the atlas
Description	RECOMMENDED. Longform description of the atlas
Dimensions	RECOMMENDED. Dimensions of the atlas, MUST be 3 (for deterministic atlases) or 4 (for probabilistic atlases).
4thDimension	OPTIONAL. RECOMMENDED if probabilistic atlas. Should indicate what the 4th dimension entails/refers to, e.g. “Indices”.
CoordinateReportStrategy	OPTIONAL. MUST BE ONE OF: “peak”, “center_of_mass”, “other”. Indicate the method of coordinate reporting in statistically significant clusters. Could be the “peak” statistical coordinate in the cluster or the “center_of_mass” of the cluster. RECOMMENDED if x, y ,z values are set in the .tsv file.
Authors	RECOMMENDED. List of the authors involved in the creation of the atlas
Curators	RECOMMENDED. List of curators who helped make the atlas accessible in a database or dataset
Funding	RECOMMENDED. The funding source(s) involved in the atlas creation
License	RECOMMENDED. The license agreement for using the atlas.
ReferencesAndLinks	RECOMMENDED. A list of relevant references and links pertaining to the atlas.
Species	RECOMMENDED. The species the atlas was derived from. For example, could be homo sapiens, Macaque, Rat, Mouse, etc.
DerivedFrom	RECOMMENDED. Indicate what data modality the atlas was derived from, e.g. "cytoarchitecture", "resting-state", "task".
LevelType	RECOMMENDED. Indicate what analysis level the atlas was derived from, e.g. "group", "individual".

atlas-<label>_dseg.json

Name	Description
SpatialReference	RECOMMENDED. Point to an existing atlas in a template space (url or relative file path where this file is located).
Resolution	RECOMMENDED. Resolution atlas is provided in.

Okay, so if the general use cases can be broken down into 3 buckets:

sharing an atlas as a standalone
resampling an existing atlas into subject space
generating subject specific atlases

Let's test out the 3 use cases

Case 1: sharing an atlas as a standalone

basic

<dataset>/derivatives/<pipeline>/
    atlas-<label>_description.json
    atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv   # These will generally be shared across templates/spaces
    atlas-<label>_desc-<label>_[dseg|probseg|mask].json  # {spatialReference: "orig_space_uri"}
    atlas-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|.tsv][.gz]

The atlas is only projected onto one template space

multiple spaces

<dataset>/derivatives/<pipeline>/
    atlas-<label>_description.json
    atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv   # These will generally be shared across templates/spaces
    atlas-<label>_space-<space1label>_desc-<label>_[dseg|probseg|mask].json  # {spatialReference: "space1label_uri"}
    atlas-<label>_space-<space1label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|.tsv][.gz]
    atlas-<label>_space-<space2label>_desc-<label>_[dseg|probseg|mask].json  # {spatialReference: "space2label_uri"}
    atlas-<label>_space-<space2label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|.tsv][.gz]

You could just have one not have the space label, but that wouldn't be recommended.

multiple spaces (valid, but not recommended)

<dataset>/derivatives/<pipeline>/
    atlas-<label>_description.json
    atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv   # These will generally be shared across templates/spaces
    atlas-<label>_desc-<label>_[dseg|probseg|mask].json  # {spatialReference: "space1label_uri"}
    atlas-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|.tsv][.gz]
    atlas-<label>_space-<space2label>_desc-<label>_[dseg|probseg|mask].json  # {spatialReference: "space2label_uri"}
    atlas-<label>_space-<space2label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|.tsv][.gz]

Use-case 2: resampling an existing atlas into subject space/resolution/etc

basic

<dataset>/derivatives/
    atlas-<label>_description.json
    atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv   # These will generally be shared across subjects
    atlas-<label>_desc-<label>_[dseg|probseg|mask].json
    atlas-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|.tsv][.gz]
    sub-01/
        func/
            sub-01_atlas-<label>_[dseg|probseg|mask].json {"spatialReference": "orig_uri", "resolution": "3mm iso"}
            sub-01_atlas-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz]

The json file at the subject level overwrites the top level json file, so the correct spatialReference and resolution is found.
The top level json file here is primarily useful for describing the original atlas and then that information is used to transform the atlas template into subject space, the transformation is applied to the actual atlas file to create the subject specific json. I can imagine use cases where the original atlas is projected onto multiple spaces and at the subject level those spaces are resampled to the subject specific resolution. If people want to re-write tsvs at the top level for specific resolutions or at the subject level to identify missing ROIs, that works as well.

Use-case 3: subject-specific atlases

<dataset>/derivatives/
  atlas_description.json
  sub-01/
    anat/
      sub-01_atlas-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz][.ome-tiff|.png]
      sub-01_atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv
      sub-01_atlas-<label>_desc-<label>_[dseg|probseg|mask].json
      sub-01_atlas-<label>_desc-<label>_coordsystem.json

The atlas_description.json could be added at the top level if the method of generation for each subject was the same.

pwighton · 2024-04-12T18:04:22Z

This looks good to me.

Though I think we will want a cohort or group entity so we can create atlases from various cohorts, e.g cohort-control, cohort-young, cohort-dementia, etc.

for more information, see https://pre-commit.ci

pwighton · 2024-04-12T21:43:33Z

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

+    - probseg
+    - mask
+  extensions:
+    - .label.gii


Suggested change

- .label.gii

- .gii

- .label.gii

To account for scalar-based atlases

jdkent · 2024-04-12T22:58:44Z

For commit 14098b3

strengths

Inheritance works as is without adding weird rules or having to copy a lot of the same data in json files
Leverages a lot of the existing BIDS/BIDS derivatives structure (e.g., fewer changes needed to the spec to support this)
- Makes it easier to get the spec to validate
IMO: use case 2 (resampling/transforming an atlas into a new template or subject space) is a common use case, and this proposal is designed so that it is easy to start with use case 1 and simply add files to support use case 2 without having to rename or move files around.

drawbacks

Have to copy the shared atlas into the derivative dataset to access metadata for resampling
- Think about how we can reference a publically shared atlas and inherit the metadata
- Or bite the bullet and copy the atlas into the derivative dataset, since most atlases are not large
  - This would be analogous to copying fmriprep outputs into another derivative dataset for further analysis.
atlas-<label>_description.json is not currently a BIDS derivatives file, and is partially overlapping
with dataset_description.json
The 4 main files exist at the root of the dataset, which may look cluttered to some users
- embedded folders is an alternative, but for inheritance to work in use-case 2 (which I think is a modal use-case),
  the files need to be at the root of the dataset, so that the validator can find them, and the metadata be inherited.
Does not leverage the seg-<label> entity for the atlas
- to support seg-<label> with inheritance, it requires more complex changes to the validator and spec.
- Or we can give up on keeping track of the metadata from the atlas to its resampling/transformations to subject
  specific spaces
Does not separate the concept of a segmentation and atlas very well
Dimensions and 4thDimension may belong in the sidecar json file and not the atlas-<label>_description.json file

melanieganz · 2024-04-15T13:20:28Z

Dear @jdkent,

thank you so much for all the work you have put in to consolidate both standpoints with fresh eyes! 🙏 The OpenneuroPET team which was also one of the drivers behind the atlas BEP highly appreciates that.
We are still going through the details, but one of the major things why we wanted an atlas outside of a derivative was that we would be able to validate a standalone atlas data set. So far it is not possible to upload data that only consist of derivatives on OpenNeuro in order to make atlases findable. Could you maybe comment on that already while we go through the details?

jdkent · 2024-04-16T15:44:00Z

Hi @melanieganz ,

I've got another round of edits to make to fully encompass the feedback I got during the meeting, so please hold off trying to understand the mess 😆, wrt your comment:

one of the major things why we wanted an atlas outside of a derivative was that we would be able to validate a standalone atlas data set. So far it is not possible to upload data that only consist of derivatives on OpenNeuro in order to make atlases findable.

Talking with @rwblair, it sounds like this is a relatively high-priority item to make a derivative dataset uploadable to openneuro.

CPernet · 2024-04-22T06:31:17Z

Hi James,

The issue can see is that those changes do not allow what was also intended, ie to share an atlas on it's own (or I missed something? - all the examples are /derivatives - re Case 1 )

To give everyone the context, there was a discussion about 1.5 years ago about where 'atlas' should be shared - being as usage or for sharing on it's own. It was 'decided' that sharing at the root level was best because:
(1) an atlas is both a tool (like stuff in code) and a image (like stuff in sub-)
(2) moving to root allows sharing new altases on their own

Back to the PR, I'd suggest allowing the folder /atlas in the root directory as initially proposed and of course still possible in /derivatives as the output of a computation. Thx

PS: can't share on it's own because if no sub- in root, then not valid

jdkent · 2024-04-23T16:00:56Z

The issue can see is that those changes do not allow what was also intended, ie to share an atlas on it's own (or I missed something? - all the examples are /derivatives - re Case 1 )

That is a good concern, definitely want to keep the ability to share an atlas on its own.

From my understanding of the derivative common principles (see storage of derived datasets, point number 2),
one should be able to share a derived dataset as a standalone dataset, enabling the use case of sharing an atlas on its own.

The sub- being required in BIDS-root is a pesky nuisance, I think for atlases (and other derivatives), it motivates the ability to share without that requirement, I'm not a %100 positive, but I believe that sub- is not required in derivative datasets, I think the problems with uploads to openneuro are more of a validation (server side), than a problem with the data itself.

will look into that.

CPernet · 2024-04-24T06:25:11Z

Very good point @jdkent we could show both options for case 1, adding in the the dataset_description.json DatasetType. What do you think?

dataset_description.json
DatasetType: 'raw'
<dataset>/derivatives/<pipeline>/atlas/
    atlas-<label>_description.json
    atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv   # constructed from sub- in the dataset - shows how it is build
    atlas-<label>_desc-<label>_[dseg|probseg|mask].json  # {spatialReference: "orig_space_uri"}
    atlas-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|.tsv][.gz]
<dataset>/sub-001/
<dataset>/sub-002/

dataset_description.json
DatasetType: 'derivative'
<dataset>/atlas/
    atlas-<label>_description.json
    atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv   # this will generally be for sharing
    atlas-<label>_desc-<label>_[dseg|probseg|mask].json 
    atlas-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|.tsv][.gz]

-- and yes you are right it has consequences on the validation - I will make an example which indeed will remind us to 'promote' atlas- at the same level as sub- but a conditional statement is needed in the validator if atlas- then sub- not mandatory

@melanieganz @effigies is there a BIDS-example repo fork we can push stuff for this PR?

effigies · 2024-04-24T21:49:57Z

If one does not exist, I would suggest just making a bep038 branch on the main repo.

melanieganz · 2024-04-29T13:25:54Z

Dear @CPernet and @jdkent,

I just made a branch of the bids-examples according to what @effigies suggested. So we can add stuff there: https://github.com/bids-standard/bids-examples/tree/bep038

melanieganz · 2024-04-30T10:18:30Z

Dear @jdkent, @CPernet, @effigies, @pwighton and @oesteban,

as suggested by @effigies I added a bep038 branch to the bids examples and following the example structure that Cyril suggested above I added two examples for atlas001 (raw dataset) and atlas002 (derivative dataset) that are very generic and that we can base our discussion on. I also added an atlas003 example where I tried to base it on the PET atlas that @pwighton has already shared.

Can you please look at them and let me know if that makes sense and if that covers your needs or what changes are necessary?

Also please note, when making the examples in the bids-example repo I discussed the example Cyril had made above with him and he corrected some misspelling there through me.

PeerHerholz · 2024-04-30T20:52:05Z

Hello everyone,

thank you very much for your continued discussion and work on this.

We also started BEP038 examples during the Copenhagen meeting last year here. I think most, if not all of them, are outdated and are thus, for reference.

Thanks again.

Best, Peer

melanieganz · 2024-05-13T13:29:14Z

Dear @jdkent ,

we really, really would like to have this move forward. But you anted to fix the examples so they align with your ideas. Can we help with this? Can you point me to the right examples in the text and then I can make examples for the validator to check?

jdkent · 2024-05-14T15:14:25Z

apologies, I am setting some time this week to finish this up.

…n into bep038_jk_edits

for more information, see https://pre-commit.ci

…n into bep038_jk_edits

jdkent · 2024-05-15T21:50:47Z

Hi @melanieganz, I have updated the examples here

melanieganz · 2024-05-30T19:13:40Z

Hi @jdkent,

thank you! So just that we agree, I can take the examples from the .md you linked to and add them to/modify the existing examples in https://github.com/bids-standard/bids-examples/tree/bep038 and then we are good to check this with @rwblair?

jdkent · 2024-05-30T19:50:48Z

yes, I am in agreement with modifying those examples and then checking in.

oesteban · 2024-06-12T11:51:42Z

@melanieganz I am working on uploading PS13 to templateflow, showing how that tool would encode it. I hit an issue with these examples atlas003/atlas/petsurfer/atlas-ps13_hemi-{R,L}_space-fsaverage_stat-mean_desc-nopvc_mimap.nii.gz

NIfTI files are borderline "valid" to allow hemi- (just because we haven't explicitly forbidden it, but it feels like we should). These should be GIFTIs as they encode surface information.

Other than that, I cannot provide more useful feedback because I don't think the proposal is in good shape. I've been preparing a PR for the last three months and hope to finish it today -- apologies for the delays.

make a couple clarifying edits

6ecbacf

jdkent changed the title ~~Keeping track of my edits to bep038~~ James Kent edits to bep038 (Atlas Specification) Apr 5, 2024

add rules/entities and supplement the spec with examples

14098b3

jdkent requested review from tsalo and erdalkaraca as code owners April 12, 2024 21:32

[pre-commit.ci] auto fixes from pre-commit.com hooks

85ae55f

for more information, see https://pre-commit.ci

pwighton reviewed Apr 12, 2024

View reviewed changes

francopestilli mentioned this pull request Apr 30, 2024

BEP-038: Atlases #1714

Draft

jdkent and others added 5 commits May 15, 2024 16:43

update examples

6ae64b5

Merge branch 'bep038_jk_edits' of github.com:jdkent/bids-specificatio…

3fc6598

…n into bep038_jk_edits

[pre-commit.ci] auto fixes from pre-commit.com hooks

60b717a

for more information, see https://pre-commit.ci

fix heading

7334478

Merge branch 'bep038_jk_edits' of github.com:jdkent/bids-specificatio…

4f1dfa3

…n into bep038_jk_edits

Remi-Gau added the BEP label Jun 18, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

James Kent edits to bep038 (Atlas Specification) #1764

James Kent edits to bep038 (Atlas Specification) #1764

jdkent commented Apr 5, 2024 •

edited by effigies

Loading

jdkent commented Apr 12, 2024

pwighton commented Apr 12, 2024

pwighton Apr 12, 2024

jdkent commented Apr 12, 2024

melanieganz commented Apr 15, 2024 •

edited

Loading

jdkent commented Apr 16, 2024

CPernet commented Apr 22, 2024 •

edited

Loading

jdkent commented Apr 23, 2024

CPernet commented Apr 24, 2024 •

edited

Loading

effigies commented Apr 24, 2024

melanieganz commented Apr 29, 2024

melanieganz commented Apr 30, 2024

PeerHerholz commented Apr 30, 2024

melanieganz commented May 13, 2024

jdkent commented May 14, 2024

jdkent commented May 15, 2024

melanieganz commented May 30, 2024

jdkent commented May 30, 2024

oesteban commented Jun 12, 2024

James Kent edits to bep038 (Atlas Specification) #1764

Are you sure you want to change the base?

James Kent edits to bep038 (Atlas Specification) #1764

Conversation

jdkent commented Apr 5, 2024 • edited by effigies Loading

random thoughts for notekeeping

CASE 1:

original

Oscar's proposal

BIDS maintainer proposal (making an atlas as its own derivative dataset expressed in one or more spaces)

BIDS maintainer proposal (making an atlas as its own derivative in one space)

Case 2

original

Oscar's proposal

James' proposal

BIDS maintainer proposal (space

Case 3:

Original

Oscar's proposal:

BIDS Maintainer's proposal

Case 4 (just referencing an external atlas)

should an atlas be its own type of dataset (e.g., raw, derivatives, atlas)?

jdkent commented Apr 12, 2024

Case 1 (sharing an atlas)

Case 2 (using a group level atlas resampled into individual spaces

case 3 (a subject-specific derived atlas, the same as the original)

Case 1: sharing an atlas as a standalone

basic

multiple spaces

multiple spaces (valid, but not recommended)

Use-case 2: resampling an existing atlas into subject space/resolution/etc

basic

Use-case 3: subject-specific atlases

pwighton commented Apr 12, 2024

pwighton Apr 12, 2024

Choose a reason for hiding this comment

jdkent commented Apr 12, 2024

strengths

drawbacks

melanieganz commented Apr 15, 2024 • edited Loading

jdkent commented Apr 16, 2024

CPernet commented Apr 22, 2024 • edited Loading

jdkent commented Apr 23, 2024

CPernet commented Apr 24, 2024 • edited Loading

effigies commented Apr 24, 2024

melanieganz commented Apr 29, 2024

melanieganz commented Apr 30, 2024

PeerHerholz commented Apr 30, 2024

melanieganz commented May 13, 2024

jdkent commented May 14, 2024

jdkent commented May 15, 2024

melanieganz commented May 30, 2024

jdkent commented May 30, 2024

oesteban commented Jun 12, 2024

jdkent commented Apr 5, 2024 •

edited by effigies

Loading

melanieganz commented Apr 15, 2024 •

edited

Loading

CPernet commented Apr 22, 2024 •

edited

Loading

CPernet commented Apr 24, 2024 •

edited

Loading