From 1129d8dc8e8be0a49a67e3f66ba9bcb5c68e2558 Mon Sep 17 00:00:00 2001 From: PeerHerholz Date: Thu, 25 Jan 2024 15:02:23 +0100 Subject: [PATCH] add draft for outlining desc- usage --- src/atlas.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/src/atlas.md b/src/atlas.md index 2dac83b5e5..d3203e02fb 100644 --- a/src/atlas.md +++ b/src/atlas.md @@ -10,7 +10,15 @@ Here we introduce an additional value to the `DatasetType field` of `dataset_des ## 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 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. ## 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. @@ -51,7 +59,6 @@ First, a given atlas underwent modifications before its utilization, specificall atlas-