From 9878702714ec3399571e663e8a3b63931f98af25 Mon Sep 17 00:00:00 2001
From: melanieganz <melanie.ganz@gmail.com>
Date: Tue, 23 Jan 2024 09:23:00 +0100
Subject: [PATCH 01/16] First draft of the atlas spec

I made a first draft of the atlas BEP based on the Google doc
---
 src/atlas.md | 102 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 102 insertions(+)
 create mode 100644 src/atlas.md

diff --git a/src/atlas.md b/src/atlas.md
new file mode 100644
index 0000000000..bf9cb92eec
--- /dev/null
+++ b/src/atlas.md
@@ -0,0 +1,102 @@
+# Longitudinal and multi-site studies
+
+Multiple sessions (visits) are encoded by adding an extra layer of directories
+and [filenames](common-principles.md#filenames)
+in the form of a session (for example `ses-<label>`) and
+with a [`*_sessions.tsv` file](modality-agnostic-files.md#sessions-file).
+
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example(
+    {
+    "sub-control01": {
+        "ses-predrug": {
+            "anat": {
+                "sub-control01_ses-predrug_T1w.nii.gz": "",
+                "sub-control01_ses-predrug_T1w.json": "",
+                "sub-control01_ses-predrug_T2w.nii.gz": "",
+                "sub-control01_ses-predrug_T2w.json": "",
+                },
+            "func": {
+                "sub-control01_ses-predrug_task-nback_bold.nii.gz": "",
+                "sub-control01_ses-predrug_task-nback_bold.json": "",
+                "sub-control01_ses-predrug_task-nback_events.tsv": "",
+                "sub-control01_ses-predrug_task-nback_physio.tsv.gz": "",
+                "sub-control01_ses-predrug_task-nback_physio.json": "",
+                "sub-control01_ses-predrug_task-nback_sbref.nii.gz": "",
+                },
+            "dwi": {
+                "sub-control01_ses-predrug_dwi.nii.gz": "",
+                "sub-control01_ses-predrug_dwi.bval": "",
+                "sub-control01_ses-predrug_dwi.bvec": "",
+                },
+            "fmap": {
+                "sub-control01_ses-predrug_phasediff.nii.gz": "",
+                "sub-control01_ses-predrug_phasediff.json": "",
+                "sub-control01_ses-predrug_magnitude1.nii.gz": "",
+                },
+            "sub-control01_ses-predrug_scans.tsv": "",
+            },
+        "ses-postdrug": {
+            "func": {
+                "sub-control01_ses-postdrug_task-nback_bold.nii.gz": "",
+                "sub-control01_ses-postdrug_task-nback_bold.json": "",
+                "sub-control01_ses-postdrug_task-nback_events.tsv": "",
+                "sub-control01_ses-postdrug_task-nback_physio.tsv.gz": "",
+                "sub-control01_ses-postdrug_task-nback_physio.json": "",
+                "sub-control01_ses-postdrug_task-nback_sbref.nii.gz": "",
+                },
+            "fmap": {
+                "sub-control01_ses-postdrug_phasediff.nii.gz": "",
+                "sub-control01_ses-postdrug_phasediff.json": "",
+                "sub-control01_ses-postdrug_magnitude1.nii.gz": "",
+                }
+            },
+        "sub-control01_sessions.tsv": "",
+        },
+    "participants.tsv": "",
+    "dataset_description.json": "",
+    "README": "",
+    "CHANGES": "",
+    }
+) }}
+
+`sub-control01_sessions.tsv` content:
+
+```Text
+session_id	acq_time	systolic_blood_pressure
+ses-predrug	2009-06-15T13:45:30	120
+ses-postdrug	2009-06-16T13:45:30	100
+```
+
+See this [example dataset](https://github.com/bids-standard/bids-examples/tree/master/7t_trt)
+that has been formatted
+using this specification and can be used
+for practical guidance when curating a new longitudinal dataset.
+
+## Multi-site or multi-center studies
+
+This version of the BIDS specification does not explicitly cover studies with
+data coming from multiple sites or multiple centers (such extension is planned
+in [BIDS `2.0`](https://github.com/bids-standard/bids-2-devel).
+There are however ways to model your data without any loss in terms of metadata.
+
+### Option 1: Treat each site/center as a separate dataset
+
+The simplest way of dealing with multiple sites is to treat data from each site
+as a separate and independent BIDS dataset with a separate participants.tsv and
+other metadata files. This way you can feed each dataset individually to BIDS
+Apps and everything should just work.
+
+### Option 2: Combining sites/centers into one dataset
+
+Alternatively you can combine data from all sites into one dataset. To identify
+which site each subjects comes from you can add a `site` column in the
+`participants.tsv` file indicating the source site. This solution allows you to
+analyze all of the subjects together in one dataset. One caveat is that subjects
+from all sites will have to have unique labels. To enforce that and improve
+readability you can use a subject label prefix identifying the site. For example
+`sub-NUY001`, `sub-MIT002`, `sub-MPG002` and so on. Remember that hyphens and
+underscores are not allowed in subject labels.

From 8304769786039b1682fb3bbf40d6a5a81508fde6 Mon Sep 17 00:00:00 2001
From: melanieganz <melanie.ganz@gmail.com>
Date: Tue, 23 Jan 2024 09:26:38 +0100
Subject: [PATCH 02/16] Added proper content

Added atlas content
---
 src/atlas.md | 496 ++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 394 insertions(+), 102 deletions(-)

diff --git a/src/atlas.md b/src/atlas.md
index bf9cb92eec..3cc712823c 100644
--- a/src/atlas.md
+++ b/src/atlas.md
@@ -1,102 +1,394 @@
-# Longitudinal and multi-site studies
-
-Multiple sessions (visits) are encoded by adding an extra layer of directories
-and [filenames](common-principles.md#filenames)
-in the form of a session (for example `ses-<label>`) and
-with a [`*_sessions.tsv` file](modality-agnostic-files.md#sessions-file).
-
-<!-- This block generates a file tree.
-A guide for using macros can be found at
- https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
--->
-{{ MACROS___make_filetree_example(
-    {
-    "sub-control01": {
-        "ses-predrug": {
-            "anat": {
-                "sub-control01_ses-predrug_T1w.nii.gz": "",
-                "sub-control01_ses-predrug_T1w.json": "",
-                "sub-control01_ses-predrug_T2w.nii.gz": "",
-                "sub-control01_ses-predrug_T2w.json": "",
-                },
-            "func": {
-                "sub-control01_ses-predrug_task-nback_bold.nii.gz": "",
-                "sub-control01_ses-predrug_task-nback_bold.json": "",
-                "sub-control01_ses-predrug_task-nback_events.tsv": "",
-                "sub-control01_ses-predrug_task-nback_physio.tsv.gz": "",
-                "sub-control01_ses-predrug_task-nback_physio.json": "",
-                "sub-control01_ses-predrug_task-nback_sbref.nii.gz": "",
-                },
-            "dwi": {
-                "sub-control01_ses-predrug_dwi.nii.gz": "",
-                "sub-control01_ses-predrug_dwi.bval": "",
-                "sub-control01_ses-predrug_dwi.bvec": "",
-                },
-            "fmap": {
-                "sub-control01_ses-predrug_phasediff.nii.gz": "",
-                "sub-control01_ses-predrug_phasediff.json": "",
-                "sub-control01_ses-predrug_magnitude1.nii.gz": "",
-                },
-            "sub-control01_ses-predrug_scans.tsv": "",
-            },
-        "ses-postdrug": {
-            "func": {
-                "sub-control01_ses-postdrug_task-nback_bold.nii.gz": "",
-                "sub-control01_ses-postdrug_task-nback_bold.json": "",
-                "sub-control01_ses-postdrug_task-nback_events.tsv": "",
-                "sub-control01_ses-postdrug_task-nback_physio.tsv.gz": "",
-                "sub-control01_ses-postdrug_task-nback_physio.json": "",
-                "sub-control01_ses-postdrug_task-nback_sbref.nii.gz": "",
-                },
-            "fmap": {
-                "sub-control01_ses-postdrug_phasediff.nii.gz": "",
-                "sub-control01_ses-postdrug_phasediff.json": "",
-                "sub-control01_ses-postdrug_magnitude1.nii.gz": "",
-                }
-            },
-        "sub-control01_sessions.tsv": "",
-        },
-    "participants.tsv": "",
-    "dataset_description.json": "",
-    "README": "",
-    "CHANGES": "",
-    }
-) }}
-
-`sub-control01_sessions.tsv` content:
-
-```Text
-session_id	acq_time	systolic_blood_pressure
-ses-predrug	2009-06-15T13:45:30	120
-ses-postdrug	2009-06-16T13:45:30	100
-```
-
-See this [example dataset](https://github.com/bids-standard/bids-examples/tree/master/7t_trt)
-that has been formatted
-using this specification and can be used
-for practical guidance when curating a new longitudinal dataset.
-
-## Multi-site or multi-center studies
-
-This version of the BIDS specification does not explicitly cover studies with
-data coming from multiple sites or multiple centers (such extension is planned
-in [BIDS `2.0`](https://github.com/bids-standard/bids-2-devel).
-There are however ways to model your data without any loss in terms of metadata.
-
-### Option 1: Treat each site/center as a separate dataset
-
-The simplest way of dealing with multiple sites is to treat data from each site
-as a separate and independent BIDS dataset with a separate participants.tsv and
-other metadata files. This way you can feed each dataset individually to BIDS
-Apps and everything should just work.
-
-### Option 2: Combining sites/centers into one dataset
-
-Alternatively you can combine data from all sites into one dataset. To identify
-which site each subjects comes from you can add a `site` column in the
-`participants.tsv` file indicating the source site. This solution allows you to
-analyze all of the subjects together in one dataset. One caveat is that subjects
-from all sites will have to have unique labels. To enforce that and improve
-readability you can use a subject label prefix identifying the site. For example
-`sub-NUY001`, `sub-MIT002`, `sub-MPG002` and so on. Remember that hyphens and
-underscores are not allowed in subject labels.
+# BIDS-Atlas
+
+## 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.
+
+## 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)
+
+## 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  <dataset>/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. 
+
+Representing the atlas at the dataset level, 
+<dataset>/atlases/atlas-<label>/
+atlas-<label>_space-<label>[_desc-<label>]_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii][.gz]
+atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].tsv
+atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].json
+
+Besides this default and required storage of the non-altered atlas at the root directory, the second use case provides three options to store atlases that were either altered, applied, or derived within a given dataset. While option 1 also uses the “atlas” identifier, options 2 and 3 use the “seg” identifier, as outlined in the next paragraphs.
+
+First: a given atlas underwent modifications before its utilization, specifically spatial transformations to a template space and is used in this form within a given pipeline. In this case, the respective BIDS-Atlas files will be stored at both the BIDS root level and the given pipeline directory under “derivatives”. Files stored at the BIDS root level will follow the structure outlined in option 1, while files stored at the pipeline level will follow the respective naming conventions. For example, if an atlas was spatially transformed to a certain MNI template, then the BIDS-Atlas files will be stored within the respective pipeline directory and the corresponding space-<label> identifier will be adapted accordingly. 
+
+<dataset>/atlases/atlas-<label>/
+atlas-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii][.gz]
+atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv
+atlas-<label>_desc-<label>_[dseg|probseg|mask].json
+<dataset>/derivatives/<pipeline>/
+atlas-<label>_space-<label>_res-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|.tsv][.gz]
+atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].tsv
+atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].json
+atlas-<label>_space-<label>_desc-<label>_edges.[tck|<eeg,meg>]
+
+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 within the pipeline directory under “derivatives”. Files stored at the BIDS root level will follow the structure outlined in option 1, while files stored at the subject level will be placed within the modality directory of the space the atlas was spatially transformed to and follow the subject-related naming conventions. For example, if an atlas was spatially transformed to the anatomical space of a given subject, then the BIDS-Atlas files will be stored within the respective subject’s anat directory and their file names will be prepended with the subject identifier. Additionally, instead of “atlas”, the “seg” identifier will be used to support a broader scope and more data modalities.  
+
+<dataset>/atlases/atlas-<label>/
+atlas-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii][.gz]
+atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv
+atlas-<label>_desc-<label>_[dseg|probseg|mask].json
+<dataset>/derivatives/<pipeline>/
+	anat/		sub-01_space-<label>_seg-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz]
+sub-01_space-<label>_seg-<label>_desc-<label>_[dseg|probseg|mask].tsv
+sub-01_space-<label>_seg-<label>_desc-<label>_[dseg|probseg|mask].json
+sub-01_space-<label>_seg-<label>_desc-<label>_edges.[tck|<eeg,meg>]
+
+
+Third: a given atlas was derived from the corresponding subject’s data and thus is subject-specific. In this case, the respective BIDS-Atlas files are only stored at the subject level within the modality directory of the data the atlas was derived from. If a subject-specific atlas was spatially transformed from the space of the modality it was derived into the space of a different modality, then the BIDS-Atlas files would be stored in both respective modality directories. For example, if an atlas was derived from data in anat and shared/utilized as is, then the BIDS-Atlas files would only be stored in the anat directory. If the atlas was spatially transformed to the functional space of the respective subject, then the BIDS-Atlas files would be stored in both directories, anat and func. As in the prior use case, the “atlas” identifier will be replaced with “seg”.   
+
+<dataset>/derivatives/<pipeline_name>/
+sub-01/
+	anat/		sub-01_space-<label>_seg_<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz]
+sub-01_space-<label>_seg-<label>_desc-<label>_[dseg|probseg|mask].tsv
+sub-01_space-<label>_seg-<label>_desc-<label>_[dseg|probseg|mask].json
+sub-01_space-<label>_seg-<label>_desc-<label>_edges.[tck|<eeg,meg>]
+
+ 
+### [probseg|dseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tracts.trx/tck/trk][.gz]
+
+This file represents the location and extent of the nodes/parcels/regions within the atlas. Different file types are supported based on the modality and atlas at hand. In more detail, this encompasses the following three options:
+
+1.	_dseg: Each node is labeled with a unique integer corresponding to its row/index in the tsv sidecar.
+2.	_probseg: Each node is represented along an additional dimension of the file (e.g., a 4D nifti file where each volume represents a node) and its position in that dimension corresponds to its row/index in the tsv sidecar.
+3.	_mask: Either each voxel represents a node or the entire mask is a single node. How the mask should be interpreted is determined by other specifications. Based on these options, an atlas can take the following forms in the here proposed specification (non-exhaustive list):
+a.	A 3D nifti file with unique integers defining nodes
+b.	A 4D binary nifti file with spatially overlapping nodes in each volume (along the 4th dimension)
+c.	A 4D nifti file with overlapping nodes with continuous values for each voxel within a volume
+
+Examples
+atlas-HarvardOxford_res-2_dseg.nii.gz
+atlas-HarvardOxford_res-2_probseg.nii.gz
+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” label should be avoided as an inherited file may need to use the desc label to contain information related or unrelated to the atlas.
+
+ 
+### [probseg|dseg|mask|channels].tsv
+
+This 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.
+
+index (or placeholder in fragment in reference)	REQUIRED. (Integer) The number associated with the node/parcel/region (right/left hemispheres may be different).
+label	RECOMMENDED. The node name
+network_id	OPTIONAL. Network ID the node/parcel belongs to
+network_label
+	OPTIONAL. Label of Network (e.g. Dorsal Attention Network)
+
+CoordinateReportStrategy	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”. 
+x	OPTIONAL. The x-coordinate of the node in the spatial reference space (See SpatialReference in the .json file)
+y	OPTIONAL. The y-coordinate of the node in the spatial reference space (See SpatialReference in the .json file)
+z	OPTIONAL. The z-coordinate of the node in the spatial reference space (See SpatialReference in the .json file)
+hemisphere	OPTIONAL. MUST BE ONE OF: “left”, “right”, “bilateral”. Indicate whether the node/parcel/region is in the left or right hemispheres, or is available bilaterally.
+color
+OPTIONAL. RGB color to use for the node.
+seed
+OPTIONAL. Seed vertex/channel of the node/region
+region
+OPTIONAL. “XY”, where X can be L:left, R:right, B:bilateral, and Y can be F:frontal, T:temporal, P:parietal, O:occipital
+
+
+
+
+
+
+Example
+
+index	label	network_label	hemisphere	…
+1	Heschl’ Gyrus	Somatomotor	left	…
+2	Heschl’ Gyrus	Somatomotor	right	…
+…	…	…	…	…
+
+### [probseg|dseg|mask].json
+
+This file provides metadata to uniquely identify, describe and characterize the atlas, as well as give proper attribution to the creators. Additionally, SpatialReference serves the important purpose of unambiguously identifying the space the atlas is labeled in.
+
+
+Name	REQUIRED. Name of the atlas
+Description	RECOMMENDED. Longform description of the atlas
+SpatialReference	RECOMMENDED. Point to an existing atlas in a template space (url or relative file path where this file is located).
+CoordinateReportStrategy	OPTIONAL. MUST BE ONE OF: “peak”, “center_of_mass”, “other”. Indicate the method of coordinate reporting in statistically significant clusters. Could be the “peak” statistical coordinate in the cluster or the “center_of_mass” of the cluster. RECOMMENDED if x, y ,z values are set in the .tsv file. 
+Authors	RECOMMENDED. List of the authors involved in the creation of the atlas
+Curators	RECOMMENDED. List of curators who helped make the atlas accessible in a database or dataset
+Funding	RECOMMENDED. The funding source(s) involved in the atlas creation
+License	RECOMMENDED. The license agreement for using the atlas.
+ReferencesAndLinks	RECOMMENDED. A list of relevant references and links pertaining to the atlas.
+Species	RECOMMENDED. The species the atlas was derived from. For example, could be Human, Macaque, Rat, Mouse, etc.
+DerivedFrom	RECOMMENDED. Indicate what data modality the atlas was derived from, e.g. "cytoarchitecture", "resting-state", "task".
+LevelType	RECOMMENDED. Indicate what analysis level the atlas was derived from, e.g. "group", "individual".
+Additional Columns	RECOMMENDED. Describe the respective column in the tsv
+
+
+
+
+
+
+
+Example 
+
+{
+  	"Name": "FSL's MNI ICBM 152 non-linear 6th Generation Asymmetric Average 
+   Brain Stereotaxic Registration Model",
+ 	"Authors": [
+ “David Kennedy”,
+ “Christian Haselgrove”,
+ “Bruce Fischl”,
+ “Janis Breeze”,
+ “Jean Frazie”, 
+ “Larry Seidman”,
+ “Jill Goldstein”
+ 		],
+ 	"BIDSVersion": "1.1.0",
+ 	"Curators": "FSL team",
+“SpatialReference”:   
+“https://templateflow.s3.amazonaws.com/tpl-MNI152NLin6Asym_res-02_T1w.nii.gz”,
+ 	"Space": "MNI152NLin6Asym",
+“Resolution”: “Matched with original template resolution (2x2x3 mm^3)”, 
+ 	"License": "See LICENSE file",
+"RRID": "SCR_002823",
+  	"ReferencesAndLinks": [
+  "https://doi.org/10.1016/j.neuroimage.2012.01.024",
+  "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Atlases”
+     ],
+  	"Species": "Human"
+}
+
+
+
+
+
+
+
+ 
+# 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
+
+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.  
+
+my_dataset/atlases/atlas-HarvardOxford/
+	atlas-HarvardOxford_res-2_dseg.json
+	atlas-HarvardOxford_res-2_dseg.nii.gz
+	atlas-HarvardOxford_res-2_dseg.tsv
+
+The content of each file is further outlined in the following, starting with the .json sidecar file containing meta-data about the atlas at hand.
+
+atlas-HarvardOxford_res-2_dseg.json
+
+{
+ 	"Authors": [
+ “David Kennedy”,
+ “Christian Haselgrove”,
+ “Bruce Fischl”,
+ “Janis Breeze”,
+ “Jean Frazie”, 
+ “Larry Seidman”,
+ “Jill Goldstein”
+ 		],
+ 	"BIDSVersion": "1.1.0",
+ 	"Curators": "FSL team",
+“SpatialReference”:   
+“https://templateflow.s3.amazonaws.com/tpl-MNI152NLin6Asym_res-02_T1w.nii.gz”,
+ 	"Space": "MNI152NLin6Asym",
+“Resolution”: “Matched with original template resolution (2x2x3 mm^3)”, 
+ 	"License": "See LICENSE file",
+  	"Name": "FSL's MNI ICBM 152 non-linear 6th Generation Asymmetric Average 
+   Brain Stereotaxic Registration Model",
+"RRID": "SCR_002823",
+  	"ReferencesAndLinks": [
+  "https://doi.org/10.1016/j.neuroimage.2012.01.024",
+  "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Atlases”
+     ],
+  	"Species": "Human"
+}
+
+Next, the content of the tsv files describing the indices and corresponding labels present in the atlas at hand. 
+
+atlas-HarvardOxford_res-2_dseg.tsv
+
+index	label	hemisphere
+0	Background	bilateral
+1	Frontal Pole	bilateral
+2
+Insular Cortex	bilateral
+3	Superior Frontal Gyrus	bilateral
+4	Middle Frontal Gyrus	bilateral
+5	Inferior Frontal Gyrus, pars triangularis	bilateral
+6	Inferior Frontal Gyrus, pars opercularis	bilateral
+…		
+
+
+
+ 
+## Multiple existing atlases in template space
+The example below illustrates how multiple existing atlases in the same template space are represented according to the atlas BEP. Specifically, the example refers to the Harvard-Oxford, Schaefer, Yeo and MSDL atlases, all in MN152NLin6Asym space and with a resolution of 2 mm3, were utilized without modifications (e.g. transformations, subsetting, etc.) for all subjects to which the pipeline was applied. Importantly, all atlas-related information is indicated via the value of the atlas- key and not via desc- to help prevent inheritance problems in subsequent steps. Here, this was used to indicate that the Harvard-Oxford atlas in its version with a maximum probability of 50, the Schaefer atlas in its 400 parcel version and the Yeo atlas in its 17 networks version were used. The respective information found in each file follows the example outlined in 4.1 as atlases were used independently from one another.
+
+bids/atlases/
+atlas-HarvardOxford/
+		atlas-HarvardOxford_dseg.nii.gz
+	atlas-HarvardOxford_dseg.json
+		atlas-HarvardOxford_dseg.tsv
+atlas-Schaefer400/
+atlas-Schaefer400_dseg.nii.gz
+atlas-Schaefer400_dseg.json
+atlas-Schaefer400_dseg.tsv
+atlas-Yeo17/
+atlas-Yeo17_dseg.nii.gz
+atlas-Yeo17_dseg.json
+atlas-Yeo17_dseg.tsv
+atlas-msdl/
+atlas-msdl_probseg.nii.gz
+atlas-msdl_probseg.json
+atlas-msdl_probseg.tsv
+
+
+
+ 
+## Single existing atlas transformed to subject space
+The example below illustrates how a single existing atlas transformed into a subject’s native space space is represented according to the atlas BEP. Specifically, the example refers to the Harvard-Oxford atlas with a resolution of 2 mm3 that was transformed from the MN152NLin6Asym template space to a given subject’s native T1w space. While the original atlas-related files remain as outlined in the use case in template space, the spatially transformed version of the nii.gz atlas file will be placed within a given subjects directory. The precise location within the latter depends on the modality space to which the atlas was transformed to, e.g. anat, func or dwi. The same location furthermore entails a corresponding json file outlining further information on the source atlas and applied transformation(s).
+
+
+bids/atlases/atlas-HarvardOxford/
+	atlas-HarvardOxford_dseg.json
+atlas-HarvardOxford_dseg.tsv
+	atlas-HavardOxford2_dseg.nii.gz
+bids/derivatives/pipeline-<name>/
+	sub-01/
+anat/
+  sub-01_T1w.nii.gz
+		  sub-01_space-T1w_seg-HarvardOxfordThr50_res-2_dseg.nii.gz	
+  sub-01_space-T1w_seg-HarvardOxfordThr50_res-2_dseg.json
+  sub-01_space-T1w_seg-HarvardOxfordThr50_res-2_dseg.tsv
+
+
+The json file accompanying the transformed atlas should include the following information.
+
+sub-01_space-T1w_seg-HarvardOxford_res-2_dseg.json
+
+{
+ 	"BIDSVersion": "1.1.0",
+“SpatialReference”: “sub-01/anat/sub-01_T1w.nii.gz”,
+ 	"Space": "T1w",
+“Resolution”: “Matched with original resolution in subject T1w space 
+  (1x1x1 mm^3)”, 
+	“Sources”: [],
+“transformation”:
+}
+
+
+##  MyConnectome example
+
+The example below illustrates how two atlases, an individual surface-based cortical parcellation in FS_lr space (called Russome), and the subcortical regions from a volumetric segmentation provided by the FreeSurfer aseg, are represented according to the atlas BEP. While the FreeSurfer atlas-related files have two instances, one as outlined in the use case in template space and one as outlined in the use case covering subject spaces, the individual parcellation in FS_lr space will be placed only within a given subjects directory. The same location furthermore entails a corresponding json file outlining further information on the atlas and applied analysis to obtain it.
+
+bids/atlases/atlas-FreeSurferASEG/
+	atlas-FreeSurferASEG_dseg.json
+	atlas-FreeSurferASEG_dseg.tsv
+	atlas-FreeSurferASEG_dseg.nii.gz
+bids/derivatives/pipeline-<name>/
+	sub-01/
+anat/
+		  sub-01_space-T1w_seg-FreeSurferASEG_res-2_dseg.nii.gz	
+  sub-01_space-T1w_seg-FreeSurferASEG_res-2_dseg.json
+  sub-01_space-T1w_seg-FreeSurferASEG_res-2_dseg.tsv
+func/
+ 		  sub-01_space-FSlr_seg-Russome_res-2_dseg.nii.gz	
+  sub-01_space-FSlr_seg-Russome_res-2_dseg.json
+  sub-01_space-FSlr_seg-Russome_res-2_dseg.tsv
+
+
+The json file accompanying the functionally derived atlas should include the following information.
+
+sub-01_task-rest_atlas.json: contains top-level metadata about atlas
+
+{
+  "Atlas": {
+    "Russome": {
+“Atlasfile”: “/link/to/russome/file”, 
+“Extra”: “individualized surface parcellation”
+},
+    “FS_aseg”: {
+“Atlasfile”: “/link/to/aseg/file”, 
+“Extra”: “freesurfer aseg”
+}
+}
+
+## Atlas utilization in electrophysiology data
+
+Some atlases in development include the Open MNI iEEG Atlas (https://mni-open-ieegatlas.research.mcgill.ca/) led by Birgit Frauscher and Jean Gotman of at McGill University with technical implementation led by Alan Evans’ group led by Christine Rogers [citation].  106 subjects’s signal data from 17__ channels in non-epileptogenic areas of (“normal”) tissue was mapped to a MICCAI 2012 standardized atlas template [citation]. 
+-> what would an atlas directory look like given the data is coming from multi-subjects? (example 4.7 quantitative atlas example) 
+-> Is BIDS coverage currently sufficient to describe this, what more metadata would be helpful, e.g. reference space.  (spatial reference is defined in 4.4 json sidecar)
+-> what they can be used for.  Looks like eeg but x y z can’t be run without abc 
+
+
+Additional intracranial EEG atlas development is in progress across 10 sites in 6 countries.   
+Co-registration on MRI templates is performed with …. 
+
+Example might look something like this, just to verify that the above could be extended with a timeseries file in which the ‘channels’ correspond to the _dseg.tsv, and the json file might need an indicator that there is a time series file. This example is only here to decide whether this is out of scope, can be removed.
+bids/atlases/atlas-FreeSurferASEG/
+	atlas-FreeSurferASEG_dseg.json
+	atlas-FreeSurferASEG_dseg.tsv
+	atlas-FreeSurferASEG_dseg.nii.gz
+atlas-FreeSurferASEG_dseg.edf
+ 
+## Quantitative atlas examples 
+
+The example below is for PET imaging, but this applies to any quantitative mapping (PET or QMRI). Compared to anatomical atlases, quantitative atlases give reference values to be compared with. Such values can be derived voxel/vertex wise or per region of interest (ROI), in the later case deriving ROIs generally from an anatomical atlas. 
+
+We created a Molecular Imaging Brain Atlases (MIBA) from 16 subjects who underwent a [11C]PS13 PET scan, a radioligand that quantifies cyclooxygenase-1 (source data: https://openneuro.org/datasets/ds004332/versions/1.0.2). Our atlas consists of mean and standard deviations of PS13 target distribution volumes (VT) computed across the 16 subjects at each voxel, in standard MRI spaces. We also project these distribution volumes onto the freesurfer cortical surfaces and include these as well.  The goal is to allow researchers with MRI-only data to correlate their results to the distribution volume of PS13. The dataset can be found at https://openneuro.org/datasets/ds004401/versions/1.1.0 (to be changed following this spec). 
+
+Case 1: voxel/vertex wise analysis
+
+Missing is the measure -- what was computed, BPND?
+
+bids/atlases/atlas-ps13/
+	  atlas-ps13_space-fsaverage_hemi-L_stat-mean_meas-VT_mimap.json
+       atlas-ps13_space-fsaverage_hemi-L_stat-mean_meas-VT_mimap.nii.gz
+       atlas-ps13_space-fsaverage_hemi-R_stat-mean_meas-VT_mimap.json
+       atlas-ps13_space-fsaverage_hemi-R_stat-mean_meas-VT_mimap.nii.gz
+	  atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_mimap.json
+       atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_mimap.nii.gz 
+       atlas-ps13_space-fsaverage_hemi-L_stat-std_meas-VT_mimap.json
+  atlas-ps13_space-fsaverage_hemi-L_stat-std_meas-VT_mimap.nii.gz
+  atlas-ps13_space-fsaverage_hemi-R_stat-std_meas-VT_mimap.json
+  atlas-ps13_space-fsaverage_hemi-R_stat-std_meas-VT_mimap.nii.gz
+
+  atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_mimap.json
+  atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_mimap.nii.gz
+
+
+ 
+Case 2: regional analysis (voxels/vertices are averaged per regions from dseg/probseg)
+
+bids/atlases/
+atlas-mni305/
+atlas-aparc.DKTatlas+aseg.mgz
+atlas-aparc.DKTatlas+aseg.tsv
+atlas-RB_all_2008-03-26.probseg.gca
+atlas-RB_all_2008-03-26.probseg.tsv
+atlas-ps13/
+	  atlas-ps13_space-fsaverage_hemi-L_stat-mean_meas-VT_mimap.json
+        atlas-ps13_space-fsaverage-hemi-L_stat-mean_meas-VT_mimap.tsv
+        atlas-ps13_space-fsaverage-hemi-L_stat-std_meas-VT_mimap.json
+       atlas-ps13_space-fsaverage-hemi-L_stat-std_meas-VT_mimap.tsv
+       atlas-ps13_space-fsaverage-hemi-R_stat-mean_meas-VT_mimap.json
+       atlas-ps13_space-fsaverage-hemi-R_stat-mean_meas-VT_mimap.tsv
+  atlas-ps13_space-fsaverage-hemi-R_stat-std_meas-VT_mimap.json
+  atlas-ps13_space-fsaverage-hemi-R_stat-std_meas-VT_mimap.tsv
+  atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_mimap.json
+  atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_mimap.tsv
+  atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_mimap.json
+  atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_mimap.tsv
+
+(note that there is no image -- we should provide instruction how to load such tsv in freesurfer for surface viewing (and save as?) in a readme and also do the same as matlab/python code for generating volumes from the tsv at the desired resolution)
+
+
+The json file accompanying the quantitative atlas should include the information as in 4.1.
\ No newline at end of file

From 01178db2b4be79d954c5e308414c0c0b4775d9a0 Mon Sep 17 00:00:00 2001
From: melanieganz <melanie.ganz@gmail.com>
Date: Tue, 23 Jan 2024 15:18:45 +0100
Subject: [PATCH 03/16] First pass of adding BEP038 content

All the content of the BEP038 Google document has been ported to the atlas.md file. Additionally atlas and a definition of what of means was added as an entity. There are still smaller things to fix as some links, references and the tables still need to be inserted.
---
 src/atlas.md                     | 389 +++++++++++++++----------------
 src/schema/objects/entities.yaml |   9 +
 2 files changed, 193 insertions(+), 205 deletions(-)

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  <dataset>/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
+<dataset>/atlas/ 
+```
 
-Representing the atlas at the dataset level, 
-<dataset>/atlases/atlas-<label>/
-atlas-<label>_space-<label>[_desc-<label>]_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii][.gz]
-atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].tsv
-atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].json
+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. 
+The default way of storage of the non-altered atlas at the root directory looks like this:
+
+```Text
+<dataset>/atlas/atlas-<label>/
+	atlas-<label>_space-<label>[_desc-<label>]_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii][.gz]
+	atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].tsv
+	atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].json
+```
+
+### Representing the atlas at the subject level
 
 Besides this default and required storage of the non-altered atlas at the root directory, the second use case provides three options to store atlases that were either altered, applied, or derived within a given dataset. While option 1 also uses the “atlas” identifier, options 2 and 3 use the “seg” identifier, as outlined in the next paragraphs.
 
-First: a given atlas underwent modifications before its utilization, specifically spatial transformations to a template space and is used in this form within a given pipeline. In this case, the respective BIDS-Atlas files will be stored at both the BIDS root level and the given pipeline directory under “derivatives”. Files stored at the BIDS root level will follow the structure outlined in option 1, while files stored at the pipeline level will follow the respective naming conventions. For example, if an atlas was spatially transformed to a certain MNI template, then the BIDS-Atlas files will be stored within the respective pipeline directory and the corresponding space-<label> identifier will be adapted accordingly. 
+#### Case 1
 
-<dataset>/atlases/atlas-<label>/
-atlas-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii][.gz]
-atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv
-atlas-<label>_desc-<label>_[dseg|probseg|mask].json
-<dataset>/derivatives/<pipeline>/
-atlas-<label>_space-<label>_res-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|.tsv][.gz]
-atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].tsv
-atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].json
-atlas-<label>_space-<label>_desc-<label>_edges.[tck|<eeg,meg>]
+First, a given atlas underwent modifications before its utilization, specifically spatial transformations to a template space and is used in this form within a given pipeline. In this case, the respective BIDS-Atlas files will be stored at both the BIDS root level and the given pipeline directory under “derivatives”. Files stored at the BIDS root level will follow the structure outlined in option 1, while files stored at the pipeline level will follow the respective naming conventions. For example, if an atlas was spatially transformed to a certain MNI template, then the BIDS-Atlas files will be stored within the respective pipeline directory and the corresponding space-<label> identifier will be adapted accordingly. 
 
-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 within the pipeline directory under “derivatives”. Files stored at the BIDS root level will follow the structure outlined in option 1, while files stored at the subject level will be placed within the modality directory of the space the atlas was spatially transformed to and follow the subject-related naming conventions. For example, if an atlas was spatially transformed to the anatomical space of a given subject, then the BIDS-Atlas files will be stored within the respective subject’s anat directory and their file names will be prepended with the subject identifier. Additionally, instead of “atlas”, the “seg” identifier will be used to support a broader scope and more data modalities.  
+```Text
+<dataset>/atlas/atlas-<label>/
+	atlas-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii][.gz]
+	atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv
+	atlas-<label>_desc-<label>_[dseg|probseg|mask].json
 
