From 11ed800bd5c28381293d92501530c6558c565415 Mon Sep 17 00:00:00 2001 From: PeerHerholz Date: Thu, 25 Jan 2024 12:26:09 +0100 Subject: [PATCH] update wording and fix typos in atlas.md --- src/atlas.md | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/src/atlas.md b/src/atlas.md index fdce6a84df..2dac83b5e5 100644 --- a/src/atlas.md +++ b/src/atlas.md @@ -2,18 +2,18 @@ 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) 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, 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. +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) 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, 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](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. +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 (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-](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`) +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 -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. +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 @@ -23,7 +23,7 @@ The first option refers to atlases that were not altered, e.g. via spatial trans /atlas/ ``` -using the BIDS validator. Importantly, only this case uses the [atlas](schema/objects/entities.yaml#atlas) identifier, following the same directory structure as [atlas](schema/objects/entities.yaml#sub), i.e., one dedicated directory for each atlas within a given dataset. +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), i.e., 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 @@ -34,7 +34,8 @@ The default way of storage of the non-altered atlas at the root directory looks ``` ### Representing an atlas within a dataset -Besides this default and required storage of the non-altered atlas at the root directory, the second use case provides three cases to store atlases that were either altered, applied, or derived within a given dataset. While case 1 uses the [atlas](schema/objects/entities.yaml#atlas) identifier, case 2 and 3 use the [seg](schema/objects/entities.yaml#seg) identifier. The difference between the use of [atlas](schema/objects/entities.yaml#atlas) and [seg](schema/objects/entities.yaml#seg) identifier is that in the first case an existing atlas is changed, e.g. transformed, but still remains an atlas. In the other case, the atlas is used to define a segmentation, e.g. the AAL atlas is used to define a cortical parcellation, that then is applied to a subjects other content, e.g. a cortical thickness or bindign poentatial map. + +Besides this default and required storage of the non-altered atlas at the root directory, the second use case provides three sub-cases to store atlases that were either altered, applied, or derived within a given dataset. While case 1 uses the [atlas](schema/objects/entities.yaml#atlas) identifier, case 2 and 3 use the [seg](schema/objects/entities.yaml#seg) identifier. The difference between the use of [atlas](schema/objects/entities.yaml#atlas) and [seg](schema/objects/entities.yaml#seg) identifier is that in the first case an existing atlas is changed, e.g. transformed, but still remains an atlas. In the other case, the atlas is used to define a segmentation, e.g. the AAL atlas is used to define a cortical parcellation, that then is applied to a subjects other content, e.g. a cortical thickness or binding potential map. #### Case 1 @@ -55,7 +56,7 @@ First, a given atlas underwent modifications before its utilization, specificall #### Case 2 -Second, a given atlas underwent modifications before its utilization, specifically spatial transformations to an individual subject space and is used in this form. In this case, the respective BIDS-Atlas files will be stored at both the BIDS root level and at the given subject level under `derivatives`. Files stored at the BIDS root level will follow the structure outlined in option 1. Files stored at the subject level now use the [seg](schema/objects/entities.yaml#seg) entity with it's value refering to the atlas use on a given file. +Second, a given atlas underwent modifications before its utilization, specifically spatial transformations to an individual subject space and is used in this form. In this case, the respective BIDS-Atlas files will be stored at both the BIDS root level and at the given subject level under `derivatives`. Files stored at the BIDS root level will follow the structure outlined in option 1. Files stored at the subject level now use the [seg](schema/objects/entities.yaml#seg) entity with it's value referring to the atlas use on a given file. ```Text /atlas/atlas-