From 6ecbacfda0ffd9e262d09e4d0690b7e1c3af2d8a Mon Sep 17 00:00:00 2001 From: James Kent Date: Fri, 5 Apr 2024 15:55:55 -0500 Subject: [PATCH 1/6] make a couple clarifying edits --- src/atlas.md | 52 ++++++++++++++++++++++++++++++++-------------------- 1 file changed, 32 insertions(+), 20 deletions(-) diff --git a/src/atlas.md b/src/atlas.md index 6a2297b97f..d5d0e6478e 100644 --- a/src/atlas.md +++ b/src/atlas.md @@ -294,7 +294,7 @@ index label network_label hemisphere ``` The `[probseg|dseg|mask].json` file provides metadata to uniquely identify, describe and characterize the atlas, as well as give proper attribution to the creators. -Additionally, SpatialReference serves the important purpose of unambiguously identifying the space the atlas is labeled in. +Additionally, SpatialReference serves the important purpose of unambiguously identifying the template/space the atlas is labeled in. @@ -312,7 +312,7 @@ Additionally, SpatialReference serves the important purpose of unambiguously ide - @@ -395,7 +395,7 @@ Example: ```JSON { - "Name": "FSL's MNI ICBM 152 non-linear 6th Generation Asymmetric Average Brain Stereotaxic Registration Model", + "Name": "HarvardOxford cort maxprob thr25 2mm", "Authors": [ "David Kennedy", "Christian Haselgrove", @@ -408,7 +408,6 @@ Example: "BIDSVersion": "1.1.0", "Curators": "FSL team", "SpatialReference": "https://templateflow.s3.amazonaws.com/tpl-MNI152NLin6Asym_res-02_T1w.nii.gz", - "Space": "MNI152NLin6Asym", "Resolution": "Matched with original template resolution (2x2x3 mm^3)", "License": "See LICENSE file", "RRID": "SCR_002823", @@ -445,6 +444,7 @@ Example content of the `atlas-HarvardOxford_res-2_dseg.json` file: ```JSON { + "Name": "HarvardOxford cort maxprob thr25 2mm",, "Authors": [ "David Kennedy", "Christian Haselgrove", @@ -457,10 +457,8 @@ Example content of the `atlas-HarvardOxford_res-2_dseg.json` file: "BIDSVersion": "1.1.0", "Curators": "FSL team", "SpatialReference": "https://templateflow.s3.amazonaws.com/tpl-MNI152NLin6Asym_res-02_T1w.nii.gz", - "Space": "MNI152NLin6Asym", "Resolution": "Matched with original template resolution (2x2x3 mm^3)", "License": "See LICENSE file", - "Name": "FSL's MNI ICBM 152 non-linear 6th Generation Asymmetric Average Brain Stereotaxic Registration Model", "RRID": "SCR_002823", "ReferencesAndLinks": [ "https://doi.org/10.1016/j.neuroimage.2012.01.024", @@ -550,10 +548,9 @@ Example content of the `sub-01_space-T1w_seg-HarvardOxford_res-2_dseg.json` file { "BIDSVersion": "1.1.0", "SpatialReference": "sub-01/anat/sub-01_T1w.nii.gz", - "Space": "T1w", "Resolution": "Matched with original resolution in subject T1w space (1x1x1 mm^3)", "Sources": [], - "transformation": + "transformation": ["TBD"] } ``` @@ -588,23 +585,38 @@ bids/derivatives/pipeline-/ The json file accompanying the functionally derived atlas should include the following information. -Example content of the `sub-01_task-rest_atlas.json` file contains top-level metadata about the atlas: +Example content of the `atlas-FreeSurferASEG_dseg.json` file contains top-level metadata about the atlas: ```JSON -"Atlas": { - "Russome": - { - "Atlasfile": "/link/to/russome/file", - "Extra": "individualized surface parcellation" - }, - "FS_aseg": { - "Atlasfile": "/link/to/aseg/file", - "Extra": "freesurfer aseg" - } + "Name": "FreeSurferASEG",, + "Authors": [ + "Bruce Fischl", + "David H. Salat", + "Evelina Busa", + "Marilyn Albert", + "Megan Dieterich", + "Christian Haselgrove", + "Andre van der Kouwe", + "Ron Killiany", + "David Kennedy", + "Shuna Klaveness", + "Albert Montillo", + "Nikos Makris", + "Bruce Rosen", + "Anders M. Dale", + ], + "BIDSVersion": "1.1.0", + "SpatialReference": "link to template (unclear)", + "Resolution": "Matched with original template resolution (2x2x3 mm^3)", + "License": "See LICENSE file", + "ReferencesAndLinks": [ + "https://surfer.nmr.mgh.harvard.edu/fswiki/FreeSurferVersion3", + "https://surfer.nmr.mgh.harvard.edu/ftp/articles/fischl02-labeling.pdf", + ], + "Species": "Human" } - ``` ## Quantitative atlas examples From 14098b391fb2ac04ebd1255b5019810531ed342e Mon Sep 17 00:00:00 2001 From: James Kent Date: Fri, 12 Apr 2024 16:32:20 -0500 Subject: [PATCH 2/6] add rules/entities and supplement the spec with examples --- src/atlas.md | 840 ++++++++++++++---------- src/schema/objects/entities.yaml | 2 + src/schema/objects/extensions.yaml | 7 + src/schema/rules/entities.yaml | 1 + src/schema/rules/files/deriv/atlas.yaml | 64 ++ 5 files changed, 565 insertions(+), 349 deletions(-) create mode 100644 src/schema/rules/files/deriv/atlas.yaml diff --git a/src/atlas.md b/src/atlas.md index d5d0e6478e..3141e43a97 100644 --- a/src/atlas.md +++ b/src/atlas.md @@ -1,425 +1,445 @@ # BIDS-Atlas In the following we describe how an [atlas](schema/objects/entities.yaml#atlas) can be shared within BIDS. -We describe a broad set of atlases and use cases thereof. +Broadly we define an atlas as a reference quantity sampled to a template. +With this definition, an atlas can be a parcellation, a segmentation, or a quantitative map. -More specifically, this entails providing and referring to existing atlas datasets, -describing atlases that were newly derived within an analysis, -and providing information for derivatives that were obtained through them. -The first would comprise (publicly) available atlases, for example, +We aim to cover three main use cases with the given definition: +1. Generating/sharing an atlas to be published and used by others. +2. Using a shared atlas and transforming/resampling it into new template spaces or subject spaces. +3. Creating subject-specific atlases derived from the corresponding subject’s data. + +These three use cases cover the majority of scenarios where atlases are used in neuroimaging research. + +The first use case would comprise (publicly) available atlases, for example, Destrieux et al. ([doi.org/10.1016/j.neuroimage.2010.06.010](https://doi.org/10.1016/j.neuroimage.2010.06.010)), AAL ([doi.org/10.1006/nimg.2001.0978](https://doi.org/10.1006/nimg.2001.0978)), Yeo ([doi.org/10.1152/jn.00338.2011](https://doi.org/10.1152/jn.00338.2011)) and JHU DTI-based white-matter atlases ([eBook ISBN: 9780080456164](https://shop.elsevier.com/books/mri-atlas-of-human-white-matter/mori/978-0-444-51741-8) -and [doi.org/10.1016/j.neuroimage.2007.07.053](https://doi.org/10.1016/j.neuroimage.2007.07.053)), -while the second would include atlases obtained through analyses within a dataset at hand, +and [doi.org/10.1016/j.neuroimage.2007.07.053](https://doi.org/10.1016/j.neuroimage.2007.07.053)). +The second use case would comprise transforming/resampling the publicly available atlases into new template spaces or subject spaces for further analysis. +For example, resampling the AAL atlas from MNI152NLin6Asym space to a subject’s native T1w space. +The third use case would include atlases obtained through analyses within a dataset at hand, for example, resting-state networks and functional localizers. -Importantly, the latter can also be utilized as existing atlases if made available. -The third would entail referencing an atlas and its properties used to derive, -for example, a parcellated time series or a connectivity matrix. - -## Atlas as new DatasetType -Here we introduce an additional value to the `DatasetType field` of `dataset_description.json`. -If a dataset declares its DatasetType to be [atlas](schema/objects/entities.yaml#atlas), -the top-level directories MUST be `atlas-` instead of `sub-`. -This will allow sharing existing atlases as stand-alone datasets, -validating them via the [BIDS validator](https://github.com/bids-standard/bids-validator) and enabling their integration as sub-datasets of other BIDS datasets. - -## File formats for the raw data -BIDS-Atlas aims to describe brain atlases via three REQUIRED files. -They entail the atlas itself (for example, in .nii, .nii.gz, .gii, or .tsv), -a file indexing/labeling each node in the atlas (in .tsv) and a file containing exhaustive meta-data about the atlas (in .json). - -The usage of [_desc-](schema/objects/entities.yaml#desc) is generally discouraged but should be evaluated on a case by case basis in order to keep this identifier available for necessary cases. -Specifically, this refers to the atlas at hand and potential different versions thereof. -As a rule of thumb, BIDS-Atlas proposed to evaluate and consider how many versions across how many levels of versions an atlas is (commonly) provided and used in. -If there is only one version, as in "release", of an atlas -and no sub-versions, as in "different parcel numbers" (or comparable), -[_desc-](schema/objects/entities.yaml#desc) is most likely not expected and/or required. -An example for [_desc-](schema/objects/entities.yaml#desc) in such a use case would be -to indicate a subset of parcels and would entail the addition of -the [_mask-](schema/objects/entities.yaml#mask) extension, -for example, providing/using the "postcentral gyrus" region of the [Destrieux atlas](doi:10.1093/cercor/bhg087.) would result in the following file name: -`atlas-Destrieux_space-MNI152NLin6Asym_res-2_desc-PostCentralGyrus_mask.nii.gz`. -Similar to the above case, if there are multiple versions, as in "release", -of an atlas and no sub-versions, as in "different parcel numbers" (or comparable), -[_desc-](schema/objects/entities.yaml#desc) is also most likely not expected and/or required, -as the version(s) (release(s)) should be indicated via `atlas-`. -For example, the different versions of the [AAL parcellation](http://www.gin.cnrs.fr/AAL-217?lang=en) -would result in the following file names: -`atlas-AAL1_space-MNI152NLin6Asym_res-2.nii.gz`, `atlas-AAL2_space-MNI152NLin6Asym_res-2.nii.gz` and `atlas-AAL3_space-MNI152NLin6Asym_res-2.nii.gz`. -Given an atlas has only one version, as in "release", and multiple sub-versions -as in "different parcel numbers" (or comparable) -[_desc-](schema/objects/entities.yaml#desc) is considered appropriate. -For example, when indicating information pertaining to the probabilistic nature of an atlas -such as the [_probseg](schema/objects/entities.yaml#probseg) version of -the [Harvard-Oxford parcellation](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Atlases): -`atlas-HarvardOxford_res-2_desc-th25_probseg.nii.gz`. -In cases where an atlas has multiple versions, as in "release", and sub-versions, -as in "different parcel numbers" (or comparable), -the version(s) (release(s)) should be indicated via `atlas-` as outlined above and the sub-versions should be indicated via [_desc-](schema/objects/entities.yaml#desc). -For example, different versions and sub-versions of the [Schaefer parcellation](https://github.com/ThomasYeoLab/CBIG/blob/master/stable_projects/brain_parcellation/Schaefer2018_LocalGlobal/Parcellations/Updates/Update_20190916_README.md) would be denoted as follows: -`atlas-Schaefer2018_space-MNI152NLin6Asym_res-2_desc-400Parcels7Networks.nii.gz`, -`atlas-Schaefer2018_space-MNI152NLin6Asym_res-2_desc-400Parcels17Networks.nii.gz`, -`atlas-Schaefer2022_space-MNI152NLin6Asym_res-2_desc-800Parcels7Networks.nii.gz` -and `atlas-Schaefer2022_space-MNI152NLin6Asym_res-2_desc-800Parcels17Networks.nii.gz`. - -Importantly, already existing BIDS entities should be used to indicate certain aspects of an atlas, -instead of [_desc-](schema/objects/entities.yaml#desc), for example, -[hemi](schema/objects/entities.yaml#hemi) to denote a given hemisphere -and [_dseg](schema/objects/entities.yaml#dseg)/[_probseg](schema/objects/entities.yaml#probseg) -to denote deterministic and probabilistic atlases respectively. - -However, as mentioned above, these are general guidelines and the exact implementation should be evaluated on a case by case basis, with deviations following common BIDS principles being permitted. - -## Directory Structure -BIDS-Atlas focuses on the utilization of atlases while also allowing their sharing. -Thus, atlases are either stored within a dedicated `atlas` directory at the BIDS root directory -(comparable to the `code` directory), -such files are the non-altered/original atlases or within a given directory under `derivatives`. -In the second case, atlases are altered, -derived or applied and thus multiple use cases have to be distinguished as indicated further below. - -### Representing an atlas as a dataset - -The first option refers to atlases that were not altered, for example, -via spatial transformations and/or resampling or applied to data -and thus their initial inclusion/utilization in a given dataset. -If there is only this form of atlases (that is, the tool used), -they are always shared at the root directory and everything else is under derivatives. -This allows validating any - -```Text -/atlas/ -``` - -using the [BIDS validator](https://github.com/bids-standard/bids-validator). -Importantly, only this case follows the same directory structure as -[sub](schema/objects/entities.yaml#sub), that is, one dedicated directory for each atlas within a given dataset. -The default way of storage of the non-altered atlas at the root directory looks like this: - -```Text -/atlas/atlas-
SpatialReference RECOMMENDED. Point to an existing atlas in a template space (URL or relative file path where this file is located). + RECOMMENDED. Point to an existing template space (URL or relative file path where this file is located).
- - - - - - - - - - - - - - - - - - - - - - - - + + + +
index (or placeholder in fragment in reference) + Name REQUIRED. (Integer) The number associated with the node/parcel/region (right/left hemispheres may be different). + REQUIRED. Name of the atlas
label + Description RECOMMENDED. The node name + RECOMMENDED. Longform description of the atlas
network_id + Dimensions OPTIONAL. Network ID the node/parcel belongs to + RECOMMENDED. Dimensions of the atlas, MUST be 3 (for deterministic atlases) or 4 (for probabilistic atlases).
network_label + 4thDimension OPTIONAL. Label of Network (for example, Dorsal Attention Network) + OPTIONAL. RECOMMENDED if probabilistic atlas. Should indicate what the 4th dimension entails/refers to. MUST be "Indices" or .
coordinate_report_strategy + CoordinateReportStrategy OPTIONAL (RECOMMENDED if x, y, z keys are specified). The strategy used to assess and report x, y and z coordinates of a given node/parcel/region. For example, "CenterOfMass". + 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.
x + Authors OPTIONAL. The x-coordinate of the node in the spatial reference space (See SpatialReference in the .json file) + RECOMMENDED. List of the authors involved in the creation of the atlas
y + Curators OPTIONAL. The y-coordinate of the node in the spatial reference space (See SpatialReference in the .json file) + RECOMMENDED. List of curators who helped make the atlas accessible in a database or dataset
z + Funding OPTIONAL. The z-coordinate of the node in the spatial reference space (See SpatialReference in the .json file) + RECOMMENDED. The funding source(s) involved in the atlas creation
hemisphere + License OPTIONAL. MUST BE ONE OF: "left", "right", "bilateral". Indicate whether the node/parcel/region is in the left or right hemispheres, or is available bilaterally. + RECOMMENDED. The license agreement for using the atlas.
color + ReferencesAndLinks OPTIONAL. RGB color to use for the node. + RECOMMENDED. A list of relevant references and links pertaining to the atlas.
seed + Species OPTIONAL. Seed vertex/channel of the node/region + RECOMMENDED. The species the atlas was derived from. For example, could be Human, Macaque, Rat, Mouse, etc.
region + DerivedFrom OPTIONAL. "XY", where X can be L:left, R:right, B:bilateral, and Y can be F:frontal, T:temporal, P:parietal, O:occipital + RECOMMENDED. Indicate what data modality the atlas was derived from, for example, "cytoarchitecture", "resting-state", "task". +
LevelType + RECOMMENDED. Indicate what analysis level the atlas was derived from, for example, "group", "individual".
-Example: -```Text -index label network_label hemisphere -1 Heschl's Gyrus Somatomotor left -2 Heschl's Gyrus Somatomotor right +#### Example: + +```JSON +{ + "Name": "HarvardOxford cort maxprob thr25 2mm", + "Authors": [ + "David Kennedy", + "Christian Haselgrove", + "Bruce Fischl", + "Janis Breeze", + "Jean Frazie", + "Larry Seidman", + "Jill Goldstein" + ], + "BIDSVersion": "1.1.0", + "Curators": "FSL team", + "License": "See LICENSE file", + "RRID": "SCR_002823", + "ReferencesAndLinks": [ + "https://doi.org/10.1016/j.neuroimage.2012.01.024", + "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Atlases" + ], + "Species": "Human" +} +``` + +### atlas-\