-<dataset>/atlases/atlas-<label>/
-atlas-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii][.gz]
-atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv
-atlas-<label>_desc-<label>_[dseg|probseg|mask].json
 <dataset>/derivatives/<pipeline>/
-	anat/		sub-01_space-<label>_seg-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz]
-sub-01_space-<label>_seg-<label>_desc-<label>_[dseg|probseg|mask].tsv
-sub-01_space-<label>_seg-<label>_desc-<label>_[dseg|probseg|mask].json
-sub-01_space-<label>_seg-<label>_desc-<label>_edges.[tck|<eeg,meg>]
+	atlas-<label>_space-<label>_res-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|.tsv][.gz]
+	atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].tsv
+	atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].json
+	atlas-<label>_space-<label>_desc-<label>_edges.[tck|<eeg,meg>]
+```
 
+#### Case 2 
 
-Third: a given atlas was derived from the corresponding subject’s data and thus is subject-specific. In this case, the respective BIDS-Atlas files are only stored at the subject level within the modality directory of the data the atlas was derived from. If a subject-specific atlas was spatially transformed from the space of the modality it was derived into the space of a different modality, then the BIDS-Atlas files would be stored in both respective modality directories. For example, if an atlas was derived from data in anat and shared/utilized as is, then the BIDS-Atlas files would only be stored in the anat directory. If the atlas was spatially transformed to the functional space of the respective subject, then the BIDS-Atlas files would be stored in both directories, anat and func. As in the prior use case, the “atlas” identifier will be replaced with “seg”.   
+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, while files stored at the subject level will be placed within the modality directory of the space the atlas was spatially transformed to and follow the subject-related naming conventions. For example, if an atlas was spatially transformed to the anatomical space of a given subject, then the BIDS-Atlas files will be stored within the respective subject’s anat directory and their file names will be prepended with the subject identifier. Additionally, instead of “atlas”, the “seg” identifier will be used to support a broader scope and more data modalities.  
 
-<dataset>/derivatives/<pipeline_name>/
-sub-01/
-	anat/		sub-01_space-<label>_seg_<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz]
-sub-01_space-<label>_seg-<label>_desc-<label>_[dseg|probseg|mask].tsv
-sub-01_space-<label>_seg-<label>_desc-<label>_[dseg|probseg|mask].json
-sub-01_space-<label>_seg-<label>_desc-<label>_edges.[tck|<eeg,meg>]
+```Text
+<dataset>/atlas/atlas-<label>/
+	atlas-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii][.gz]
+	atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv
+	atlas-<label>_desc-<label>_[dseg|probseg|mask].json
 
- 
-### [probseg|dseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tracts.trx/tck/trk][.gz]
+<dataset>/derivatives/
+	sub-01/
+		anat/
+		sub-01_space-<label>_seg-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz]
+		sub-01_space-<label>_seg-<label>_desc-<label>_[dseg|probseg|mask].tsv
+		sub-01_space-<label>_seg-<label>_desc-<label>_[dseg|probseg|mask].json
+```
 
-This file represents the location and extent of the nodes/parcels/regions within the atlas. Different file types are supported based on the modality and atlas at hand. In more detail, this encompasses the following three options:
+#### Case 3
+
+Third, a given atlas was derived from the corresponding subject’s data and thus is subject-specific. In this case, the respective BIDS-Atlas files are only stored at the subject level within the modality directory of the data the atlas was derived from. If a subject-specific atlas was spatially transformed from the space of the modality it was derived into the space of a different modality, then the BIDS-Atlas files would be stored in both respective modality directories. For example, if an atlas was derived from data in anat and shared/utilized as is, then the BIDS-Atlas files would only be stored in the anat directory. If the atlas was spatially transformed to the functional space of the respective subject, then the BIDS-Atlas files would be stored in both directories, anat and func. As in the prior use case, the “atlas” identifier will be replaced with “seg”. Note, if an atlas is defined at the single subject level, you should specify a [Image-based Coordinate System](/appendices/coordinate-systems.md).
+
+```Text
+<dataset>/derivatives/
+	sub-01/
+		anat/		
+			sub-01_space-<label>_seg_<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz]
+			sub-01_space-<label>_seg-<label>_desc-<label>_[dseg|probseg|mask].tsv
+			sub-01_space-<label>_seg-<label>_desc-<label>_[dseg|probseg|mask].json
+			sub-01_space-<label>_seg-<label>_desc-<label>_coordsystem.json
+```
+
+### Representing locations in an atlas file
+
+The `[probseg|dseg|mask].[nii|dlabel.nii|label.gii][.gz]` file represents the location and extent of the nodes/parcels/regions within the atlas. Different file types are supported based on the modality and atlas at hand. In more detail, this encompasses the following three options:
 
 1.	_dseg: Each node is labeled with a unique integer corresponding to its row/index in the tsv sidecar.
 2.	_probseg: Each node is represented along an additional dimension of the file (e.g., a 4D nifti file where each volume represents a node) and its position in that dimension corresponds to its row/index in the tsv sidecar.
@@ -65,75 +97,33 @@ a.	A 3D nifti file with unique integers defining nodes
 b.	A 4D binary nifti file with spatially overlapping nodes in each volume (along the 4th dimension)
 c.	A 4D nifti file with overlapping nodes with continuous values for each voxel within a volume
 
-Examples
+Examples:
+```Text
 atlas-HarvardOxford_res-2_dseg.nii.gz
 atlas-HarvardOxford_res-2_probseg.nii.gz
 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” label should be avoided as an inherited file may need to use the desc label to contain information related or unrelated to the atlas.
 
