update wording and fix typos in atlas.md

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
 <dataset>/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
 <dataset>/atlas/atlas-<label>/
@@ -73,7 +74,7 @@ Second, a given atlas underwent modifications before its utilization, specifical
 
 #### Case 3
 
-Third, a given atlas was derived from the corresponding subject’s data and thus is subject-specific. In this case, the `atlas` directory at the root of the dataset does not exist. The subject specific atlas filenames are the same as in case 2 at the subject level within the modality directory of the data the atlas was derived from. Optionally, a `*_coordsystem.json` file that specifies the [Image-based Coordinate System](/appendices/coordinate-systems.md) of the suject-specific atlas can be used for e.g. an histological atlas/segnmentation. Unlike As in the prior use case, the [atlas](schema/objects/entities.yaml#atlas) identifier will be replaced with the [seg](schema/objects/entities.yaml#seg) identifier.
+Third, a given atlas was derived from the corresponding subject’s data and thus is subject-specific. In this case, the `atlas` directory at the root of the dataset does not exist. The subject specific atlas filenames are the same as in case 2 at the subject level within the modality directory of the data the atlas was derived from. Optionally, a `*_coordsystem.json` file that specifies the [Image-based Coordinate System](/appendices/coordinate-systems.md) of the subject-specific atlas can be used for e.g. an histological atlas/segmentation. Unlike as in the prior use case, the [atlas](schema/objects/entities.yaml#atlas) identifier will be replaced with the [seg](schema/objects/entities.yaml#seg) identifier.
 
 ```Text
 <dataset>/derivatives/
@@ -83,7 +84,7 @@ Third, a given atlas was derived from the corresponding subject’s data and thu
 			sub-01_atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv
 			sub-01_atlas-<label>_desc-<label>_[dseg|probseg|mask].json
 			sub-01_atlas-<label>_desc-<label>_coordsystem.json
-
+```
 
 ### Representing locations in an atlas file
 
@@ -105,7 +106,7 @@ atlas-HarvardOxford_res-2_desc-HeschlGyrus_mask.nii.gz
 
 General Recommendations: This specification relies on the inheritance principle whereby files deeper in the hierarchy inherit from the top-level files. If you have atlas files that are transformed to subject-specific space for each subject, then excluding the space entity at the top level is a good way to ensure the file inherits information about the original atlas. Additionally, the [desc](schema/objects/entities.yaml#desc) label should be avoided as an inherited file. One may need to use the [desc](schema/objects/entities.yaml#desc) label to contain information related or unrelated to the atlas.
 
- The `[probseg|dseg|mask|channels].tsv` file indexes and labels each node/parcel/region within the atlas. This file resembles the typical Look Up Table (LUT) often shared with atlases. This file will be essential for downstream workflows that generate matrices, as the index/label fields will be used to reference the original anatomy the index/labels are derived from. Additional fields can be added with their respective definition/description in the sidecar json file.
+The `[probseg|dseg|mask|channels].tsv` file indexes and labels each node/parcel/region within the atlas. This file resembles the typical Look Up Table (LUT) often shared with atlases. This file will be essential for downstream workflows that generate matrices or other derived files within which node/parcel/region information is required, as the index/label fields will be used to reference the original anatomy the index/labels are derived from. Additional fields can be added with their respective definition/description in the sidecar json file.
 
 <table>
   <tr>
@@ -133,7 +134,7 @@ General Recommendations: This specification relies on the inheritance principle
    </td>
   </tr>
   <tr>
-   <td>CoordinateReportStrategy
+   <td>coordinate_report_strategy
    </td>
    <td>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”. 
    </td>
@@ -318,12 +319,12 @@ Example:
 # BIDS-Atlas Example datasets
 Within the following, multiple examples showcasing the proposed extension are provided. They include BEP-specific as well as other/general BIDS files.
 
-## Single existing atlas in template space
+## Atlas as dataset - single existing atlas in template space
 
-The example below illustrates how a single existing atlas in template space is represented according to the atlas BEP. Specifically, the example refers to the Harvard-Oxford atlas in MN152NLin6Asym space with a resolution of 2 mm3, used without modifications (e.g. transformations, subsetting, etc.) for all subjects to which the pipeline was applied.  
+The example below illustrates how a single existing atlas in template space is represented as a dataset according to the atlas BEP. Specifically, the example refers to the Harvard-Oxford atlas in MN152NLin6Asym space with a resolution of 2 mm3, used without modifications (e.g. transformations, subsetting, etc.) for all subjects to which the pipeline was applied.  
 
 ```Text
-my_dataset/atlases/atlas-HarvardOxford/
+my_dataset/atlas-HarvardOxford/
 	atlas-HarvardOxford_res-2_dseg.json
 	atlas-HarvardOxford_res-2_dseg.nii.gz
 	atlas-HarvardOxford_res-2_dseg.tsv