diff --git a/src/atlas.md b/src/atlas.md index 3cc712823c..2fa10e6fd6 100644 --- a/src/atlas.md +++ b/src/atlas.md @@ -1,62 +1,94 @@ # 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. + +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, 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) [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, 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 e.g. 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", 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 and enabling their integration as sub-datasets of other BIDS datasets. +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 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 (e.g. 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- is currently discouraged in order to keep this identifier available for necessary cases. Phrased differently, instead of using the _desc- identifier to refer to a specific version of a given atlas (e.g. atlas-Schaefer_res-2_desc-400.nii.gz), the respective information should be captured in the atlas- identifier (e.g. atlas-Schaefer400_res-2.nii.gz) and the _desc- used for e.g. referring to subsets of a given atlas (e.g. atlas-Schaefer400_res-2_desc-label01_mask.nii.gz). Common identifiers (e.g., hemi) currently exist and should not be used in lieu of the _desc- identifier, whereas information pertaining to the probabilistic nature of an atlas threshold is appropriate for the _desc- identifier (e.g. atlas-HarvardOxford_res-2_desc-th25_probseg.nii.gz) +The usage of [_desc-](schema/objects/entities.yaml#desc) is currently discouraged in order to keep this identifier available for necessary cases. Phrased differently, instead of using the [_desc-](schema/objects/entities.yaml#desc) identifier to refer to a specific version of a given atlas (e.g. `atlas-Schaefer_res-2_desc-400.nii.gz`), the respective information should be captured in the atlas- identifier (e.g. `atlas-Schaefer400_res-2.nii.gz`) and the [_desc-](schema/objects/entities.yaml#desc) used for e.g. referring to subsets of a given atlas (e.g. `atlas-Schaefer400_res-2_desc-label01_mask.nii.gz`). Common identifiers (e.g., [hemi](schema/objects/entities.yaml#hemi) currently exist and should not be used in lieu of the [_desc-](schema/objects/entities.yaml#desc) identifier, whereas information pertaining to the probabilistic nature of an atlas threshold is appropriate for the [_desc-](schema/objects/entities.yaml#desc) identifier (e.g. `atlas-HarvardOxford_res-2_desc-th25_probseg.nii.gz`) ## Directory Structure -Importantly, 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) or within the directory of a given subject’s derivatives. Given the manifold use cases of atlases, the files mentioned above are utilized in BIDS-Atlas in two general ways: non-altered/original required at BIDS root and altered/derived/applied atlases stored under derivatives. The first option refers to atlases that were not altered, e.g. 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 (i.e., the tool used), they are always shared at the root folder and everything else is under derivatives. This allows validating any /atlas/ using the BIDS validator. Importantly, only this case uses the “atlas-” identifier, following the same directory structure as “sub”, i.e., one dedicated directory for each atlas within a given dataset. +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. In the second case, they are stored within the directory of a given subject’s derivatives representing the altered/derived/applied atlases. + +### Representing the atlas at the dataset level + +The first option refers to atlases that were not altered, e.g. 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 (i.e., the tool used), they are always shared at the root folder and everything else is under derivatives. This allows validating any + +```Text +/atlas/ +``` -Representing the atlas at the dataset level, -/atlases/atlas-