- 
-### [probseg|dseg|mask|channels].tsv
-
-This 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.
-
-index (or placeholder in fragment in reference)	REQUIRED. (Integer) The number associated with the node/parcel/region (right/left hemispheres may be different).
-label	RECOMMENDED. The node name
-network_id	OPTIONAL. Network ID the node/parcel belongs to
-network_label
-	OPTIONAL. Label of Network (e.g. Dorsal Attention Network)
-
-CoordinateReportStrategy	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”. 
-x	OPTIONAL. The x-coordinate of the node in the spatial reference space (See SpatialReference in the .json file)
-y	OPTIONAL. The y-coordinate of the node in the spatial reference space (See SpatialReference in the .json file)
-z	OPTIONAL. The z-coordinate of the node in the spatial reference space (See SpatialReference in the .json file)
-hemisphere	OPTIONAL. MUST BE ONE OF: “left”, “right”, “bilateral”. Indicate whether the node/parcel/region is in the left or right hemispheres, or is available bilaterally.
-color
-OPTIONAL. RGB color to use for the node.
-seed
-OPTIONAL. Seed vertex/channel of the node/region
-region
-OPTIONAL. “XY”, where X can be L:left, R:right, B:bilateral, and Y can be F:frontal, T:temporal, P:parietal, O:occipital
-
-
-
-
-
-
-Example
+ 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.
 
+insert missing table from word document here
+  
+Example:
+```Text
 index	label	network_label	hemisphere	…
 1	Heschl’ Gyrus	Somatomotor	left	…
 2	Heschl’ Gyrus	Somatomotor	right	…
-…	…	…	…	…
-
-### [probseg|dseg|mask].json
-
-This file provides metadata to uniquely identify, describe and characterize the atlas, as well as give proper attribution to the creators. Additionally, SpatialReference serves the important purpose of unambiguously identifying the space the atlas is labeled in.
-
+```
 
-Name	REQUIRED. Name of the atlas
-Description	RECOMMENDED. Longform description of the atlas
-SpatialReference	RECOMMENDED. Point to an existing atlas in a template space (url or relative file path where this file is located).
-CoordinateReportStrategy	OPTIONAL. MUST BE ONE OF: “peak”, “center_of_mass”, “other”. Indicate the method of coordinate reporting in statistically significant clusters. Could be the “peak” statistical coordinate in the cluster or the “center_of_mass” of the cluster. RECOMMENDED if x, y ,z values are set in the .tsv file. 
-Authors	RECOMMENDED. List of the authors involved in the creation of the atlas
-Curators	RECOMMENDED. List of curators who helped make the atlas accessible in a database or dataset
-Funding	RECOMMENDED. The funding source(s) involved in the atlas creation
-License	RECOMMENDED. The license agreement for using the atlas.
-ReferencesAndLinks	RECOMMENDED. A list of relevant references and links pertaining to the atlas.
-Species	RECOMMENDED. The species the atlas was derived from. For example, could be Human, Macaque, Rat, Mouse, etc.
-DerivedFrom	RECOMMENDED. Indicate what data modality the atlas was derived from, e.g. "cytoarchitecture", "resting-state", "task".
-LevelType	RECOMMENDED. Indicate what analysis level the atlas was derived from, e.g. "group", "individual".
-Additional Columns	RECOMMENDED. Describe the respective column in the tsv
+The `[probseg|dseg|mask].json` file provides metadata to uniquely identify, describe and characterize the atlas, as well as give proper attribution to the creators. Additionally, SpatialReference serves the important purpose of unambiguously identifying the space the atlas is labeled in.
 
+insert missing table from word document here
 
+Example:
 
-
-
-
-
-Example 
-
+```JSON
 {
   	"Name": "FSL's MNI ICBM 152 non-linear 6th Generation Asymmetric Average 
    Brain Stereotaxic Registration Model",
@@ -160,14 +150,8 @@ Example
      ],
   	"Species": "Human"
 }
+```
 
-
-
-
-
-
-
- 
 # 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.
 
@@ -175,15 +159,18 @@ Within the following, multiple examples showcasing the proposed extension are pr
 
 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.  
 
+```Text
 my_dataset/atlases/atlas-HarvardOxford/
 	atlas-HarvardOxford_res-2_dseg.json
 	atlas-HarvardOxford_res-2_dseg.nii.gz
 	atlas-HarvardOxford_res-2_dseg.tsv
+```
 
 The content of each file is further outlined in the following, starting with the .json sidecar file containing meta-data about the atlas at hand.
 
-atlas-HarvardOxford_res-2_dseg.json
+Example content of the `atlas-HarvardOxford_res-2_dseg.json` file:
 
+```JSON
 {
  	"Authors": [
  “David Kennedy”,
@@ -210,11 +197,14 @@ atlas-HarvardOxford_res-2_dseg.json
      ],
   	"Species": "Human"
 }
+```
 
 Next, the content of the tsv files describing the indices and corresponding labels present in the atlas at hand. 
 
-atlas-HarvardOxford_res-2_dseg.tsv
+Example content of the `atlas-HarvardOxford_res-2_dseg.tsv` file:
 
+
+```Text
 index	label	hemisphere
 0	Background	bilateral
 1	Frontal Pole	bilateral
@@ -224,56 +214,55 @@ Insular Cortex	bilateral
 4	Middle Frontal Gyrus	bilateral
 5	Inferior Frontal Gyrus, pars triangularis	bilateral
 6	Inferior Frontal Gyrus, pars opercularis	bilateral
-…		
-
+```
 
-
- 
 ## Multiple existing atlases in template space
 The example below illustrates how multiple existing atlases in the same template space are represented according to the atlas BEP. Specifically, the example refers to the Harvard-Oxford, Schaefer, Yeo and MSDL atlases, all in MN152NLin6Asym space and with a resolution of 2 mm3, were utilized without modifications (e.g. transformations, subsetting, etc.) for all subjects to which the pipeline was applied. Importantly, all atlas-related information is indicated via the value of the atlas- key and not via desc- to help prevent inheritance problems in subsequent steps. Here, this was used to indicate that the Harvard-Oxford atlas in its version with a maximum probability of 50, the Schaefer atlas in its 400 parcel version and the Yeo atlas in its 17 networks version were used. The respective information found in each file follows the example outlined in 4.1 as atlases were used independently from one another.
 
+
+```Text
 bids/atlases/
-atlas-HarvardOxford/
+	atlas-HarvardOxford/
 		atlas-HarvardOxford_dseg.nii.gz
-	atlas-HarvardOxford_dseg.json
+		atlas-HarvardOxford_dseg.json
 		atlas-HarvardOxford_dseg.tsv
-atlas-Schaefer400/
-atlas-Schaefer400_dseg.nii.gz
-atlas-Schaefer400_dseg.json
-atlas-Schaefer400_dseg.tsv
-atlas-Yeo17/
-atlas-Yeo17_dseg.nii.gz
-atlas-Yeo17_dseg.json
-atlas-Yeo17_dseg.tsv
-atlas-msdl/
-atlas-msdl_probseg.nii.gz
-atlas-msdl_probseg.json
-atlas-msdl_probseg.tsv
-
-
-
+	atlas-Schaefer400/
+		atlas-Schaefer400_dseg.nii.gz
+		atlas-Schaefer400_dseg.json
+		atlas-Schaefer400_dseg.tsv
+	atlas-Yeo17/
+		atlas-Yeo17_dseg.nii.gz
+		atlas-Yeo17_dseg.json
+		atlas-Yeo17_dseg.tsv
+	atlas-msdl/
+		atlas-msdl_probseg.nii.gz
+		atlas-msdl_probseg.json
+		atlas-msdl_probseg.tsv
+```
  
 ## Single existing atlas transformed to subject space
 The example below illustrates how a single existing atlas transformed into a subject’s native space space is represented according to the atlas BEP. Specifically, the example refers to the Harvard-Oxford atlas with a resolution of 2 mm3 that was transformed from the MN152NLin6Asym template space to a given subject’s native T1w space. While the original atlas-related files remain as outlined in the use case in template space, the spatially transformed version of the nii.gz atlas file will be placed within a given subjects directory. The precise location within the latter depends on the modality space to which the atlas was transformed to, e.g. anat, func or dwi. The same location furthermore entails a corresponding json file outlining further information on the source atlas and applied transformation(s).
 
 
+```Text
 bids/atlases/atlas-HarvardOxford/
 	atlas-HarvardOxford_dseg.json
-atlas-HarvardOxford_dseg.tsv
+	atlas-HarvardOxford_dseg.tsv
 	atlas-HavardOxford2_dseg.nii.gz
 bids/derivatives/pipeline-<name>/
 	sub-01/
-anat/
-  sub-01_T1w.nii.gz
-		  sub-01_space-T1w_seg-HarvardOxfordThr50_res-2_dseg.nii.gz	
-  sub-01_space-T1w_seg-HarvardOxfordThr50_res-2_dseg.json
-  sub-01_space-T1w_seg-HarvardOxfordThr50_res-2_dseg.tsv
-
+		anat/
+  			sub-01_T1w.nii.gz
+		  	sub-01_space-T1w_seg-HarvardOxfordThr50_res-2_dseg.nii.gz	
+  			sub-01_space-T1w_seg-HarvardOxfordThr50_res-2_dseg.json
+  			sub-01_space-T1w_seg-HarvardOxfordThr50_res-2_dseg.tsv
+```
 
 The json file accompanying the transformed atlas should include the following information.
 
-sub-01_space-T1w_seg-HarvardOxford_res-2_dseg.json
+Example content of the `sub-01_space-T1w_seg-HarvardOxford_res-2_dseg.json` file:
 
+```JSON
 {
  	"BIDSVersion": "1.1.0",
 “SpatialReference”: “sub-01/anat/sub-01_T1w.nii.gz”,
@@ -283,32 +272,35 @@ sub-01_space-T1w_seg-HarvardOxford_res-2_dseg.json
 	“Sources”: [],
 “transformation”:
 }
-
+```
 
 ##  MyConnectome example
 
 The example below illustrates how two atlases, an individual surface-based cortical parcellation in FS_lr space (called Russome), and the subcortical regions from a volumetric segmentation provided by the FreeSurfer aseg, are represented according to the atlas BEP. While the FreeSurfer atlas-related files have two instances, one as outlined in the use case in template space and one as outlined in the use case covering subject spaces, the individual parcellation in FS_lr space will be placed only within a given subjects directory. The same location furthermore entails a corresponding json file outlining further information on the atlas and applied analysis to obtain it.
 
+```Text
 bids/atlases/atlas-FreeSurferASEG/
 	atlas-FreeSurferASEG_dseg.json
 	atlas-FreeSurferASEG_dseg.tsv
 	atlas-FreeSurferASEG_dseg.nii.gz
+
 bids/derivatives/pipeline-<name>/
 	sub-01/
-anat/
-		  sub-01_space-T1w_seg-FreeSurferASEG_res-2_dseg.nii.gz	
-  sub-01_space-T1w_seg-FreeSurferASEG_res-2_dseg.json
-  sub-01_space-T1w_seg-FreeSurferASEG_res-2_dseg.tsv
-func/
- 		  sub-01_space-FSlr_seg-Russome_res-2_dseg.nii.gz	
-  sub-01_space-FSlr_seg-Russome_res-2_dseg.json
-  sub-01_space-FSlr_seg-Russome_res-2_dseg.tsv
-
+		anat/
+			sub-01_space-T1w_seg-FreeSurferASEG_res-2_dseg.nii.gz	
+  			sub-01_space-T1w_seg-FreeSurferASEG_res-2_dseg.json
+  			sub-01_space-T1w_seg-FreeSurferASEG_res-2_dseg.tsv
+		func/
+ 			sub-01_space-FSlr_seg-Russome_res-2_dseg.nii.gz	
+  			sub-01_space-FSlr_seg-Russome_res-2_dseg.json
+  			sub-01_space-FSlr_seg-Russome_res-2_dseg.tsv
+```
 
 The json file accompanying the functionally derived atlas should include the following information.
 
-sub-01_task-rest_atlas.json: contains top-level metadata about atlas
+Example content of the `sub-01_task-rest_atlas.json` file contains top-level metadata about the atlas:
 
+```JSON
 {
   "Atlas": {
     "Russome": {
@@ -320,75 +312,62 @@ sub-01_task-rest_atlas.json: contains top-level metadata about atlas
 “Extra”: “freesurfer aseg”
 }
 }
+```
 
 ## Atlas utilization in electrophysiology data
 
