diff --git a/mkdocs.yml b/mkdocs.yml index 82badc4288..339a3d5a57 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -24,6 +24,7 @@ nav: - Common data types and metadata: derivatives/common-data-types.md - Imaging data types: derivatives/imaging.md - Longitudinal and multi-site studies: longitudinal-and-multi-site-studies.md + - Atlases: atlas.md - Glossary: glossary.md - BIDS Extension Proposals: extensions.md - Appendix: diff --git a/src/atlas.md b/src/atlas.md index d3203e02fb..6a2297b97f 100644 --- a/src/atlas.md +++ b/src/atlas.md @@ -1,108 +1,196 @@ # 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) 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. +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, +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. +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 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, e.g. 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), e.g. [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. +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. +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, 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 +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/ +/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), 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), 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-