-Some atlases in development include the Open MNI iEEG Atlas (https://mni-open-ieegatlas.research.mcgill.ca/) led by Birgit Frauscher and Jean Gotman of at McGill University with technical implementation led by Alan Evans’ group led by Christine Rogers [citation].  106 subjects’s signal data from 17__ channels in non-epileptogenic areas of (“normal”) tissue was mapped to a MICCAI 2012 standardized atlas template [citation]. 
--> what would an atlas directory look like given the data is coming from multi-subjects? (example 4.7 quantitative atlas example) 
--> Is BIDS coverage currently sufficient to describe this, what more metadata would be helpful, e.g. reference space.  (spatial reference is defined in 4.4 json sidecar)
--> what they can be used for.  Looks like eeg but x y z can’t be run without abc 
-
-
-Additional intracranial EEG atlas development is in progress across 10 sites in 6 countries.   
-Co-registration on MRI templates is performed with …. 
+Some atlases in development include the Open MNI iEEG Atlas (https://mni-open-ieegatlas.research.mcgill.ca/) led by Birgit Frauscher and Jean Gotman of at McGill University with technical implementation led by Alan Evans’ group led by Christine Rogers [citation].  106 subjects’s signal data from 17__ channels in non-epileptogenic areas of (“normal”) tissue was mapped to a MICCAI 2012 standardized atlas template [citation]. Additional intracranial EEG atlas development is in progress across 10 sites in 6 countries.   
 
-Example might look something like this, just to verify that the above could be extended with a timeseries file in which the ‘channels’ correspond to the _dseg.tsv, and the json file might need an indicator that there is a time series file. This example is only here to decide whether this is out of scope, can be removed.
-bids/atlases/atlas-FreeSurferASEG/
-	atlas-FreeSurferASEG_dseg.json
-	atlas-FreeSurferASEG_dseg.tsv
-	atlas-FreeSurferASEG_dseg.nii.gz
-atlas-FreeSurferASEG_dseg.edf
- 
 ## Quantitative atlas examples 
 
-The example below is for PET imaging, but this applies to any quantitative mapping (PET or QMRI). Compared to anatomical atlases, quantitative atlases give reference values to be compared with. Such values can be derived voxel/vertex wise or per region of interest (ROI), in the later case deriving ROIs generally from an anatomical atlas. 
-
-We created a Molecular Imaging Brain Atlases (MIBA) from 16 subjects who underwent a [11C]PS13 PET scan, a radioligand that quantifies cyclooxygenase-1 (source data: https://openneuro.org/datasets/ds004332/versions/1.0.2). Our atlas consists of mean and standard deviations of PS13 target distribution volumes (VT) computed across the 16 subjects at each voxel, in standard MRI spaces. We also project these distribution volumes onto the freesurfer cortical surfaces and include these as well.  The goal is to allow researchers with MRI-only data to correlate their results to the distribution volume of PS13. The dataset can be found at https://openneuro.org/datasets/ds004401/versions/1.1.0 (to be changed following this spec). 
-
-Case 1: voxel/vertex wise analysis
-
-Missing is the measure -- what was computed, BPND?
-
-bids/atlases/atlas-ps13/
-	  atlas-ps13_space-fsaverage_hemi-L_stat-mean_meas-VT_mimap.json
-       atlas-ps13_space-fsaverage_hemi-L_stat-mean_meas-VT_mimap.nii.gz
-       atlas-ps13_space-fsaverage_hemi-R_stat-mean_meas-VT_mimap.json
-       atlas-ps13_space-fsaverage_hemi-R_stat-mean_meas-VT_mimap.nii.gz
-	  atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_mimap.json
-       atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_mimap.nii.gz 
-       atlas-ps13_space-fsaverage_hemi-L_stat-std_meas-VT_mimap.json
-  atlas-ps13_space-fsaverage_hemi-L_stat-std_meas-VT_mimap.nii.gz
-  atlas-ps13_space-fsaverage_hemi-R_stat-std_meas-VT_mimap.json
-  atlas-ps13_space-fsaverage_hemi-R_stat-std_meas-VT_mimap.nii.gz
-
-  atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_mimap.json
-  atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_mimap.nii.gz
-
-
- 
-Case 2: regional analysis (voxels/vertices are averaged per regions from dseg/probseg)
-
-bids/atlases/
-atlas-mni305/
-atlas-aparc.DKTatlas+aseg.mgz
-atlas-aparc.DKTatlas+aseg.tsv
-atlas-RB_all_2008-03-26.probseg.gca
-atlas-RB_all_2008-03-26.probseg.tsv
-atlas-ps13/
-	  atlas-ps13_space-fsaverage_hemi-L_stat-mean_meas-VT_mimap.json
+The example below is for PET imaging, but this applies to any quantitative mapping (PET or QMRI). Compared to anatomical atlases, quantitative atlases give reference values to be compared with. Such values can be derived voxel/vertex wise (see case 1) or per region of interest (ROI) (see case 2). In the latter case, ROIs are generally derived from an anatomical atlas. 
+
+We created a Molecular Imaging Brain Atlases (MIBA) from 16 subjects who underwent a [11C]PS13 PET scan, a radioligand that quantifies cyclooxygenase-1 (see [source data](https://openneuro.org/datasets/ds004332/versions/1.0.2)). Our atlas consists of mean and standard deviations of PS13 target distribution volumes (VT) computed across the 16 subjects at each voxel, in standard MRI spaces. We also project these distribution volumes onto the freesurfer cortical surfaces and include these as well.  The goal is to allow researchers with MRI-only data to correlate their results to the distribution volume of PS13. The dataset can be found [here](https://openneuro.org/datasets/ds004401/versions/1.1.0). 
+
+### Case 1: voxel/vertex wise analysis
+
+Example directory content for a quantitative atlas that provides values at all voxels and/or verteces:
+
+```Text
+bids/atlas/atlas-ps13/
+		atlas-ps13_space-fsaverage_hemi-L_stat-mean_meas-VT_mimap.json
+       	atlas-ps13_space-fsaverage_hemi-L_stat-mean_meas-VT_mimap.nii.gz
+       	atlas-ps13_space-fsaverage_hemi-R_stat-mean_meas-VT_mimap.json
+       	atlas-ps13_space-fsaverage_hemi-R_stat-mean_meas-VT_mimap.nii.gz
+	  	atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_mimap.json
+       	atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_mimap.nii.gz 
+       	atlas-ps13_space-fsaverage_hemi-L_stat-std_meas-VT_mimap.json
+		atlas-ps13_space-fsaverage_hemi-L_stat-std_meas-VT_mimap.nii.gz
+		atlas-ps13_space-fsaverage_hemi-R_stat-std_meas-VT_mimap.json
+		atlas-ps13_space-fsaverage_hemi-R_stat-std_meas-VT_mimap.nii.gz
+		atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_mimap.json
+		atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_mimap.nii.gz
+```
+
+### Case 2: regional analysis (voxels/vertices are averaged per regions from dseg/probseg)
+
+Example directory content for a quantitative atlas that provides values for certain ROIs only:
+
+```Text
+bids/atlas/
+	atlas-mni305/
+		atlas-aparc.DKTatlas+aseg.mgz
+		atlas-aparc.DKTatlas+aseg.tsv
+		atlas-RB_all_2008-03-26.probseg.gca
+		atlas-RB_all_2008-03-26.probseg.tsv
+	atlas-ps13/
+	  	atlas-ps13_space-fsaverage_hemi-L_stat-mean_meas-VT_mimap.json
         atlas-ps13_space-fsaverage-hemi-L_stat-mean_meas-VT_mimap.tsv
         atlas-ps13_space-fsaverage-hemi-L_stat-std_meas-VT_mimap.json
-       atlas-ps13_space-fsaverage-hemi-L_stat-std_meas-VT_mimap.tsv
-       atlas-ps13_space-fsaverage-hemi-R_stat-mean_meas-VT_mimap.json
-       atlas-ps13_space-fsaverage-hemi-R_stat-mean_meas-VT_mimap.tsv
-  atlas-ps13_space-fsaverage-hemi-R_stat-std_meas-VT_mimap.json
-  atlas-ps13_space-fsaverage-hemi-R_stat-std_meas-VT_mimap.tsv
-  atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_mimap.json
-  atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_mimap.tsv
-  atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_mimap.json
-  atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_mimap.tsv
-
-(note that there is no image -- we should provide instruction how to load such tsv in freesurfer for surface viewing (and save as?) in a readme and also do the same as matlab/python code for generating volumes from the tsv at the desired resolution)
-
-
-The json file accompanying the quantitative atlas should include the information as in 4.1.
\ No newline at end of file
+       	atlas-ps13_space-fsaverage-hemi-L_stat-std_meas-VT_mimap.tsv
+       	atlas-ps13_space-fsaverage-hemi-R_stat-mean_meas-VT_mimap.json
+       	atlas-ps13_space-fsaverage-hemi-R_stat-mean_meas-VT_mimap.tsv
+		atlas-ps13_space-fsaverage-hemi-R_stat-std_meas-VT_mimap.json
+		atlas-ps13_space-fsaverage-hemi-R_stat-std_meas-VT_mimap.tsv
+		atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_mimap.json
+		atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_mimap.tsv
+		atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_mimap.json
+		atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_mimap.tsv
+```
+
+Note that there is no image file present in a regional qunatitative atlas. The json file accompanying the quantitative atlas should include the information as in 4.1.
\ No newline at end of file
diff --git a/src/schema/objects/entities.yaml b/src/schema/objects/entities.yaml
index 6facc34c0d..29ea8f43e3 100644
--- a/src/schema/objects/entities.yaml
+++ b/src/schema/objects/entities.yaml
@@ -25,6 +25,15 @@ acquisition:
     remains at the discretion of the researcher.
   type: string
   format: label
+atlas:
+  name: atlas
+  display_name: Atlas
+  description: |
+  The definition of atlas per Merriam-Webster is ‘a bound collection of maps (i.e. labeled brain regions or quantitative aspects) and metadata (tables, or textual matter). 
+
+  Within BIDS atlases are broadly defined as a mapping between locations in a spatial coordinate systems and descriptions associated with those locations. By analogy with geographical atlases, brain atlases can map brain locations to either discrete labels like a map of countries does, or to continuous quantities like a topographic map does.
+
+  This comprises all possible types of atlases, specifically deterministic, probabilistic, and mask/voxel-based ones, and quantitative maps from various modalities including but not limited to: structural features (e.g. myelination, cytoarchitecture), functional features (e.g. resting-state networks, localizers) and such based on multimodal data integration (e.g. gene expression, receptors). Furthermore, it covers both volume/voxel and surface/vertex data, as well as gray and white matter atlases.
 ceagent:
   name: ce
   display_name: Contrast Enhancing Agent

From 81d5ccc2ca951c01d48c5fd08bbf22d3764e20c2 Mon Sep 17 00:00:00 2001
From: melanieganz <melanie.ganz@gmail.com>
Date: Tue, 23 Jan 2024 16:14:16 +0100
Subject: [PATCH 04/16] Fixed details

Fixed details such as linking to entities and suffixes as well as clarified some of the example text.  The tables need still to be fixed.
---
 src/atlas.md | 129 +++++++++++++++++++++++++--------------------------
 1 file changed, 62 insertions(+), 67 deletions(-)

diff --git a/src/atlas.md b/src/atlas.md
index 2fa10e6fd6..226fdfb020 100644
--- a/src/atlas.md
+++ b/src/atlas.md
@@ -2,7 +2,7 @@
 
 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. 
+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.
@@ -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-” identifier, following the same directory structure as “sub”, i.e., one dedicated directory for each atlas within a given dataset. 
+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. 
 The default way of storage of the non-altered atlas at the root directory looks like this:
 
 ```Text
@@ -35,11 +35,11 @@ The default way of storage of the non-altered atlas at the root directory looks
 
 ### Representing the atlas at the subject level
 
-Besides this default and required storage of the non-altered atlas at the root directory, the second use case provides three options to store atlases that were either altered, applied, or derived within a given dataset. While option 1 also uses the “atlas” identifier, options 2 and 3 use the “seg” identifier, as outlined in the next paragraphs.
+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 also uses the [atlas](schema/objects/entities.yaml#atlas) identifier, case 2 and 3 use the [seg](schema/objects/entities.yaml#seg) identifier, as outlined in the next paragraphs.
 
 #### Case 1
 
-First, a given atlas underwent modifications before its utilization, specifically spatial transformations to a template space and is used in this form within a given pipeline. In this case, the respective BIDS-Atlas files will be stored at both the BIDS root level and the given pipeline directory under “derivatives”. Files stored at the BIDS root level will follow the structure outlined in option 1, while files stored at the pipeline level will follow the respective naming conventions. For example, if an atlas was spatially transformed to a certain MNI template, then the BIDS-Atlas files will be stored within the respective pipeline directory and the corresponding space-<label> identifier will be adapted accordingly. 
+First, a given atlas underwent modifications before its utilization, specifically spatial transformations to a template space and is used in this form within a given pipeline. In this case, the respective BIDS-Atlas files will be stored at both the BIDS root level and the given pipeline directory under `derivatives`. Files stored at the BIDS root level will follow the structure outlined in option 1, while files stored at the pipeline level will follow the respective naming conventions. For example, if an atlas was spatially transformed to a certain MNI template, then the BIDS-Atlas files will be stored within the respective pipeline directory and the corresponding [space](schema/objects/entities.yaml#space)-<label> identifier will be adapted accordingly. 
 
 ```Text
 <dataset>/atlas/atlas-<label>/
@@ -56,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, while files stored at the subject level will be placed within the modality directory of the space the atlas was spatially transformed to and follow the subject-related naming conventions. For example, if an atlas was spatially transformed to the anatomical space of a given subject, then the BIDS-Atlas files will be stored within the respective subject’s anat directory and their file names will be prepended with the subject identifier. Additionally, instead of “atlas”, the “seg” identifier will be used to support a broader scope and more data modalities.  
+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, while files stored at the subject level will be placed within the modality directory of the space the atlas was spatially transformed to and follow the subject-related naming conventions. For example, if an atlas was spatially transformed to the anatomical space of a given subject, then the BIDS-Atlas files will be stored within the respective subject’s anat directory and their file names will be prepended with the subject identifier. Additionally, instead of [atlas](schema/objects/entities.yaml#atlas), the [seg](schema/objects/entities.yaml#seg) identifier will be used to support a broader scope and more data modalities.  
 
 ```Text
 <dataset>/atlas/atlas-<label>/
@@ -74,7 +74,9 @@ 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 respective BIDS-Atlas files are only stored at the subject level within the modality directory of the data the atlas was derived from. If a subject-specific atlas was spatially transformed from the space of the modality it was derived into the space of a different modality, then the BIDS-Atlas files would be stored in both respective modality directories. For example, if an atlas was derived from data in anat and shared/utilized as is, then the BIDS-Atlas files would only be stored in the anat directory. If the atlas was spatially transformed to the functional space of the respective subject, then the BIDS-Atlas files would be stored in both directories, anat and func. As in the prior use case, the “atlas” identifier will be replaced with “seg”. Note, if an atlas is defined at the single subject level, you should specify a [Image-based Coordinate System](/appendices/coordinate-systems.md).
+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. The only addition is a `*_coordsystem.json` file that specifies the [Image-based Coordinate System](/appendices/coordinate-systems.md) of the suject-specific atlas. 
+
+If a subject-specific atlas was spatially transformed from the space of the modality it was derived into the space of a different modality, then the BIDS-Atlas files would be stored in both respective modality directories. For example, if an atlas was derived from data in anat and shared/utilized as is, then the BIDS-Atlas files would only be stored in the anat directory. If the atlas was spatially transformed to the functional space of the respective subject, then the BIDS-Atlas files would be stored in both directories, anat and func. 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/
@@ -90,9 +92,9 @@ Third, a given atlas was derived from the corresponding subject’s data and thu
 
 The `[probseg|dseg|mask].[nii|dlabel.nii|label.gii][.gz]` file represents the location and extent of the nodes/parcels/regions within the atlas. Different file types are supported based on the modality and atlas at hand. In more detail, this encompasses the following three options:
 
-1.	_dseg: Each node is labeled with a unique integer corresponding to its row/index in the tsv sidecar.
-2.	_probseg: Each node is represented along an additional dimension of the file (e.g., a 4D nifti file where each volume represents a node) and its position in that dimension corresponds to its row/index in the tsv sidecar.
-3.	_mask: Either each voxel represents a node or the entire mask is a single node. How the mask should be interpreted is determined by other specifications. Based on these options, an atlas can take the following forms in the here proposed specification (non-exhaustive list):
+1. [_dseg](schema/objects/suffixes.yaml#dseg): Each node is labeled with a unique integer corresponding to its row/index in the tsv sidecar.
+2. [_probseg](schema/objects/suffixes.yaml#probseg): Each node is represented along an additional dimension of the file (e.g., a 4D nifti file where each volume represents a node) and its position in that dimension corresponds to its row/index in the tsv sidecar.
+3. [_mask](schema/objects/suffixes.yaml#mask): Either each voxel represents a node or the entire mask is a single node. How the mask should be interpreted is determined by other specifications. Based on these options, an atlas can take the following forms in the here proposed specification (non-exhaustive list):
 a.	A 3D nifti file with unique integers defining nodes
 b.	A 4D binary nifti file with spatially overlapping nodes in each volume (along the 4th dimension)
 c.	A 4D nifti file with overlapping nodes with continuous values for each voxel within a volume
@@ -104,11 +106,11 @@ atlas-HarvardOxford_res-2_probseg.nii.gz
 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” label should be avoided as an inherited file may need to use the desc label to contain information related or unrelated to the atlas.
+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.
 
-insert missing table from word document here
+insert missing table 1 from Google doc here
   
 Example:
 ```Text
@@ -119,35 +121,33 @@ index	label	network_label	hemisphere	…
 
 The `[probseg|dseg|mask].json` file provides metadata to uniquely identify, describe and characterize the atlas, as well as give proper attribution to the creators. Additionally, SpatialReference serves the important purpose of unambiguously identifying the space the atlas is labeled in.
 
-insert missing table from word document here
+insert missing table 2 from Google doc here
 
 Example:
 
 ```JSON
 {
-  	"Name": "FSL's MNI ICBM 152 non-linear 6th Generation Asymmetric Average 
-   Brain Stereotaxic Registration Model",
+  	"Name": "FSL's MNI ICBM 152 non-linear 6th Generation Asymmetric Average Brain Stereotaxic Registration Model",
  	"Authors": [
- “David Kennedy”,
- “Christian Haselgrove”,
- “Bruce Fischl”,
- “Janis Breeze”,
- “Jean Frazie”, 
- “Larry Seidman”,
- “Jill Goldstein”
- 		],
+		"David Kennedy",
+		"Christian Haselgrove",
+		"Bruce Fischl",
+		"Janis Breeze",
+		"Jean Frazie", 
+		"Larry Seidman",
+		"Jill Goldstein"
+				],
  	"BIDSVersion": "1.1.0",
  	"Curators": "FSL team",
-“SpatialReference”:   
-“https://templateflow.s3.amazonaws.com/tpl-MNI152NLin6Asym_res-02_T1w.nii.gz”,
+	"SpatialReference": "https://templateflow.s3.amazonaws.com/tpl-MNI152NLin6Asym_res-02_T1w.nii.gz",
  	"Space": "MNI152NLin6Asym",
-“Resolution”: “Matched with original template resolution (2x2x3 mm^3)”, 
+	"Resolution": "Matched with original template resolution (2x2x3 mm^3)", 
  	"License": "See LICENSE file",
-"RRID": "SCR_002823",
+	"RRID": "SCR_002823",
   	"ReferencesAndLinks": [
-  "https://doi.org/10.1016/j.neuroimage.2012.01.024",
-  "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Atlases”
-     ],
+	"https://doi.org/10.1016/j.neuroimage.2012.01.024",
+	"https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Atlases"
+		],
   	"Species": "Human"
 }
 ```
@@ -173,28 +173,26 @@ Example content of the `atlas-HarvardOxford_res-2_dseg.json` file:
 ```JSON
 {
  	"Authors": [
- “David Kennedy”,
- “Christian Haselgrove”,
- “Bruce Fischl”,
- “Janis Breeze”,
- “Jean Frazie”, 
- “Larry Seidman”,
- “Jill Goldstein”
- 		],
+		"David Kennedy",
+		"Christian Haselgrove",
+		"Bruce Fischl",
+		"Janis Breeze",
+		"Jean Frazie", 
+		"Larry Seidman",
+		"Jill Goldstein"
+				],
  	"BIDSVersion": "1.1.0",
  	"Curators": "FSL team",
-“SpatialReference”:   
-“https://templateflow.s3.amazonaws.com/tpl-MNI152NLin6Asym_res-02_T1w.nii.gz”,
+	"SpatialReference": "https://templateflow.s3.amazonaws.com/tpl-MNI152NLin6Asym_res-02_T1w.nii.gz",
  	"Space": "MNI152NLin6Asym",
-“Resolution”: “Matched with original template resolution (2x2x3 mm^3)”, 
+"	Resolution": "Matched with original template resolution (2x2x3 mm^3)", 
  	"License": "See LICENSE file",
-  	"Name": "FSL's MNI ICBM 152 non-linear 6th Generation Asymmetric Average 
-   Brain Stereotaxic Registration Model",
-"RRID": "SCR_002823",
+  	"Name": "FSL's MNI ICBM 152 non-linear 6th Generation Asymmetric Average Brain Stereotaxic Registration Model",
+	"RRID": "SCR_002823",
   	"ReferencesAndLinks": [
-  "https://doi.org/10.1016/j.neuroimage.2012.01.024",
-  "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Atlases”
-     ],
+	"https://doi.org/10.1016/j.neuroimage.2012.01.024",
+	"https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Atlases"
+		],
   	"Species": "Human"
 }
 ```
@@ -203,7 +201,6 @@ Next, the content of the tsv files describing the indices and corresponding labe
 
 Example content of the `atlas-HarvardOxford_res-2_dseg.tsv` file:
 
-
 ```Text
 index	label	hemisphere
 0	Background	bilateral
@@ -265,12 +262,11 @@ Example content of the `sub-01_space-T1w_seg-HarvardOxford_res-2_dseg.json` file
 ```JSON
 {
  	"BIDSVersion": "1.1.0",
-“SpatialReference”: “sub-01/anat/sub-01_T1w.nii.gz”,
+	"SpatialReference": "sub-01/anat/sub-01_T1w.nii.gz",
  	"Space": "T1w",
-“Resolution”: “Matched with original resolution in subject T1w space 
-  (1x1x1 mm^3)”, 
-	“Sources”: [],
-“transformation”:
+	"Resolution": "Matched with original resolution in subject T1w space (1x1x1 mm^3)", 
+	"Sources": [],
+	"transformation":
 }
 ```
 
@@ -301,22 +297,21 @@ The json file accompanying the functionally derived atlas should include the fol
 Example content of the `sub-01_task-rest_atlas.json` file contains top-level metadata about the atlas:
 
 ```JSON
-{
-  "Atlas": {
-    "Russome": {
-“Atlasfile”: “/link/to/russome/file”, 
-“Extra”: “individualized surface parcellation”
-},
-    “FS_aseg”: {
-“Atlasfile”: “/link/to/aseg/file”, 
-“Extra”: “freesurfer aseg”
-}
-}
-```
 
-## Atlas utilization in electrophysiology data
+"Atlas": 
+{
+	"Russome": 
+	{
+	"Atlasfile": "/link/to/russome/file", 
+	"Extra": "individualized surface parcellation"
+	},
+	"FS_aseg": {
+	"Atlasfile": "/link/to/aseg/file", 
+	"Extra": "freesurfer aseg"
+	}
+} 
 
-Some atlases in development include the Open MNI iEEG Atlas (https://mni-open-ieegatlas.research.mcgill.ca/) led by Birgit Frauscher and Jean Gotman of at McGill University with technical implementation led by Alan Evans’ group led by Christine Rogers [citation].  106 subjects’s signal data from 17__ channels in non-epileptogenic areas of (“normal”) tissue was mapped to a MICCAI 2012 standardized atlas template [citation]. Additional intracranial EEG atlas development is in progress across 10 sites in 6 countries.   
+```
 
 ## Quantitative atlas examples 
 
@@ -370,4 +365,4 @@ bids/atlas/
 		atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_mimap.tsv
 ```
 
-Note that there is no image file present in a regional qunatitative atlas. The json file accompanying the quantitative atlas should include the information as in 4.1.
\ No newline at end of file
+Note that there is no image file present in a regional qunatitative atlas. The json file accompanying the quantitative atlas should include the information as in [Single existing atlas in template space](#_Single_existing_atlas_in_template_space).
\ No newline at end of file

From 7626992505dcdaae0c71023f3137a616d28b1b1d Mon Sep 17 00:00:00 2001
From: melanieganz <melanie.ganz@gmail.com>
Date: Wed, 24 Jan 2024 16:24:41 +0100
Subject: [PATCH 05/16] case 3 files renamed

---
 src/atlas.md | 229 +++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 196 insertions(+), 33 deletions(-)

diff --git a/src/atlas.md b/src/atlas.md
index 226fdfb020..fdce6a84df 100644
--- a/src/atlas.md
+++ b/src/atlas.md
@@ -15,7 +15,7 @@ The usage of [_desc-](schema/objects/entities.yaml#desc) is currently discourage
 ## 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. 
 
-### Representing the atlas at the dataset level
+### 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  
 
@@ -33,9 +33,8 @@ The default way of storage of the non-altered atlas at the root directory looks
 	atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].json
 ```
 
-### Representing the atlas at the subject level
-
-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 also uses the [atlas](schema/objects/entities.yaml#atlas) identifier, case 2 and 3 use the [seg](schema/objects/entities.yaml#seg) identifier, as outlined in the next paragraphs.
+### 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.
 
 #### Case 1
 
@@ -56,7 +55,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, while files stored at the subject level will be placed within the modality directory of the space the atlas was spatially transformed to and follow the subject-related naming conventions. For example, if an atlas was spatially transformed to the anatomical space of a given subject, then the BIDS-Atlas files will be stored within the respective subject’s anat directory and their file names will be prepended with the subject identifier. Additionally, instead of [atlas](schema/objects/entities.yaml#atlas), the [seg](schema/objects/entities.yaml#seg) identifier will be used to support a broader scope and more data modalities.  
+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. 
 
 ```Text
 <dataset>/atlas/atlas-<label>/
@@ -66,7 +65,7 @@ Second, a given atlas underwent modifications before its utilization, specifical
 
 <dataset>/derivatives/
 	sub-01/
-		anat/
+		func/
 		sub-01_space-<label>_seg-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz]
 		sub-01_space-<label>_seg-<label>_desc-<label>_[dseg|probseg|mask].tsv
 		sub-01_space-<label>_seg-<label>_desc-<label>_[dseg|probseg|mask].json
@@ -74,19 +73,17 @@ 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. The only addition is a `*_coordsystem.json` file that specifies the [Image-based Coordinate System](/appendices/coordinate-systems.md) of the suject-specific atlas. 
-
-If a subject-specific atlas was spatially transformed from the space of the modality it was derived into the space of a different modality, then the BIDS-Atlas files would be stored in both respective modality directories. For example, if an atlas was derived from data in anat and shared/utilized as is, then the BIDS-Atlas files would only be stored in the anat directory. If the atlas was spatially transformed to the functional space of the respective subject, then the BIDS-Atlas files would be stored in both directories, anat and func. 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 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.
 
 ```Text
 <dataset>/derivatives/
 	sub-01/
 		anat/		
-			sub-01_space-<label>_seg_<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz]
-			sub-01_space-<label>_seg-<label>_desc-<label>_[dseg|probseg|mask].tsv
-			sub-01_space-<label>_seg-<label>_desc-<label>_[dseg|probseg|mask].json
-			sub-01_space-<label>_seg-<label>_desc-<label>_coordsystem.json
-```
+			sub-01_atlas-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz][.ome-tiff|.png]
+			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
 
@@ -110,18 +107,184 @@ General Recommendations: This specification relies on the inheritance principle
 
  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.
 
-insert missing table 1 from Google doc here
+<table>
+  <tr>
+   <td>index (or placeholder in fragment in reference)
+   </td>
+   <td>REQUIRED. (Integer) The number associated with the node/parcel/region (right/left hemispheres may be different).
+   </td>
+  </tr>
+  <tr>
+   <td>label
+   </td>
+   <td>RECOMMENDED. The node name
+   </td>
+  </tr>
+  <tr>
+   <td>network_id
+   </td>
+   <td>OPTIONAL. Network ID the node/parcel belongs to
+   </td>
+  </tr>
+  <tr>
+   <td>network_label
+   </td>
+   <td>OPTIONAL. Label of Network (e.g. Dorsal Attention Network)
+   </td>
+  </tr>
+  <tr>
+   <td>CoordinateReportStrategy
+   </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>
+  </tr>
+  <tr>
+   <td>x
+   </td>
+   <td>OPTIONAL. The x-coordinate of the node in the spatial reference space (See SpatialReference in the .json file)
+   </td>
+  </tr>
+  <tr>
+   <td>y
+   </td>
+   <td>OPTIONAL. The y-coordinate of the node in the spatial reference space (See SpatialReference in the .json file)
+   </td>
+  </tr>
+  <tr>
+   <td>z
+   </td>
+   <td>OPTIONAL. The z-coordinate of the node in the spatial reference space (See SpatialReference in the .json file)
+   </td>
+  </tr>
+  <tr>
+   <td>hemisphere
+   </td>
+   <td>OPTIONAL. MUST BE ONE OF: “left”, “right”, “bilateral”. Indicate whether the node/parcel/region is in the left or right hemispheres, or is available bilaterally.
+   </td>
+  </tr>
+  <tr>
+   <td>color
+   </td>
+   <td>OPTIONAL. RGB color to use for the node.
+   </td>
+  </tr>
+  <tr>
+   <td>seed
+   </td>
+   <td>OPTIONAL. Seed vertex/channel of the node/region
+   </td>
+  </tr>
+  <tr>
+   <td>region
+   </td>
+   <td>OPTIONAL. “XY”, where X can be L:left, R:right, B:bilateral, and Y can be F:frontal, T:temporal, P:parietal, O:occipital
+   </td>
+  </tr>
+</table>
   
 Example:
 ```Text
-index	label	network_label	hemisphere	…
-1	Heschl’ Gyrus	Somatomotor	left	…
-2	Heschl’ Gyrus	Somatomotor	right	…
+index	label	network_label	hemisphere
+1	Heschl’ Gyrus	Somatomotor	left
+2	Heschl’ Gyrus	Somatomotor	right
 ```
 
 The `[probseg|dseg|mask].json` file provides metadata to uniquely identify, describe and characterize the atlas, as well as give proper attribution to the creators. Additionally, SpatialReference serves the important purpose of unambiguously identifying the space the atlas is labeled in.
 
-insert missing table 2 from Google doc here
+<table>
+  <tr>
+   <td>Name
+   </td>
+   <td>REQUIRED. Name of the atlas
+   </td>
+  </tr>
+  <tr>
+   <td>Description
+   </td>
+   <td>RECOMMENDED. Longform description of the atlas
+   </td>
+  </tr>
+  <tr>
+   <td>SpatialReference
+   </td>
+   <td>RECOMMENDED. Point to an existing atlas in a template space (url or relative file path where this file is located).
+   </td>
+  </tr>
+  <tr>
+   <td>Resolution
+   </td>
+   <td>RECOMMENDED. Resolution atlas is provided in.
+   </td>
+  </tr>
+  <tr>
+   <td>Dimensions
+   </td>
+   <td>RECOMMENDED. Dimensions of the atlas, MUST be 3 (for deterministic atlases) or 4 (for probabilistic atlases).
+   </td>
+  </tr>
+  <tr>
+   <td>4thDimension
+   </td>
+   <td>OPTIONAL. RECOMMENDED if probabilistic atlas. Should indicate what the 4th dimension entails/refers to. MUST be “Indices” or   .
+   </td>
+  </tr>
+  <tr>
+   <td>CoordinateReportStrategy
+   </td>
+   <td>OPTIONAL. MUST BE ONE OF: “peak”, “center_of_mass”, “other”. Indicate the method of coordinate reporting in statistically significant clusters. Could be the “peak” statistical coordinate in the cluster or the “center_of_mass” of the cluster. RECOMMENDED if x, y ,z values are set in the .tsv file. 
+   </td>
+  </tr>
+  <tr>
+   <td>Authors
+   </td>
+   <td>RECOMMENDED. List of the authors involved in the creation of the atlas
+   </td>
+  </tr>
+  <tr>
+   <td>Curators
+   </td>
+   <td>RECOMMENDED. List of curators who helped make the atlas accessible in a database or dataset
+   </td>
+  </tr>
+  <tr>
+   <td>Funding
+   </td>
+   <td>RECOMMENDED. The funding source(s) involved in the atlas creation
+   </td>
+  </tr>
+  <tr>
+   <td>License
+   </td>
+   <td>RECOMMENDED. The license agreement for using the atlas.
+   </td>
+  </tr>
+  <tr>
+   <td>ReferencesAndLinks
+   </td>
+   <td>RECOMMENDED. A list of relevant references and links pertaining to the atlas.
+   </td>
+  </tr>
+  <tr>
+   <td>Species
+   </td>
+   <td>RECOMMENDED. The species the atlas was derived from. For example, could be Human, Macaque, Rat, Mouse, etc.
+   </td>
+  </tr>
+  <tr>
+   <td>DerivedFrom
+   </td>
+   <td>RECOMMENDED. Indicate what data modality the atlas was derived from, e.g. "cytoarchitecture", "resting-state", "task".
+   </td>
+  </tr>
+  <tr>
+   <td>LevelType
+   </td>
+   <td>RECOMMENDED. Indicate what analysis level the atlas was derived from, e.g. "group", "individual".
+   </td>
+  </tr>
+</table>
+
+
 
 Example:
 
@@ -341,28 +504,28 @@ bids/atlas/atlas-ps13/
 
 ### Case 2: regional analysis (voxels/vertices are averaged per regions from dseg/probseg)
 
-Example directory content for a quantitative atlas that provides values for certain ROIs only:
+Example directory content for a quantitative atlas that provides values for certain ROIs only, in this case defined by the AAL atlas:
 
 ```Text
 bids/atlas/
 	atlas-mni305/
 		atlas-aparc.DKTatlas+aseg.mgz
-		atlas-aparc.DKTatlas+aseg.tsv
+		atlas-aparc.DKTatlas+aseg.tsv 
 		atlas-RB_all_2008-03-26.probseg.gca
 		atlas-RB_all_2008-03-26.probseg.tsv
 	atlas-ps13/
-	  	atlas-ps13_space-fsaverage_hemi-L_stat-mean_meas-VT_mimap.json
-        atlas-ps13_space-fsaverage-hemi-L_stat-mean_meas-VT_mimap.tsv
-        atlas-ps13_space-fsaverage-hemi-L_stat-std_meas-VT_mimap.json
-       	atlas-ps13_space-fsaverage-hemi-L_stat-std_meas-VT_mimap.tsv
-       	atlas-ps13_space-fsaverage-hemi-R_stat-mean_meas-VT_mimap.json
-       	atlas-ps13_space-fsaverage-hemi-R_stat-mean_meas-VT_mimap.tsv
-		atlas-ps13_space-fsaverage-hemi-R_stat-std_meas-VT_mimap.json
-		atlas-ps13_space-fsaverage-hemi-R_stat-std_meas-VT_mimap.tsv
-		atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_mimap.json
-		atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_mimap.tsv
-		atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_mimap.json
-		atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_mimap.tsv
+	  	atlas-ps13_space-fsaverage_hemi-L_stat-mean_meas-VT_seg-AAL_mimap.json
+        atlas-ps13_space-fsaverage-hemi-L_stat-mean_meas-VT_seg-AAL_mimap.tsv
+        atlas-ps13_space-fsaverage-hemi-L_stat-std_meas-VT_seg-AAL_mimap.json
+       	atlas-ps13_space-fsaverage-hemi-L_stat-std_meas-VT_seg-AAL_mimap.tsv
+       	atlas-ps13_space-fsaverage-hemi-R_stat-mean_meas-VT_seg-AAL_mimap.json
+       	atlas-ps13_space-fsaverage-hemi-R_stat-mean_meas-VT_seg-AAL_mimap.tsv
+		atlas-ps13_space-fsaverage-hemi-R_stat-std_meas-VT_seg-AAL_mimap.json
+		atlas-ps13_space-fsaverage-hemi-R_stat-std_meas-VT_seg-AAL_mimap.tsv
+		atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_seg-AAL_mimap.json
+		atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_seg-AAL_mimap.tsv
+		atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_seg-AAL_mimap.json
+		atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_seg-AAL_mimap.tsv
 ```
 
 Note that there is no image file present in a regional qunatitative atlas. The json file accompanying the quantitative atlas should include the information as in [Single existing atlas in template space](#_Single_existing_atlas_in_template_space).
\ No newline at end of file

From 11ed800bd5c28381293d92501530c6558c565415 Mon Sep 17 00:00:00 2001
From: PeerHerholz <herholz.peer@gmail.com>
Date: Thu, 25 Jan 2024 12:26:09 +0100
Subject: [PATCH 06/16] 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
 <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

From 1129d8dc8e8be0a49a67e3f66ba9bcb5c68e2558 Mon Sep 17 00:00:00 2001
From: PeerHerholz <herholz.peer@gmail.com>
Date: Thu, 25 Jan 2024 15:02:23 +0100
Subject: [PATCH 07/16] 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-<label>_space-<label>_res-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|.tsv][.gz]
 	atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].tsv
 	atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].json
-	atlas-<label>_space-<label>_desc-<label>_edges.[tck|<eeg,meg>]
 ```
 
 #### Case 2 

From 6881c9cb71fed83348ef391d91c98d05562a3044 Mon Sep 17 00:00:00 2001
From: Cyril Pernet <wamcyril@gmail.com>
Date: Wed, 31 Jan 2024 17:12:04 +0100
Subject: [PATCH 08/16] add ref to template and lnter

---
 src/schema/objects/entities.yaml | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

diff --git a/src/schema/objects/entities.yaml b/src/schema/objects/entities.yaml
index 29ea8f43e3..b6463e710a 100644
--- a/src/schema/objects/entities.yaml
+++ b/src/schema/objects/entities.yaml
@@ -29,11 +29,18 @@ atlas:
   name: atlas
   display_name: Atlas
   description: |
-  The definition of atlas per Merriam-Webster is ‘a bound collection of maps (i.e. labeled brain regions or quantitative aspects) and metadata (tables, or textual matter). 
-
-  Within BIDS atlases are broadly defined as a mapping between locations in a spatial coordinate systems and descriptions associated with those locations. By analogy with geographical atlases, brain atlases can map brain locations to either discrete labels like a map of countries does, or to continuous quantities like a topographic map does.
-
-  This comprises all possible types of atlases, specifically deterministic, probabilistic, and mask/voxel-based ones, and quantitative maps from various modalities including but not limited to: structural features (e.g. myelination, cytoarchitecture), functional features (e.g. resting-state networks, localizers) and such based on multimodal data integration (e.g. gene expression, receptors). Furthermore, it covers both volume/voxel and surface/vertex data, as well as gray and white matter atlases.
+  The definition of atlas per Merriam-Webster is ‘a bound collection of maps (i.e. labeled brain regions
+  or quantitative aspects) and metadata (tables, or textual matter). Within BIDS, atlases are broadly 
+  defined as a mapping between locations in a spatial coordinate systems and descriptions associated with
+  those locations. Atlases are often build from registering many subjects or maps to a template. By analogy
+  with geographical atlases, brain atlases can map brain locations to either discrete labels like a map 
+  of countries does, or to continuous quantities like a topographic map does. 
+
+  This comprises all possible types of atlases, specifically deterministic, probabilistic, and mask/voxel-based
+  ones, and quantitative maps from various modalities including but not limited to structural features (e.g. 
+  myelination, cytoarchitecture), functional features (e.g. resting-state networks, localizers) and such based on 
+  multimodal data integration (e.g. gene expression, receptors). Furthermore, it covers both volume/voxel and 
+  surface/vertex data, as well as gray and white matter atlases.
 ceagent:
   name: ce
   display_name: Contrast Enhancing Agent

From e2b3ddbfceb9643755a59d4eacf62ecc5e459182 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Tue, 6 Feb 2024 11:56:24 -0500
Subject: [PATCH 09/16] Remove trailing whitespace, normalize indentation to
 two spaces

---
 src/atlas.md | 358 +++++++++++++++++++++++++--------------------------
 1 file changed, 179 insertions(+), 179 deletions(-)

diff --git a/src/atlas.md b/src/atlas.md
index d3203e02fb..407b86a82c 100644
--- a/src/atlas.md
+++ b/src/atlas.md
@@ -1,16 +1,16 @@
 # 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. 
+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](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). 
+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. 
+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`.
@@ -18,27 +18,27 @@ In cases where an atlas has multiple versions, as in "release", and sub-versions
 
 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. 
+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.
 
 ### 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, 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
-<dataset>/atlas/ 
+<dataset>/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), 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
 <dataset>/atlas/atlas-<label>/
-	atlas-<label>_space-<label>[_desc-<label>]_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii][.gz]
-	atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].tsv
-	atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].json
+  atlas-<label>_space-<label>[_desc-<label>]_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii][.gz]
+  atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].tsv
+  atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].json
 ```
 
 ### Representing an atlas within a dataset
@@ -47,36 +47,36 @@ Besides this default and required storage of the non-altered atlas at the root d
 
 #### Case 1
 
-First, a given atlas underwent modifications before its utilization, specifically spatial transformations to a template space and is used in this form within a given pipeline. In this case, the respective BIDS-Atlas files will be stored at both the BIDS root level and the given pipeline directory under `derivatives`. Files stored at the BIDS root level will follow the structure outlined in option 1, while files stored at the pipeline level will follow the respective naming conventions. For example, if an atlas was spatially transformed to a certain MNI template, then the BIDS-Atlas files will be stored within the respective pipeline directory and the corresponding [space](schema/objects/entities.yaml#space)-<label> identifier will be adapted accordingly. 
+First, a given atlas underwent modifications before its utilization, specifically spatial transformations to a template space and is used in this form within a given pipeline. In this case, the respective BIDS-Atlas files will be stored at both the BIDS root level and the given pipeline directory under `derivatives`. Files stored at the BIDS root level will follow the structure outlined in option 1, while files stored at the pipeline level will follow the respective naming conventions. For example, if an atlas was spatially transformed to a certain MNI template, then the BIDS-Atlas files will be stored within the respective pipeline directory and the corresponding [space](schema/objects/entities.yaml#space)-<label> identifier will be adapted accordingly.
 
 ```Text
 <dataset>/atlas/atlas-<label>/
-	atlas-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii][.gz]
-	atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv
-	atlas-<label>_desc-<label>_[dseg|probseg|mask].json
+  atlas-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii][.gz]
+  atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv
+  atlas-<label>_desc-<label>_[dseg|probseg|mask].json
 
 <dataset>/derivatives/<pipeline>/
-	atlas-<label>_space-<label>_res-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|.tsv][.gz]
-	atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].tsv
-	atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].json
+  atlas-<label>_space-<label>_res-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|.tsv][.gz]
+  atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].tsv
+  atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].json
 ```
 
-#### Case 2 
+#### 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 referring 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>/
-	atlas-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii][.gz]
-	atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv
-	atlas-<label>_desc-<label>_[dseg|probseg|mask].json
+  atlas-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii][.gz]
+  atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv
+  atlas-<label>_desc-<label>_[dseg|probseg|mask].json
 
 <dataset>/derivatives/
-	sub-01/
-		func/
-		sub-01_space-<label>_seg-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz]
-		sub-01_space-<label>_seg-<label>_desc-<label>_[dseg|probseg|mask].tsv
-		sub-01_space-<label>_seg-<label>_desc-<label>_[dseg|probseg|mask].json
+  sub-01/
+    func/
+      sub-01_space-<label>_seg-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz]
+      sub-01_space-<label>_seg-<label>_desc-<label>_[dseg|probseg|mask].tsv
+      sub-01_space-<label>_seg-<label>_desc-<label>_[dseg|probseg|mask].json
 ```
 
 #### Case 3
@@ -85,12 +85,12 @@ Third, a given atlas was derived from the corresponding subject’s data and thu
 
 ```Text
 <dataset>/derivatives/
-	sub-01/
-		anat/		
-			sub-01_atlas-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz][.ome-tiff|.png]
-			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
+  sub-01/
+    anat/
+      sub-01_atlas-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz][.ome-tiff|.png]
+      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
@@ -100,9 +100,9 @@ The `[probseg|dseg|mask].[nii|dlabel.nii|label.gii][.gz]` file represents the lo
 1. [_dseg](schema/objects/suffixes.yaml#dseg): Each node is labeled with a unique integer corresponding to its row/index in the tsv sidecar.
 2. [_probseg](schema/objects/suffixes.yaml#probseg): Each node is represented along an additional dimension of the file (e.g., a 4D nifti file where each volume represents a node) and its position in that dimension corresponds to its row/index in the tsv sidecar.
 3. [_mask](schema/objects/suffixes.yaml#mask): Either each voxel represents a node or the entire mask is a single node. How the mask should be interpreted is determined by other specifications. Based on these options, an atlas can take the following forms in the here proposed specification (non-exhaustive list):
-a.	A 3D nifti file with unique integers defining nodes
-b.	A 4D binary nifti file with spatially overlapping nodes in each volume (along the 4th dimension)
-c.	A 4D nifti file with overlapping nodes with continuous values for each voxel within a volume
+a.  A 3D nifti file with unique integers defining nodes
+b.  A 4D binary nifti file with spatially overlapping nodes in each volume (along the 4th dimension)
+c.  A 4D nifti file with overlapping nodes with continuous values for each voxel within a volume
 
 Examples:
 ```Text
@@ -143,7 +143,7 @@ The `[probseg|dseg|mask|channels].tsv` file indexes and labels each node/parcel/
   <tr>
    <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>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>
   </tr>
   <tr>
@@ -189,12 +189,12 @@ The `[probseg|dseg|mask|channels].tsv` file indexes and labels each node/parcel/
    </td>
   </tr>
 </table>
-  
+
 Example:
 ```Text
 index	label	network_label	hemisphere
-1	Heschl’ Gyrus	Somatomotor	left
-2	Heschl’ Gyrus	Somatomotor	right
+1	Heschl's Gyrus	Somatomotor	left
+2	Heschl's Gyrus	Somatomotor	right
 ```
 
 The `[probseg|dseg|mask].json` file provides metadata to uniquely identify, describe and characterize the atlas, as well as give proper attribution to the creators. Additionally, SpatialReference serves the important purpose of unambiguously identifying the space the atlas is labeled in.
@@ -239,7 +239,7 @@ The `[probseg|dseg|mask].json` file provides metadata to uniquely identify, desc
   <tr>
    <td>CoordinateReportStrategy
    </td>
-   <td>OPTIONAL. MUST BE ONE OF: “peak”, “center_of_mass”, “other”. Indicate the method of coordinate reporting in statistically significant clusters. Could be the “peak” statistical coordinate in the cluster or the “center_of_mass” of the cluster. RECOMMENDED if x, y ,z values are set in the .tsv file. 
+   <td>OPTIONAL. MUST BE ONE OF: “peak”, “center_of_mass”, “other”. Indicate the method of coordinate reporting in statistically significant clusters. Could be the “peak” statistical coordinate in the cluster or the “center_of_mass” of the cluster. RECOMMENDED if x, y ,z values are set in the .tsv file.
    </td>
   </tr>
   <tr>
@@ -298,28 +298,28 @@ Example:
 
 ```JSON
 {
-  	"Name": "FSL's MNI ICBM 152 non-linear 6th Generation Asymmetric Average Brain Stereotaxic Registration Model",
- 	"Authors": [
-		"David Kennedy",
-		"Christian Haselgrove",
-		"Bruce Fischl",
-		"Janis Breeze",
-		"Jean Frazie", 
-		"Larry Seidman",
-		"Jill Goldstein"
-				],
- 	"BIDSVersion": "1.1.0",
- 	"Curators": "FSL team",
-	"SpatialReference": "https://templateflow.s3.amazonaws.com/tpl-MNI152NLin6Asym_res-02_T1w.nii.gz",
- 	"Space": "MNI152NLin6Asym",
-	"Resolution": "Matched with original template resolution (2x2x3 mm^3)", 
- 	"License": "See LICENSE file",
-	"RRID": "SCR_002823",
-  	"ReferencesAndLinks": [
-	"https://doi.org/10.1016/j.neuroimage.2012.01.024",
-	"https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Atlases"
-		],
-  	"Species": "Human"
+  "Name": "FSL's MNI ICBM 152 non-linear 6th Generation Asymmetric Average Brain Stereotaxic Registration Model",
+  "Authors": [
+    "David Kennedy",
+    "Christian Haselgrove",
+    "Bruce Fischl",
+    "Janis Breeze",
+    "Jean Frazie",
+    "Larry Seidman",
+    "Jill Goldstein"
+  ],
+  "BIDSVersion": "1.1.0",
+  "Curators": "FSL team",
+  "SpatialReference": "https://templateflow.s3.amazonaws.com/tpl-MNI152NLin6Asym_res-02_T1w.nii.gz",
+  "Space": "MNI152NLin6Asym",
+  "Resolution": "Matched with original template resolution (2x2x3 mm^3)",
+  "License": "See LICENSE file",
+  "RRID": "SCR_002823",
+  "ReferencesAndLinks": [
+    "https://doi.org/10.1016/j.neuroimage.2012.01.024",
+    "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Atlases"
+  ],
+  "Species": "Human"
 }
 ```
 
@@ -328,13 +328,13 @@ Within the following, multiple examples showcasing the proposed extension are pr
 
 ## Atlas as dataset - single existing atlas in template space
 
-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.  
+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/atlas-HarvardOxford/
-	atlas-HarvardOxford_res-2_dseg.json
-	atlas-HarvardOxford_res-2_dseg.nii.gz
-	atlas-HarvardOxford_res-2_dseg.tsv
+  atlas-HarvardOxford_res-2_dseg.json
+  atlas-HarvardOxford_res-2_dseg.nii.gz
+  atlas-HarvardOxford_res-2_dseg.tsv
 ```
 
 The content of each file is further outlined in the following, starting with the .json sidecar file containing meta-data about the atlas at hand.
@@ -343,32 +343,32 @@ Example content of the `atlas-HarvardOxford_res-2_dseg.json` file:
 
 ```JSON
 {
- 	"Authors": [
-		"David Kennedy",
-		"Christian Haselgrove",
-		"Bruce Fischl",
-		"Janis Breeze",
-		"Jean Frazie", 
-		"Larry Seidman",
-		"Jill Goldstein"
-				],
- 	"BIDSVersion": "1.1.0",
- 	"Curators": "FSL team",
-	"SpatialReference": "https://templateflow.s3.amazonaws.com/tpl-MNI152NLin6Asym_res-02_T1w.nii.gz",
- 	"Space": "MNI152NLin6Asym",
-"	Resolution": "Matched with original template resolution (2x2x3 mm^3)", 
- 	"License": "See LICENSE file",
-  	"Name": "FSL's MNI ICBM 152 non-linear 6th Generation Asymmetric Average Brain Stereotaxic Registration Model",
-	"RRID": "SCR_002823",
-  	"ReferencesAndLinks": [
-	"https://doi.org/10.1016/j.neuroimage.2012.01.024",
-	"https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Atlases"
-		],
-  	"Species": "Human"
+  "Authors": [
+    "David Kennedy",
+    "Christian Haselgrove",
+    "Bruce Fischl",
+    "Janis Breeze",
+    "Jean Frazie",
+    "Larry Seidman",
+    "Jill Goldstein"
+  ],
+  "BIDSVersion": "1.1.0",
+  "Curators": "FSL team",
+  "SpatialReference": "https://templateflow.s3.amazonaws.com/tpl-MNI152NLin6Asym_res-02_T1w.nii.gz",
+  "Space": "MNI152NLin6Asym",
+  "Resolution": "Matched with original template resolution (2x2x3 mm^3)",
+  "License": "See LICENSE file",
+    "Name": "FSL's MNI ICBM 152 non-linear 6th Generation Asymmetric Average Brain Stereotaxic Registration Model",
+  "RRID": "SCR_002823",
+  "ReferencesAndLinks": [
+    "https://doi.org/10.1016/j.neuroimage.2012.01.024",
+    "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Atlases"
+  ],
+  "Species": "Human"
 }
 ```
 
-Next, the content of the tsv files describing the indices and corresponding labels present in the atlas at hand. 
+Next, the content of the tsv files describing the indices and corresponding labels present in the atlas at hand.
 
 Example content of the `atlas-HarvardOxford_res-2_dseg.tsv` file:
 
@@ -390,22 +390,22 @@ The example below illustrates how multiple existing atlases in the same template
 
 ```Text
 bids/atlases/
-	atlas-HarvardOxford/
-		atlas-HarvardOxford_dseg.nii.gz
-		atlas-HarvardOxford_dseg.json
-		atlas-HarvardOxford_dseg.tsv
-	atlas-Schaefer400/
-		atlas-Schaefer400_dseg.nii.gz
-		atlas-Schaefer400_dseg.json
-		atlas-Schaefer400_dseg.tsv
-	atlas-Yeo17/
-		atlas-Yeo17_dseg.nii.gz
-		atlas-Yeo17_dseg.json
-		atlas-Yeo17_dseg.tsv
-	atlas-msdl/
-		atlas-msdl_probseg.nii.gz
-		atlas-msdl_probseg.json
-		atlas-msdl_probseg.tsv
+  atlas-HarvardOxford/
+    atlas-HarvardOxford_dseg.nii.gz
+    atlas-HarvardOxford_dseg.json
+    atlas-HarvardOxford_dseg.tsv
+  atlas-Schaefer400/
+    atlas-Schaefer400_dseg.nii.gz
+    atlas-Schaefer400_dseg.json
+    atlas-Schaefer400_dseg.tsv
+  atlas-Yeo17/
+    atlas-Yeo17_dseg.nii.gz
+    atlas-Yeo17_dseg.json
+    atlas-Yeo17_dseg.tsv
+  atlas-msdl/
+    atlas-msdl_probseg.nii.gz
+    atlas-msdl_probseg.json
+    atlas-msdl_probseg.tsv
 ```
  
 ## Single existing atlas transformed to subject space
@@ -414,16 +414,16 @@ The example below illustrates how a single existing atlas transformed into a sub
 
 ```Text
 bids/atlases/atlas-HarvardOxford/
-	atlas-HarvardOxford_dseg.json
-	atlas-HarvardOxford_dseg.tsv
-	atlas-HavardOxford2_dseg.nii.gz
+  atlas-HarvardOxford_dseg.json
+  atlas-HarvardOxford_dseg.tsv
+  atlas-HavardOxford2_dseg.nii.gz
 bids/derivatives/pipeline-<name>/
-	sub-01/
-		anat/
-  			sub-01_T1w.nii.gz
-		  	sub-01_space-T1w_seg-HarvardOxfordThr50_res-2_dseg.nii.gz	
-  			sub-01_space-T1w_seg-HarvardOxfordThr50_res-2_dseg.json
-  			sub-01_space-T1w_seg-HarvardOxfordThr50_res-2_dseg.tsv
+  sub-01/
+    anat/
+      sub-01_T1w.nii.gz
+      sub-01_space-T1w_seg-HarvardOxfordThr50_res-2_dseg.nii.gz
+      sub-01_space-T1w_seg-HarvardOxfordThr50_res-2_dseg.json
+      sub-01_space-T1w_seg-HarvardOxfordThr50_res-2_dseg.tsv
 ```
 
 The json file accompanying the transformed atlas should include the following information.
@@ -432,12 +432,12 @@ Example content of the `sub-01_space-T1w_seg-HarvardOxford_res-2_dseg.json` file
 
 ```JSON
 {
- 	"BIDSVersion": "1.1.0",
-	"SpatialReference": "sub-01/anat/sub-01_T1w.nii.gz",
- 	"Space": "T1w",
-	"Resolution": "Matched with original resolution in subject T1w space (1x1x1 mm^3)", 
-	"Sources": [],
-	"transformation":
+  "BIDSVersion": "1.1.0",
+  "SpatialReference": "sub-01/anat/sub-01_T1w.nii.gz",
+  "Space": "T1w",
+  "Resolution": "Matched with original resolution in subject T1w space (1x1x1 mm^3)",
+  "Sources": [],
+  "transformation":
 }
 ```
 
@@ -447,20 +447,20 @@ The example below illustrates how two atlases, an individual surface-based corti
 
 ```Text
 bids/atlases/atlas-FreeSurferASEG/
-	atlas-FreeSurferASEG_dseg.json
-	atlas-FreeSurferASEG_dseg.tsv
-	atlas-FreeSurferASEG_dseg.nii.gz
+  atlas-FreeSurferASEG_dseg.json
+  atlas-FreeSurferASEG_dseg.tsv
+  atlas-FreeSurferASEG_dseg.nii.gz
 
 bids/derivatives/pipeline-<name>/
-	sub-01/
-		anat/
-			sub-01_space-T1w_seg-FreeSurferASEG_res-2_dseg.nii.gz	
-  			sub-01_space-T1w_seg-FreeSurferASEG_res-2_dseg.json
-  			sub-01_space-T1w_seg-FreeSurferASEG_res-2_dseg.tsv
-		func/
- 			sub-01_space-FSlr_seg-Russome_res-2_dseg.nii.gz	
-  			sub-01_space-FSlr_seg-Russome_res-2_dseg.json
-  			sub-01_space-FSlr_seg-Russome_res-2_dseg.tsv
+  sub-01/
+    anat/
+      sub-01_space-T1w_seg-FreeSurferASEG_res-2_dseg.nii.gz
+      sub-01_space-T1w_seg-FreeSurferASEG_res-2_dseg.json
+      sub-01_space-T1w_seg-FreeSurferASEG_res-2_dseg.tsv
+    func/
+      sub-01_space-FSlr_seg-Russome_res-2_dseg.nii.gz
+      sub-01_space-FSlr_seg-Russome_res-2_dseg.json
+      sub-01_space-FSlr_seg-Russome_res-2_dseg.tsv
 ```
 
 The json file accompanying the functionally derived atlas should include the following information.
@@ -469,26 +469,26 @@ Example content of the `sub-01_task-rest_atlas.json` file contains top-level met
 
 ```JSON
 
-"Atlas": 
+"Atlas":
 {
-	"Russome": 
-	{
-	"Atlasfile": "/link/to/russome/file", 
-	"Extra": "individualized surface parcellation"
-	},
-	"FS_aseg": {
-	"Atlasfile": "/link/to/aseg/file", 
-	"Extra": "freesurfer aseg"
-	}
-} 
+  "Russome":
+  {
+    "Atlasfile": "/link/to/russome/file",
+    "Extra": "individualized surface parcellation"
+  },
+  "FS_aseg": {
+    "Atlasfile": "/link/to/aseg/file",
+    "Extra": "freesurfer aseg"
+  }
+}
 
 ```
 
-## Quantitative atlas examples 
+## Quantitative atlas examples
 
-The example below is for PET imaging, but this applies to any quantitative mapping (PET or QMRI). Compared to anatomical atlases, quantitative atlases give reference values to be compared with. Such values can be derived voxel/vertex wise (see case 1) or per region of interest (ROI) (see case 2). In the latter case, ROIs are generally derived from an anatomical atlas. 
+The example below is for PET imaging, but this applies to any quantitative mapping (PET or QMRI). Compared to anatomical atlases, quantitative atlases give reference values to be compared with. Such values can be derived voxel/vertex wise (see case 1) or per region of interest (ROI) (see case 2). In the latter case, ROIs are generally derived from an anatomical atlas.
 
-We created a Molecular Imaging Brain Atlases (MIBA) from 16 subjects who underwent a [11C]PS13 PET scan, a radioligand that quantifies cyclooxygenase-1 (see [source data](https://openneuro.org/datasets/ds004332/versions/1.0.2)). Our atlas consists of mean and standard deviations of PS13 target distribution volumes (VT) computed across the 16 subjects at each voxel, in standard MRI spaces. We also project these distribution volumes onto the freesurfer cortical surfaces and include these as well.  The goal is to allow researchers with MRI-only data to correlate their results to the distribution volume of PS13. The dataset can be found [here](https://openneuro.org/datasets/ds004401/versions/1.1.0). 
+We created a Molecular Imaging Brain Atlases (MIBA) from 16 subjects who underwent a [11C]PS13 PET scan, a radioligand that quantifies cyclooxygenase-1 (see [source data](https://openneuro.org/datasets/ds004332/versions/1.0.2)). Our atlas consists of mean and standard deviations of PS13 target distribution volumes (VT) computed across the 16 subjects at each voxel, in standard MRI spaces. We also project these distribution volumes onto the freesurfer cortical surfaces and include these as well.  The goal is to allow researchers with MRI-only data to correlate their results to the distribution volume of PS13. The dataset can be found [here](https://openneuro.org/datasets/ds004401/versions/1.1.0).
 
 ### Case 1: voxel/vertex wise analysis
 
@@ -496,18 +496,18 @@ Example directory content for a quantitative atlas that provides values at all v
 
 ```Text
 bids/atlas/atlas-ps13/
-		atlas-ps13_space-fsaverage_hemi-L_stat-mean_meas-VT_mimap.json
-       	atlas-ps13_space-fsaverage_hemi-L_stat-mean_meas-VT_mimap.nii.gz
-       	atlas-ps13_space-fsaverage_hemi-R_stat-mean_meas-VT_mimap.json
-       	atlas-ps13_space-fsaverage_hemi-R_stat-mean_meas-VT_mimap.nii.gz
-	  	atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_mimap.json
-       	atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_mimap.nii.gz 
-       	atlas-ps13_space-fsaverage_hemi-L_stat-std_meas-VT_mimap.json
-		atlas-ps13_space-fsaverage_hemi-L_stat-std_meas-VT_mimap.nii.gz
-		atlas-ps13_space-fsaverage_hemi-R_stat-std_meas-VT_mimap.json
-		atlas-ps13_space-fsaverage_hemi-R_stat-std_meas-VT_mimap.nii.gz
-		atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_mimap.json
-		atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_mimap.nii.gz
+    atlas-ps13_space-fsaverage_hemi-L_stat-mean_meas-VT_mimap.json
+    atlas-ps13_space-fsaverage_hemi-L_stat-mean_meas-VT_mimap.nii.gz
+    atlas-ps13_space-fsaverage_hemi-R_stat-mean_meas-VT_mimap.json
+    atlas-ps13_space-fsaverage_hemi-R_stat-mean_meas-VT_mimap.nii.gz
+    atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_mimap.json
+    atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_mimap.nii.gz
+    atlas-ps13_space-fsaverage_hemi-L_stat-std_meas-VT_mimap.json
+    atlas-ps13_space-fsaverage_hemi-L_stat-std_meas-VT_mimap.nii.gz
+    atlas-ps13_space-fsaverage_hemi-R_stat-std_meas-VT_mimap.json
+    atlas-ps13_space-fsaverage_hemi-R_stat-std_meas-VT_mimap.nii.gz
+    atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_mimap.json
+    atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_mimap.nii.gz
 ```
 
 ### Case 2: regional analysis (voxels/vertices are averaged per regions from dseg/probseg)
@@ -516,24 +516,24 @@ Example directory content for a quantitative atlas that provides values for cert
 
 ```Text
 bids/atlas/
-	atlas-mni305/
-		atlas-aparc.DKTatlas+aseg.mgz
-		atlas-aparc.DKTatlas+aseg.tsv 
-		atlas-RB_all_2008-03-26.probseg.gca
-		atlas-RB_all_2008-03-26.probseg.tsv
-	atlas-ps13/
-	  	atlas-ps13_space-fsaverage_hemi-L_stat-mean_meas-VT_seg-AAL_mimap.json
-        atlas-ps13_space-fsaverage-hemi-L_stat-mean_meas-VT_seg-AAL_mimap.tsv
-        atlas-ps13_space-fsaverage-hemi-L_stat-std_meas-VT_seg-AAL_mimap.json
-       	atlas-ps13_space-fsaverage-hemi-L_stat-std_meas-VT_seg-AAL_mimap.tsv
-       	atlas-ps13_space-fsaverage-hemi-R_stat-mean_meas-VT_seg-AAL_mimap.json
-       	atlas-ps13_space-fsaverage-hemi-R_stat-mean_meas-VT_seg-AAL_mimap.tsv
-		atlas-ps13_space-fsaverage-hemi-R_stat-std_meas-VT_seg-AAL_mimap.json
-		atlas-ps13_space-fsaverage-hemi-R_stat-std_meas-VT_seg-AAL_mimap.tsv
-		atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_seg-AAL_mimap.json
-		atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_seg-AAL_mimap.tsv
-		atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_seg-AAL_mimap.json
-		atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_seg-AAL_mimap.tsv
+  atlas-mni305/
+    atlas-aparc.DKTatlas+aseg.mgz
+    atlas-aparc.DKTatlas+aseg.tsv
+    atlas-RB_all_2008-03-26.probseg.gca
+    atlas-RB_all_2008-03-26.probseg.tsv
+  atlas-ps13/
+    atlas-ps13_space-fsaverage_hemi-L_stat-mean_meas-VT_seg-AAL_mimap.json
+    atlas-ps13_space-fsaverage-hemi-L_stat-mean_meas-VT_seg-AAL_mimap.tsv
+    atlas-ps13_space-fsaverage-hemi-L_stat-std_meas-VT_seg-AAL_mimap.json
+    atlas-ps13_space-fsaverage-hemi-L_stat-std_meas-VT_seg-AAL_mimap.tsv
+    atlas-ps13_space-fsaverage-hemi-R_stat-mean_meas-VT_seg-AAL_mimap.json
+    atlas-ps13_space-fsaverage-hemi-R_stat-mean_meas-VT_seg-AAL_mimap.tsv
+    atlas-ps13_space-fsaverage-hemi-R_stat-std_meas-VT_seg-AAL_mimap.json
+    atlas-ps13_space-fsaverage-hemi-R_stat-std_meas-VT_seg-AAL_mimap.tsv
+    atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_seg-AAL_mimap.json
+    atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_seg-AAL_mimap.tsv
+    atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_seg-AAL_mimap.json
+    atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_seg-AAL_mimap.tsv
 ```
 
-Note that there is no image file present in a regional qunatitative atlas. The json file accompanying the quantitative atlas should include the information as in [Single existing atlas in template space](#_Single_existing_atlas_in_template_space).
\ No newline at end of file
+Note that there is no image file present in a regional qunatitative atlas. The json file accompanying the quantitative atlas should include the information as in [Single existing atlas in template space](#_Single_existing_atlas_in_template_space).

From f7a268da719fd3cf4888e78308504ce81bd333f0 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Tue, 6 Feb 2024 12:09:42 -0500
Subject: [PATCH 10/16] Run codespell and aspell

---
 src/atlas.md | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/src/atlas.md b/src/atlas.md
index 407b86a82c..40f74d55e8 100644
--- a/src/atlas.md
+++ b/src/atlas.md
@@ -25,7 +25,7 @@ BIDS-Atlas focuses on the utilization of atlases while also allowing their shari
 
 ### 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, 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 directory and everything else is under derivatives. This allows validating any
 
 ```Text
 <dataset>/atlas/
@@ -98,11 +98,11 @@ Third, a given atlas was derived from the corresponding subject’s data and thu
 The `[probseg|dseg|mask].[nii|dlabel.nii|label.gii][.gz]` file represents the location and extent of the nodes/parcels/regions within the atlas. Different file types are supported based on the modality and atlas at hand. In more detail, this encompasses the following three options:
 
 1. [_dseg](schema/objects/suffixes.yaml#dseg): Each node is labeled with a unique integer corresponding to its row/index in the tsv sidecar.
-2. [_probseg](schema/objects/suffixes.yaml#probseg): Each node is represented along an additional dimension of the file (e.g., a 4D nifti file where each volume represents a node) and its position in that dimension corresponds to its row/index in the tsv sidecar.
+2. [_probseg](schema/objects/suffixes.yaml#probseg): Each node is represented along an additional dimension of the file (e.g., a 4D NIfTI file where each volume represents a node) and its position in that dimension corresponds to its row/index in the tsv sidecar.
 3. [_mask](schema/objects/suffixes.yaml#mask): Either each voxel represents a node or the entire mask is a single node. How the mask should be interpreted is determined by other specifications. Based on these options, an atlas can take the following forms in the here proposed specification (non-exhaustive list):
-a.  A 3D nifti file with unique integers defining nodes
-b.  A 4D binary nifti file with spatially overlapping nodes in each volume (along the 4th dimension)
-c.  A 4D nifti file with overlapping nodes with continuous values for each voxel within a volume
+a.  A 3D NIfTI file with unique integers defining nodes
+b.  A 4D binary NIfTI file with spatially overlapping nodes in each volume (along the 4th dimension)
+c.  A 4D NIfTI file with overlapping nodes with continuous values for each voxel within a volume
 
 Examples:
 ```Text
@@ -215,7 +215,7 @@ The `[probseg|dseg|mask].json` file provides metadata to uniquely identify, desc
   <tr>
    <td>SpatialReference
    </td>
-   <td>RECOMMENDED. Point to an existing atlas in a template space (url or relative file path where this file is located).
+   <td>RECOMMENDED. Point to an existing atlas in a template space (URL or relative file path where this file is located).
    </td>
   </tr>
   <tr>
@@ -486,13 +486,13 @@ Example content of the `sub-01_task-rest_atlas.json` file contains top-level met
 
 ## Quantitative atlas examples
 
-The example below is for PET imaging, but this applies to any quantitative mapping (PET or QMRI). Compared to anatomical atlases, quantitative atlases give reference values to be compared with. Such values can be derived voxel/vertex wise (see case 1) or per region of interest (ROI) (see case 2). In the latter case, ROIs are generally derived from an anatomical atlas.
+The example below is for PET imaging, but this applies to any quantitative mapping (PET or qMRI). Compared to anatomical atlases, quantitative atlases give reference values to be compared with. Such values can be derived voxel/vertex wise (see case 1) or per region of interest (ROI) (see case 2). In the latter case, ROIs are generally derived from an anatomical atlas.
 
-We created a Molecular Imaging Brain Atlases (MIBA) from 16 subjects who underwent a [11C]PS13 PET scan, a radioligand that quantifies cyclooxygenase-1 (see [source data](https://openneuro.org/datasets/ds004332/versions/1.0.2)). Our atlas consists of mean and standard deviations of PS13 target distribution volumes (VT) computed across the 16 subjects at each voxel, in standard MRI spaces. We also project these distribution volumes onto the freesurfer cortical surfaces and include these as well.  The goal is to allow researchers with MRI-only data to correlate their results to the distribution volume of PS13. The dataset can be found [here](https://openneuro.org/datasets/ds004401/versions/1.1.0).
+We created a Molecular Imaging Brain Atlases (MIBA) from 16 subjects who underwent a [11C]PS13 PET scan, a radioligand that quantifies cyclooxygenase-1 (see [source data](https://openneuro.org/datasets/ds004332/versions/1.0.2)). Our atlas consists of mean and standard deviations of PS13 target distribution volumes (VT) computed across the 16 subjects at each voxel, in standard MRI spaces. We also project these distribution volumes onto the FreeSurfer cortical surfaces and include these as well.  The goal is to allow researchers with MRI-only data to correlate their results to the distribution volume of PS13. The dataset can be found [here](https://openneuro.org/datasets/ds004401/versions/1.1.0).
 
 ### Case 1: voxel/vertex wise analysis
 
-Example directory content for a quantitative atlas that provides values at all voxels and/or verteces:
+Example directory content for a quantitative atlas that provides values at all voxels and/or vertices:
 
 ```Text
 bids/atlas/atlas-ps13/
@@ -536,4 +536,4 @@ bids/atlas/
     atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_seg-AAL_mimap.tsv
 ```
 
-Note that there is no image file present in a regional qunatitative atlas. The json file accompanying the quantitative atlas should include the information as in [Single existing atlas in template space](#_Single_existing_atlas_in_template_space).
+Note that there is no image file present in a regional quantitative atlas. The json file accompanying the quantitative atlas should include the information as in [Single existing atlas in template space](#_Single_existing_atlas_in_template_space).

From a96ab795dfb2ec118818c10acc827344c7acb3ba Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Tue, 6 Feb 2024 12:13:00 -0500
Subject: [PATCH 11/16] Replace i.e. and e.g.

---
 src/atlas.md | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/src/atlas.md b/src/atlas.md
index 40f74d55e8..f3f939aee2 100644
--- a/src/atlas.md
+++ b/src/atlas.md
@@ -2,21 +2,21 @@
 
 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, 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.
 
 ## 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).
+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, 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`.
+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), 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.
+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.
 
@@ -25,13 +25,13 @@ BIDS-Atlas focuses on the utilization of atlases while also allowing their shari
 
 ### 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 directory 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
 <dataset>/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
@@ -43,7 +43,7 @@ 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 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.
+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, for example, transformed, but still remains an atlas. In the other case, the atlas is used to define a segmentation, for example, the AAL atlas is used to define a cortical parcellation, that then is applied to a subjects other content, for example, a cortical thickness or binding potential map.
 
 #### Case 1
 
@@ -81,7 +81,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 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.
+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, for example, 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/
@@ -98,7 +98,7 @@ Third, a given atlas was derived from the corresponding subject’s data and thu
 The `[probseg|dseg|mask].[nii|dlabel.nii|label.gii][.gz]` file represents the location and extent of the nodes/parcels/regions within the atlas. Different file types are supported based on the modality and atlas at hand. In more detail, this encompasses the following three options:
 
 1. [_dseg](schema/objects/suffixes.yaml#dseg): Each node is labeled with a unique integer corresponding to its row/index in the tsv sidecar.
-2. [_probseg](schema/objects/suffixes.yaml#probseg): Each node is represented along an additional dimension of the file (e.g., a 4D NIfTI file where each volume represents a node) and its position in that dimension corresponds to its row/index in the tsv sidecar.
+2. [_probseg](schema/objects/suffixes.yaml#probseg): Each node is represented along an additional dimension of the file (for example, a 4D NIfTI file where each volume represents a node) and its position in that dimension corresponds to its row/index in the tsv sidecar.
 3. [_mask](schema/objects/suffixes.yaml#mask): Either each voxel represents a node or the entire mask is a single node. How the mask should be interpreted is determined by other specifications. Based on these options, an atlas can take the following forms in the here proposed specification (non-exhaustive list):
 a.  A 3D NIfTI file with unique integers defining nodes
 b.  A 4D binary NIfTI file with spatially overlapping nodes in each volume (along the 4th dimension)
@@ -137,7 +137,7 @@ The `[probseg|dseg|mask|channels].tsv` file indexes and labels each node/parcel/
   <tr>
    <td>network_label
    </td>
-   <td>OPTIONAL. Label of Network (e.g. Dorsal Attention Network)
+   <td>OPTIONAL. Label of Network (for example, Dorsal Attention Network)
    </td>
   </tr>
   <tr>
@@ -281,13 +281,13 @@ The `[probseg|dseg|mask].json` file provides metadata to uniquely identify, desc
   <tr>
    <td>DerivedFrom
    </td>
-   <td>RECOMMENDED. Indicate what data modality the atlas was derived from, e.g. "cytoarchitecture", "resting-state", "task".
+   <td>RECOMMENDED. Indicate what data modality the atlas was derived from, for example, "cytoarchitecture", "resting-state", "task".
    </td>
   </tr>
   <tr>
    <td>LevelType
    </td>
-   <td>RECOMMENDED. Indicate what analysis level the atlas was derived from, e.g. "group", "individual".
+   <td>RECOMMENDED. Indicate what analysis level the atlas was derived from, for example, "group", "individual".
    </td>
   </tr>
 </table>
@@ -328,7 +328,7 @@ Within the following, multiple examples showcasing the proposed extension are pr
 
 ## Atlas as dataset - single existing atlas in template space
 
-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.
+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 (for example, transformations, subsetting, etc.) for all subjects to which the pipeline was applied.
 
 ```Text
 my_dataset/atlas-HarvardOxford/
@@ -385,7 +385,7 @@ Insular Cortex	bilateral
 ```
 
 ## Multiple existing atlases in template space
-The example below illustrates how multiple existing atlases in the same template space are represented according to the atlas BEP. Specifically, the example refers to the Harvard-Oxford, Schaefer, Yeo and MSDL atlases, all in MN152NLin6Asym space and with a resolution of 2 mm3, were utilized without modifications (e.g. transformations, subsetting, etc.) for all subjects to which the pipeline was applied. Importantly, all atlas-related information is indicated via the value of the atlas- key and not via desc- to help prevent inheritance problems in subsequent steps. Here, this was used to indicate that the Harvard-Oxford atlas in its version with a maximum probability of 50, the Schaefer atlas in its 400 parcel version and the Yeo atlas in its 17 networks version were used. The respective information found in each file follows the example outlined in 4.1 as atlases were used independently from one another.
+The example below illustrates how multiple existing atlases in the same template space are represented according to the atlas BEP. Specifically, the example refers to the Harvard-Oxford, Schaefer, Yeo and MSDL atlases, all in MN152NLin6Asym space and with a resolution of 2 mm3, were utilized without modifications (for example, transformations, subsetting, etc.) for all subjects to which the pipeline was applied. Importantly, all atlas-related information is indicated via the value of the atlas- key and not via desc- to help prevent inheritance problems in subsequent steps. Here, this was used to indicate that the Harvard-Oxford atlas in its version with a maximum probability of 50, the Schaefer atlas in its 400 parcel version and the Yeo atlas in its 17 networks version were used. The respective information found in each file follows the example outlined in 4.1 as atlases were used independently from one another.
 
 
 ```Text
@@ -409,7 +409,7 @@ bids/atlases/
 ```
  
 ## Single existing atlas transformed to subject space
-The example below illustrates how a single existing atlas transformed into a subject’s native space space is represented according to the atlas BEP. Specifically, the example refers to the Harvard-Oxford atlas with a resolution of 2 mm3 that was transformed from the MN152NLin6Asym template space to a given subject’s native T1w space. While the original atlas-related files remain as outlined in the use case in template space, the spatially transformed version of the nii.gz atlas file will be placed within a given subjects directory. The precise location within the latter depends on the modality space to which the atlas was transformed to, e.g. anat, func or dwi. The same location furthermore entails a corresponding json file outlining further information on the source atlas and applied transformation(s).
+The example below illustrates how a single existing atlas transformed into a subject’s native space space is represented according to the atlas BEP. Specifically, the example refers to the Harvard-Oxford atlas with a resolution of 2 mm3 that was transformed from the MN152NLin6Asym template space to a given subject’s native T1w space. While the original atlas-related files remain as outlined in the use case in template space, the spatially transformed version of the nii.gz atlas file will be placed within a given subjects directory. The precise location within the latter depends on the modality space to which the atlas was transformed to, for example, anat, func or dwi. The same location furthermore entails a corresponding json file outlining further information on the source atlas and applied transformation(s).
 
 
 ```Text

From 18e2bcc779521fc388c10c3583c612038aa8a9f7 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Tue, 6 Feb 2024 12:24:46 -0500
Subject: [PATCH 12/16] Line break at sentences, format nested list as markdown

---
 src/atlas.md | 130 +++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 96 insertions(+), 34 deletions(-)

diff --git a/src/atlas.md b/src/atlas.md
index f3f939aee2..8e22b99ecb 100644
--- a/src/atlas.md
+++ b/src/atlas.md
@@ -1,37 +1,55 @@
 # 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.
+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.
+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 (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`.
+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, 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
+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
 <dataset>/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), that is, 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
@@ -43,11 +61,17 @@ 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 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, for example, transformed, but still remains an atlas. In the other case, the atlas is used to define a segmentation, for example, the AAL atlas is used to define a cortical parcellation, that then is applied to a subjects other content, for example, a cortical thickness or binding potential 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, for example, transformed, but still remains an atlas.
+In the other case, the atlas is used to define a segmentation, for example, the AAL atlas is used to define a cortical parcellation, that then is applied to a subjects other content, for example, a cortical thickness or binding potential map.
 
 #### Case 1
 
-First, a given atlas underwent modifications before its utilization, specifically spatial transformations to a template space and is used in this form within a given pipeline. In this case, the respective BIDS-Atlas files will be stored at both the BIDS root level and the given pipeline directory under `derivatives`. Files stored at the BIDS root level will follow the structure outlined in option 1, while files stored at the pipeline level will follow the respective naming conventions. For example, if an atlas was spatially transformed to a certain MNI template, then the BIDS-Atlas files will be stored within the respective pipeline directory and the corresponding [space](schema/objects/entities.yaml#space)-<label> identifier will be adapted accordingly.
+First, a given atlas underwent modifications before its utilization, specifically spatial transformations to a template space and is used in this form within a given pipeline.
+In this case, the respective BIDS-Atlas files will be stored at both the BIDS root level and the given pipeline directory under `derivatives`.
+Files stored at the BIDS root level will follow the structure outlined in option 1, while files stored at the pipeline level will follow the respective naming conventions.
+For example, if an atlas was spatially transformed to a certain MNI template, then the BIDS-Atlas files will be stored within the respective pipeline directory and the corresponding [space](schema/objects/entities.yaml#space)-<label> identifier will be adapted accordingly.
 
 ```Text
 <dataset>/atlas/atlas-<label>/
@@ -63,7 +87,10 @@ 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 referring 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>/
@@ -81,7 +108,11 @@ 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 subject-specific atlas can be used for, for example, 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.
+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, for example, 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/
@@ -95,14 +126,18 @@ Third, a given atlas was derived from the corresponding subject’s data and thu
 
 ### Representing locations in an atlas file
 
-The `[probseg|dseg|mask].[nii|dlabel.nii|label.gii][.gz]` file represents the location and extent of the nodes/parcels/regions within the atlas. Different file types are supported based on the modality and atlas at hand. In more detail, this encompasses the following three options:
+The `[probseg|dseg|mask].[nii|dlabel.nii|label.gii][.gz]` file represents the location and extent of the nodes/parcels/regions within the atlas.
+Different file types are supported based on the modality and atlas at hand.
+In more detail, this encompasses the following three options:
 
 1. [_dseg](schema/objects/suffixes.yaml#dseg): Each node is labeled with a unique integer corresponding to its row/index in the tsv sidecar.
-2. [_probseg](schema/objects/suffixes.yaml#probseg): Each node is represented along an additional dimension of the file (for example, a 4D NIfTI file where each volume represents a node) and its position in that dimension corresponds to its row/index in the tsv sidecar.
-3. [_mask](schema/objects/suffixes.yaml#mask): Either each voxel represents a node or the entire mask is a single node. How the mask should be interpreted is determined by other specifications. Based on these options, an atlas can take the following forms in the here proposed specification (non-exhaustive list):
-a.  A 3D NIfTI file with unique integers defining nodes
-b.  A 4D binary NIfTI file with spatially overlapping nodes in each volume (along the 4th dimension)
-c.  A 4D NIfTI file with overlapping nodes with continuous values for each voxel within a volume
+1. [_probseg](schema/objects/suffixes.yaml#probseg): Each node is represented along an additional dimension of the file (for example, a 4D NIfTI file where each volume represents a node) and its position in that dimension corresponds to its row/index in the tsv sidecar.
+1. [_mask](schema/objects/suffixes.yaml#mask): Either each voxel represents a node or the entire mask is a single node.
+   How the mask should be interpreted is determined by other specifications.
+   Based on these options, an atlas can take the following forms in the here proposed specification (non-exhaustive list):
+     1.  A 3D NIfTI file with unique integers defining nodes
+     1.  A 4D binary NIfTI file with spatially overlapping nodes in each volume (along the 4th dimension)
+     1.  A 4D NIfTI file with overlapping nodes with continuous values for each voxel within a volume
 
 Examples:
 ```Text
@@ -111,9 +146,15 @@ atlas-HarvardOxford_res-2_probseg.nii.gz
 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.
+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 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.
+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>
@@ -197,7 +238,8 @@ index	label	network_label	hemisphere
 2	Heschl's Gyrus	Somatomotor	right
 ```
 
-The `[probseg|dseg|mask].json` file provides metadata to uniquely identify, describe and characterize the atlas, as well as give proper attribution to the creators. Additionally, SpatialReference serves the important purpose of unambiguously identifying the space the atlas is labeled in.
+The `[probseg|dseg|mask].json` file provides metadata to uniquely identify, describe and characterize the atlas, as well as give proper attribution to the creators.
+Additionally, SpatialReference serves the important purpose of unambiguously identifying the space the atlas is labeled in.
 
 <table>
   <tr>
@@ -324,11 +366,13 @@ 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.
+Within the following, multiple examples showcasing the proposed extension are provided.
+They include BEP-specific as well as other/general BIDS files.
 
 ## Atlas as dataset - single existing atlas in template space
 
-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 (for example, 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 (for example, transformations, subsetting, etc.) for all subjects to which the pipeline was applied.
 
 ```Text
 my_dataset/atlas-HarvardOxford/
@@ -385,7 +429,11 @@ Insular Cortex	bilateral
 ```
 
 ## Multiple existing atlases in template space
-The example below illustrates how multiple existing atlases in the same template space are represented according to the atlas BEP. Specifically, the example refers to the Harvard-Oxford, Schaefer, Yeo and MSDL atlases, all in MN152NLin6Asym space and with a resolution of 2 mm3, were utilized without modifications (for example, transformations, subsetting, etc.) for all subjects to which the pipeline was applied. Importantly, all atlas-related information is indicated via the value of the atlas- key and not via desc- to help prevent inheritance problems in subsequent steps. Here, this was used to indicate that the Harvard-Oxford atlas in its version with a maximum probability of 50, the Schaefer atlas in its 400 parcel version and the Yeo atlas in its 17 networks version were used. The respective information found in each file follows the example outlined in 4.1 as atlases were used independently from one another.
+The example below illustrates how multiple existing atlases in the same template space are represented according to the atlas BEP.
+Specifically, the example refers to the Harvard-Oxford, Schaefer, Yeo and MSDL atlases, all in MN152NLin6Asym space and with a resolution of 2 mm3, were utilized without modifications (for example, transformations, subsetting, etc.) for all subjects to which the pipeline was applied.
+Importantly, all atlas-related information is indicated via the value of the atlas- key and not via desc- to help prevent inheritance problems in subsequent steps.
+Here, this was used to indicate that the Harvard-Oxford atlas in its version with a maximum probability of 50, the Schaefer atlas in its 400 parcel version and the Yeo atlas in its 17 networks version were used.
+The respective information found in each file follows the example outlined in 4.1 as atlases were used independently from one another.
 
 
 ```Text
@@ -409,7 +457,11 @@ bids/atlases/
 ```
  
 ## Single existing atlas transformed to subject space
-The example below illustrates how a single existing atlas transformed into a subject’s native space space is represented according to the atlas BEP. Specifically, the example refers to the Harvard-Oxford atlas with a resolution of 2 mm3 that was transformed from the MN152NLin6Asym template space to a given subject’s native T1w space. While the original atlas-related files remain as outlined in the use case in template space, the spatially transformed version of the nii.gz atlas file will be placed within a given subjects directory. The precise location within the latter depends on the modality space to which the atlas was transformed to, for example, anat, func or dwi. The same location furthermore entails a corresponding json file outlining further information on the source atlas and applied transformation(s).
+The example below illustrates how a single existing atlas transformed into a subject’s native space space is represented according to the atlas BEP.
+Specifically, the example refers to the Harvard-Oxford atlas with a resolution of 2 mm3 that was transformed from the MN152NLin6Asym template space to a given subject’s native T1w space.
+While the original atlas-related files remain as outlined in the use case in template space, the spatially transformed version of the nii.gz atlas file will be placed within a given subjects directory.
+The precise location within the latter depends on the modality space to which the atlas was transformed to, for example, anat, func or dwi.
+The same location furthermore entails a corresponding json file outlining further information on the source atlas and applied transformation(s).
 
 
 ```Text
@@ -443,7 +495,9 @@ Example content of the `sub-01_space-T1w_seg-HarvardOxford_res-2_dseg.json` file
 
 ##  MyConnectome example
 
-The example below illustrates how two atlases, an individual surface-based cortical parcellation in FS_lr space (called Russome), and the subcortical regions from a volumetric segmentation provided by the FreeSurfer aseg, are represented according to the atlas BEP. While the FreeSurfer atlas-related files have two instances, one as outlined in the use case in template space and one as outlined in the use case covering subject spaces, the individual parcellation in FS_lr space will be placed only within a given subjects directory. The same location furthermore entails a corresponding json file outlining further information on the atlas and applied analysis to obtain it.
+The example below illustrates how two atlases, an individual surface-based cortical parcellation in FS_lr space (called Russome), and the subcortical regions from a volumetric segmentation provided by the FreeSurfer aseg, are represented according to the atlas BEP.
+While the FreeSurfer atlas-related files have two instances, one as outlined in the use case in template space and one as outlined in the use case covering subject spaces, the individual parcellation in FS_lr space will be placed only within a given subjects directory.
+The same location furthermore entails a corresponding json file outlining further information on the atlas and applied analysis to obtain it.
 
 ```Text
 bids/atlases/atlas-FreeSurferASEG/
@@ -486,9 +540,16 @@ Example content of the `sub-01_task-rest_atlas.json` file contains top-level met
 
 ## Quantitative atlas examples
 
-The example below is for PET imaging, but this applies to any quantitative mapping (PET or qMRI). Compared to anatomical atlases, quantitative atlases give reference values to be compared with. Such values can be derived voxel/vertex wise (see case 1) or per region of interest (ROI) (see case 2). In the latter case, ROIs are generally derived from an anatomical atlas.
+The example below is for PET imaging, but this applies to any quantitative mapping (PET or qMRI).
+Compared to anatomical atlases, quantitative atlases give reference values to be compared with.
+Such values can be derived voxel/vertex wise (see case 1) or per region of interest (ROI) (see case 2).
+In the latter case, ROIs are generally derived from an anatomical atlas.
 
-We created a Molecular Imaging Brain Atlases (MIBA) from 16 subjects who underwent a [11C]PS13 PET scan, a radioligand that quantifies cyclooxygenase-1 (see [source data](https://openneuro.org/datasets/ds004332/versions/1.0.2)). Our atlas consists of mean and standard deviations of PS13 target distribution volumes (VT) computed across the 16 subjects at each voxel, in standard MRI spaces. We also project these distribution volumes onto the FreeSurfer cortical surfaces and include these as well.  The goal is to allow researchers with MRI-only data to correlate their results to the distribution volume of PS13. The dataset can be found [here](https://openneuro.org/datasets/ds004401/versions/1.1.0).
+We created a Molecular Imaging Brain Atlases (MIBA) from 16 subjects who underwent a [11C]PS13 PET scan, a radioligand that quantifies cyclooxygenase-1 (see [source data](https://openneuro.org/datasets/ds004332/versions/1.0.2)).
+Our atlas consists of mean and standard deviations of PS13 target distribution volumes (VT) computed across the 16 subjects at each voxel, in standard MRI spaces.
+We also project these distribution volumes onto the FreeSurfer cortical surfaces and include these as well.
+The goal is to allow researchers with MRI-only data to correlate their results to the distribution volume of PS13.
+The dataset can be found [here](https://openneuro.org/datasets/ds004401/versions/1.1.0).
 
 ### Case 1: voxel/vertex wise analysis
 
@@ -536,4 +597,5 @@ bids/atlas/
     atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_seg-AAL_mimap.tsv
 ```
 
-Note that there is no image file present in a regional quantitative atlas. The json file accompanying the quantitative atlas should include the information as in [Single existing atlas in template space](#_Single_existing_atlas_in_template_space).
+Note that there is no image file present in a regional quantitative atlas.
+The json file accompanying the quantitative atlas should include the information as in [Single existing atlas in template space](#_Single_existing_atlas_in_template_space).

From 803f0d4e1fc6dbe6cc901c660211ee828feb16b1 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Tue, 6 Feb 2024 12:29:29 -0500
Subject: [PATCH 13/16] Replace unicode quotes with ASCII

---
 src/atlas.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/atlas.md b/src/atlas.md
index 8e22b99ecb..00c49d55bb 100644
--- a/src/atlas.md
+++ b/src/atlas.md
@@ -184,7 +184,7 @@ Additional fields can be added with their respective definition/description in t
   <tr>
    <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>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>
   </tr>
   <tr>
@@ -208,7 +208,7 @@ Additional fields can be added with their respective definition/description in t
   <tr>
    <td>hemisphere
    </td>
-   <td>OPTIONAL. MUST BE ONE OF: “left”, “right”, “bilateral”. Indicate whether the node/parcel/region is in the left or right hemispheres, or is available bilaterally.
+   <td>OPTIONAL. MUST BE ONE OF: "left", "right", "bilateral". Indicate whether the node/parcel/region is in the left or right hemispheres, or is available bilaterally.
    </td>
   </tr>
   <tr>
@@ -226,7 +226,7 @@ Additional fields can be added with their respective definition/description in t
   <tr>
    <td>region
    </td>
-   <td>OPTIONAL. “XY”, where X can be L:left, R:right, B:bilateral, and Y can be F:frontal, T:temporal, P:parietal, O:occipital
+   <td>OPTIONAL. "XY", where X can be L:left, R:right, B:bilateral, and Y can be F:frontal, T:temporal, P:parietal, O:occipital
    </td>
   </tr>
 </table>
@@ -275,13 +275,13 @@ Additionally, SpatialReference serves the important purpose of unambiguously ide
   <tr>
    <td>4thDimension
    </td>
-   <td>OPTIONAL. RECOMMENDED if probabilistic atlas. Should indicate what the 4th dimension entails/refers to. MUST be “Indices” or   .
+   <td>OPTIONAL. RECOMMENDED if probabilistic atlas. Should indicate what the 4th dimension entails/refers to. MUST be "Indices" or   .
    </td>
   </tr>
   <tr>
    <td>CoordinateReportStrategy
    </td>
-   <td>OPTIONAL. MUST BE ONE OF: “peak”, “center_of_mass”, “other”. Indicate the method of coordinate reporting in statistically significant clusters. Could be the “peak” statistical coordinate in the cluster or the “center_of_mass” of the cluster. RECOMMENDED if x, y ,z values are set in the .tsv file.
+   <td>OPTIONAL. MUST BE ONE OF: "peak", "center_of_mass", "other". Indicate the method of coordinate reporting in statistically significant clusters. Could be the "peak" statistical coordinate in the cluster or the "center_of_mass" of the cluster. RECOMMENDED if x, y ,z values are set in the .tsv file.
    </td>
   </tr>
   <tr>

From dda4790d423ef0e1dbd7bd62a274a1dae319cad3 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Tue, 6 Feb 2024 12:29:54 -0500
Subject: [PATCH 14/16] Include atlas.md in table of contents

---
 mkdocs.yml | 1 +
 1 file changed, 1 insertion(+)

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:

From ba30c0ea48a2c2df4c1e62623b415a75775dc112 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Tue, 6 Feb 2024 13:48:29 -0500
Subject: [PATCH 15/16] Semantic line breaks, mostly at commas

---
 src/atlas.md | 147 ++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 109 insertions(+), 38 deletions(-)

diff --git a/src/atlas.md b/src/atlas.md
index 00c49d55bb..6a2297b97f 100644
--- a/src/atlas.md
+++ b/src/atlas.md
@@ -3,45 +3,91 @@
 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.
+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.
+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.
+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 (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).
+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.
+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.
+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, 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.
+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
@@ -49,7 +95,8 @@ This allows validating any
 ```
 
 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.
+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
@@ -68,10 +115,13 @@ In the other case, the atlas is used to define a segmentation, for example, the
 
 #### Case 1
 
-First, a given atlas underwent modifications before its utilization, specifically spatial transformations to a template space and is used in this form within a given pipeline.
+First, a given atlas underwent modifications before its utilization,
+specifically spatial transformations to a template space and is used in this form within a given pipeline.
 In this case, the respective BIDS-Atlas files will be stored at both the BIDS root level and the given pipeline directory under `derivatives`.
-Files stored at the BIDS root level will follow the structure outlined in option 1, while files stored at the pipeline level will follow the respective naming conventions.
-For example, if an atlas was spatially transformed to a certain MNI template, then the BIDS-Atlas files will be stored within the respective pipeline directory and the corresponding [space](schema/objects/entities.yaml#space)-<label> identifier will be adapted accordingly.
+Files stored at the BIDS root level will follow the structure outlined in option 1,
+while files stored at the pipeline level will follow the respective naming conventions.
+For example, if an atlas was spatially transformed to a certain MNI template,
+then the BIDS-Atlas files will be stored within the respective pipeline directory and the corresponding [space](schema/objects/entities.yaml#space)-<label> identifier will be adapted accordingly.
 
 ```Text
 <dataset>/atlas/atlas-<label>/
@@ -87,7 +137,8 @@ For example, if an atlas was spatially transformed to a certain MNI template, th
 
 #### 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.
+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.
@@ -111,7 +162,9 @@ Files stored at the subject level now use the [seg](schema/objects/entities.yaml
 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, for example, an histological atlas/segmentation.
+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,
+for example, 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
@@ -147,13 +200,15 @@ 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.
+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 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.
+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>
@@ -372,7 +427,9 @@ They include BEP-specific as well as other/general BIDS files.
 ## Atlas as dataset - single existing atlas in template space
 
 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 (for example, transformations, subsetting, etc.) for all subjects to which the pipeline was applied.
+Specifically, the example refers to the Harvard-Oxford atlas in MN152NLin6Asym space with a resolution of 2 mm3,
+used without modifications (for example, transformations, subsetting, etc.)
+for all subjects to which the pipeline was applied.
 
 ```Text
 my_dataset/atlas-HarvardOxford/
@@ -381,7 +438,8 @@ my_dataset/atlas-HarvardOxford/
   atlas-HarvardOxford_res-2_dseg.tsv
 ```
 
-The content of each file is further outlined in the following, starting with the .json sidecar file containing meta-data about the atlas at hand.
+The content of each file is further outlined in the following,
+starting with the .json sidecar file containing meta-data about the atlas at hand.
 
 Example content of the `atlas-HarvardOxford_res-2_dseg.json` file:
 
@@ -430,9 +488,13 @@ Insular Cortex	bilateral
 
 ## Multiple existing atlases in template space
 The example below illustrates how multiple existing atlases in the same template space are represented according to the atlas BEP.
-Specifically, the example refers to the Harvard-Oxford, Schaefer, Yeo and MSDL atlases, all in MN152NLin6Asym space and with a resolution of 2 mm3, were utilized without modifications (for example, transformations, subsetting, etc.) for all subjects to which the pipeline was applied.
+Specifically, the example refers to the Harvard-Oxford, Schaefer, Yeo and MSDL atlases,
+all in MN152NLin6Asym space and with a resolution of 2 mm3,
+were utilized without modifications (for example, transformations, subsetting, etc.)
+for all subjects to which the pipeline was applied.
 Importantly, all atlas-related information is indicated via the value of the atlas- key and not via desc- to help prevent inheritance problems in subsequent steps.
-Here, this was used to indicate that the Harvard-Oxford atlas in its version with a maximum probability of 50, the Schaefer atlas in its 400 parcel version and the Yeo atlas in its 17 networks version were used.
+Here, this was used to indicate that the Harvard-Oxford atlas in its version with a maximum probability of 50,
+the Schaefer atlas in its 400 parcel version and the Yeo atlas in its 17 networks version were used.
 The respective information found in each file follows the example outlined in 4.1 as atlases were used independently from one another.
 
 
@@ -459,8 +521,10 @@ bids/atlases/
 ## Single existing atlas transformed to subject space
 The example below illustrates how a single existing atlas transformed into a subject’s native space space is represented according to the atlas BEP.
 Specifically, the example refers to the Harvard-Oxford atlas with a resolution of 2 mm3 that was transformed from the MN152NLin6Asym template space to a given subject’s native T1w space.
-While the original atlas-related files remain as outlined in the use case in template space, the spatially transformed version of the nii.gz atlas file will be placed within a given subjects directory.
-The precise location within the latter depends on the modality space to which the atlas was transformed to, for example, anat, func or dwi.
+While the original atlas-related files remain as outlined in the use case in template space,
+the spatially transformed version of the nii.gz atlas file will be placed within a given subjects directory.
+The precise location within the latter depends on the modality space to which the atlas was transformed to,
+for example, anat, func or dwi.
 The same location furthermore entails a corresponding json file outlining further information on the source atlas and applied transformation(s).
 
 
@@ -495,8 +559,13 @@ Example content of the `sub-01_space-T1w_seg-HarvardOxford_res-2_dseg.json` file
 
 ##  MyConnectome example
 
-The example below illustrates how two atlases, an individual surface-based cortical parcellation in FS_lr space (called Russome), and the subcortical regions from a volumetric segmentation provided by the FreeSurfer aseg, are represented according to the atlas BEP.
-While the FreeSurfer atlas-related files have two instances, one as outlined in the use case in template space and one as outlined in the use case covering subject spaces, the individual parcellation in FS_lr space will be placed only within a given subjects directory.
+The example below illustrates how two atlases,
+an individual surface-based cortical parcellation in FS_lr space (called Russome),
+and the subcortical regions from a volumetric segmentation provided by the FreeSurfer aseg,
+are represented according to the atlas BEP.
+While the FreeSurfer atlas-related files have two instances,
+one as outlined in the use case in template space and one as outlined in the use case covering subject spaces,
+the individual parcellation in FS_lr space will be placed only within a given subjects directory.
 The same location furthermore entails a corresponding json file outlining further information on the atlas and applied analysis to obtain it.
 
 ```Text
@@ -545,7 +614,8 @@ Compared to anatomical atlases, quantitative atlases give reference values to be
 Such values can be derived voxel/vertex wise (see case 1) or per region of interest (ROI) (see case 2).
 In the latter case, ROIs are generally derived from an anatomical atlas.
 
-We created a Molecular Imaging Brain Atlases (MIBA) from 16 subjects who underwent a [11C]PS13 PET scan, a radioligand that quantifies cyclooxygenase-1 (see [source data](https://openneuro.org/datasets/ds004332/versions/1.0.2)).
+We created a Molecular Imaging Brain Atlases (MIBA) from 16 subjects who underwent a [11C]PS13 PET scan,
+a radioligand that quantifies cyclooxygenase-1 (see [source data](https://openneuro.org/datasets/ds004332/versions/1.0.2)).
 Our atlas consists of mean and standard deviations of PS13 target distribution volumes (VT) computed across the 16 subjects at each voxel, in standard MRI spaces.
 We also project these distribution volumes onto the FreeSurfer cortical surfaces and include these as well.
 The goal is to allow researchers with MRI-only data to correlate their results to the distribution volume of PS13.
@@ -573,7 +643,8 @@ bids/atlas/atlas-ps13/
 
 ### Case 2: regional analysis (voxels/vertices are averaged per regions from dseg/probseg)
 
-Example directory content for a quantitative atlas that provides values for certain ROIs only, in this case defined by the AAL atlas:
+Example directory content for a quantitative atlas that provides values for certain ROIs only,
+in this case defined by the AAL atlas:
 
 ```Text
 bids/atlas/

From 9c803d78d83d83074ed04d715378bafe0dad620f Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Tue, 6 Feb 2024 14:20:39 -0500
Subject: [PATCH 16/16] FIX: Whitespace in
 schema.objects.entities.atlas.description

---
 src/schema/objects/entities.yaml | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/src/schema/objects/entities.yaml b/src/schema/objects/entities.yaml
index b6463e710a..d46bc6b084 100644
--- a/src/schema/objects/entities.yaml
+++ b/src/schema/objects/entities.yaml
@@ -29,18 +29,18 @@ atlas:
   name: atlas
   display_name: Atlas
   description: |
-  The definition of atlas per Merriam-Webster is ‘a bound collection of maps (i.e. labeled brain regions
-  or quantitative aspects) and metadata (tables, or textual matter). Within BIDS, atlases are broadly 
-  defined as a mapping between locations in a spatial coordinate systems and descriptions associated with
-  those locations. Atlases are often build from registering many subjects or maps to a template. By analogy
-  with geographical atlases, brain atlases can map brain locations to either discrete labels like a map 
-  of countries does, or to continuous quantities like a topographic map does. 
-
-  This comprises all possible types of atlases, specifically deterministic, probabilistic, and mask/voxel-based
-  ones, and quantitative maps from various modalities including but not limited to structural features (e.g. 
-  myelination, cytoarchitecture), functional features (e.g. resting-state networks, localizers) and such based on 
-  multimodal data integration (e.g. gene expression, receptors). Furthermore, it covers both volume/voxel and 
-  surface/vertex data, as well as gray and white matter atlases.
+    The definition of atlas per Merriam-Webster is ‘a bound collection of maps (i.e. labeled brain regions
+    or quantitative aspects) and metadata (tables, or textual matter). Within BIDS, atlases are broadly
+    defined as a mapping between locations in a spatial coordinate systems and descriptions associated with
+    those locations. Atlases are often build from registering many subjects or maps to a template. By analogy
+    with geographical atlases, brain atlases can map brain locations to either discrete labels like a map
+    of countries does, or to continuous quantities like a topographic map does.
+
+    This comprises all possible types of atlases, specifically deterministic, probabilistic, and mask/voxel-based
+    ones, and quantitative maps from various modalities including but not limited to structural features (e.g.
+    myelination, cytoarchitecture), functional features (e.g. resting-state networks, localizers) and such based on
+    multimodal data integration (e.g. gene expression, receptors). Furthermore, it covers both volume/voxel and
+    surface/vertex data, as well as gray and white matter atlases.
 ceagent:
   name: ce
   display_name: Contrast Enhancing Agent