Skip to content

Commit 7626992

Browse files
melanieganzmelanieganz
committed
case 3 files renamed
1 parent 81d5ccc commit 7626992

File tree

1 file changed

+196
-33
lines changed

1 file changed

+196
-33
lines changed

‎src/atlas.md‎

Lines changed: 196 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ The usage of [_desc-](schema/objects/entities.yaml#desc) is currently discourage
1515
## Directory Structure
1616
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.
1717

18-
### Representing the atlas at the dataset level
18+
### Representing an atlas as a dataset
1919

2020
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
2121

@@ -33,9 +33,8 @@ The default way of storage of the non-altered atlas at the root directory looks
3333
atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].json
3434
```
3535

36-
### Representing the atlas at the subject level
37-
38-
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.
36+
### Representing an atlas within a dataset
37+
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.
3938

4039
#### Case 1
4140

@@ -56,7 +55,7 @@ First, a given atlas underwent modifications before its utilization, specificall
5655

5756
#### Case 2
5857

59-
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.
58+
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.
6059

6160
```Text
6261
<dataset>/atlas/atlas-<label>/
@@ -66,27 +65,25 @@ Second, a given atlas underwent modifications before its utilization, specifical
6665
6766
<dataset>/derivatives/
6867
sub-01/
69-
anat/
68+
func/
7069
sub-01_space-<label>_seg-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz]
7170
sub-01_space-<label>_seg-<label>_desc-<label>_[dseg|probseg|mask].tsv
7271
sub-01_space-<label>_seg-<label>_desc-<label>_[dseg|probseg|mask].json
7372
```
7473

7574
#### Case 3
7675

77-
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.
78-
79-
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.
76+
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.
8077

8178
```Text
8279
<dataset>/derivatives/
8380
sub-01/
8481
anat/
85-
sub-01_space-<label>_seg_<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz]
86-
sub-01_space-<label>_seg-<label>_desc-<label>_[dseg|probseg|mask].tsv
87-
sub-01_space-<label>_seg-<label>_desc-<label>_[dseg|probseg|mask].json
88-
sub-01_space-<label>_seg-<label>_desc-<label>_coordsystem.json
89-
```
82+
sub-01_atlas-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz][.ome-tiff|.png]
83+
sub-01_atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv
84+
sub-01_atlas-<label>_desc-<label>_[dseg|probseg|mask].json
85+
sub-01_atlas-<label>_desc-<label>_coordsystem.json
86+
9087
9188
### Representing locations in an atlas file
9289
@@ -110,18 +107,184 @@ General Recommendations: This specification relies on the inheritance principle
110107

111108
 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.
112109

113-
insert missing table 1 from Google doc here
110+
<table>
111+
<tr>
112+
<td>index (or placeholder in fragment in reference)
113+
</td>
114+
<td>REQUIRED. (Integer) The number associated with the node/parcel/region (right/left hemispheres may be different).
115+
</td>
116+
</tr>
117+
<tr>
118+
<td>label
119+
</td>
120+
<td>RECOMMENDED. The node name
121+
</td>
122+
</tr>
123+
<tr>
124+
<td>network_id
125+
</td>
126+
<td>OPTIONAL. Network ID the node/parcel belongs to
127+
</td>
128+
</tr>
129+
<tr>
130+
<td>network_label
131+
</td>
132+
<td>OPTIONAL. Label of Network (e.g. Dorsal Attention Network)
133+
</td>
134+
</tr>
135+
<tr>
136+
<td>CoordinateReportStrategy
137+
</td>
138+
<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”.
139+
</td>
140+
</tr>
141+
<tr>
142+
<td>x
143+
</td>
144+
<td>OPTIONAL. The x-coordinate of the node in the spatial reference space (See SpatialReference in the .json file)
145+
</td>
146+
</tr>
147+
<tr>
148+
<td>y
149+
</td>
150+
<td>OPTIONAL. The y-coordinate of the node in the spatial reference space (See SpatialReference in the .json file)
151+
</td>
152+
</tr>
153+
<tr>
154+
<td>z
155+
</td>
156+
<td>OPTIONAL. The z-coordinate of the node in the spatial reference space (See SpatialReference in the .json file)
157+
</td>
158+
</tr>
159+
<tr>
160+
<td>hemisphere
161+
</td>
162+
<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.
163+
</td>
164+
</tr>
165+
<tr>
166+
<td>color
167+
</td>
168+
<td>OPTIONAL. RGB color to use for the node.
169+
</td>
170+
</tr>
171+
<tr>
172+
<td>seed
173+
</td>
174+
<td>OPTIONAL. Seed vertex/channel of the node/region
175+
</td>
176+
</tr>
177+
<tr>
178+
<td>region
179+
</td>
180+
<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
181+
</td>
182+
</tr>
183+
</table>
114184

115185
Example:
116186
```Text
117-
index label network_label hemisphere …
118-
1 Heschl’ Gyrus Somatomotor left …
119-
2 Heschl’ Gyrus Somatomotor right …
187+
index label network_label hemisphere
188+
1 Heschl’ Gyrus Somatomotor left
189+
2 Heschl’ Gyrus Somatomotor right
120190
```
121191

122192
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.
123193

124-
insert missing table 2 from Google doc here
194+
<table>
195+
<tr>
196+
<td>Name
197+
</td>
198+
<td>REQUIRED. Name of the atlas
199+
</td>
200+
</tr>
201+
<tr>
202+
<td>Description
203+
</td>
204+
<td>RECOMMENDED. Longform description of the atlas
205+
</td>
206+
</tr>
207+
<tr>
208+
<td>SpatialReference
209+
</td>
210+
<td>RECOMMENDED. Point to an existing atlas in a template space (url or relative file path where this file is located).
211+
</td>
212+
</tr>
213+
<tr>
214+
<td>Resolution
215+
</td>
216+
<td>RECOMMENDED. Resolution atlas is provided in.
217+
</td>
218+
</tr>
219+
<tr>
220+
<td>Dimensions
221+
</td>
222+
<td>RECOMMENDED. Dimensions of the atlas, MUST be 3 (for deterministic atlases) or 4 (for probabilistic atlases).
223+
</td>
224+
</tr>
225+
<tr>
226+
<td>4thDimension
227+
</td>
228+
<td>OPTIONAL. RECOMMENDED if probabilistic atlas. Should indicate what the 4th dimension entails/refers to. MUST be “Indices” or .
229+
</td>
230+
</tr>
231+
<tr>
232+
<td>CoordinateReportStrategy
233+
</td>
234+
<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.
235+
</td>
236+
</tr>
237+
<tr>
238+
<td>Authors
239+
</td>
240+
<td>RECOMMENDED. List of the authors involved in the creation of the atlas
241+
</td>
242+
</tr>
243+
<tr>
244+
<td>Curators
245+
</td>
246+
<td>RECOMMENDED. List of curators who helped make the atlas accessible in a database or dataset
247+
</td>
248+
</tr>
249+
<tr>
250+
<td>Funding
251+
</td>
252+
<td>RECOMMENDED. The funding source(s) involved in the atlas creation
253+
</td>
254+
</tr>
255+
<tr>
256+
<td>License
257+
</td>
258+
<td>RECOMMENDED. The license agreement for using the atlas.
259+
</td>
260+
</tr>
261+
<tr>
262+
<td>ReferencesAndLinks
263+
</td>
264+
<td>RECOMMENDED. A list of relevant references and links pertaining to the atlas.
265+
</td>
266+
</tr>
267+
<tr>
268+
<td>Species
269+
</td>
270+
<td>RECOMMENDED. The species the atlas was derived from. For example, could be Human, Macaque, Rat, Mouse, etc.
271+
</td>
272+
</tr>
273+
<tr>
274+
<td>DerivedFrom
275+
</td>
276+
<td>RECOMMENDED. Indicate what data modality the atlas was derived from, e.g. "cytoarchitecture", "resting-state", "task".
277+
</td>
278+
</tr>
279+
<tr>
280+
<td>LevelType
281+
</td>
282+
<td>RECOMMENDED. Indicate what analysis level the atlas was derived from, e.g. "group", "individual".
283+
</td>
284+
</tr>
285+
</table>
286+
287+
125288

126289
Example:
127290

@@ -341,28 +504,28 @@ bids/atlas/atlas-ps13/
341504

342505
### Case 2: regional analysis (voxels/vertices are averaged per regions from dseg/probseg)
343506

344-
Example directory content for a quantitative atlas that provides values for certain ROIs only:
507+
Example directory content for a quantitative atlas that provides values for certain ROIs only, in this case defined by the AAL atlas:
345508

346509
```Text
347510
bids/atlas/
348511
atlas-mni305/
349512
atlas-aparc.DKTatlas+aseg.mgz
350-
atlas-aparc.DKTatlas+aseg.tsv
513+
atlas-aparc.DKTatlas+aseg.tsv
351514
atlas-RB_all_2008-03-26.probseg.gca
352515
atlas-RB_all_2008-03-26.probseg.tsv
353516
atlas-ps13/
354-
atlas-ps13_space-fsaverage_hemi-L_stat-mean_meas-VT_mimap.json
355-
atlas-ps13_space-fsaverage-hemi-L_stat-mean_meas-VT_mimap.tsv
356-
atlas-ps13_space-fsaverage-hemi-L_stat-std_meas-VT_mimap.json
357-
atlas-ps13_space-fsaverage-hemi-L_stat-std_meas-VT_mimap.tsv
358-
atlas-ps13_space-fsaverage-hemi-R_stat-mean_meas-VT_mimap.json
359-
atlas-ps13_space-fsaverage-hemi-R_stat-mean_meas-VT_mimap.tsv
360-
atlas-ps13_space-fsaverage-hemi-R_stat-std_meas-VT_mimap.json
361-
atlas-ps13_space-fsaverage-hemi-R_stat-std_meas-VT_mimap.tsv
362-
atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_mimap.json
363-
atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_mimap.tsv
364-
atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_mimap.json
365-
atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_mimap.tsv
517+
atlas-ps13_space-fsaverage_hemi-L_stat-mean_meas-VT_seg-AAL_mimap.json
518+
atlas-ps13_space-fsaverage-hemi-L_stat-mean_meas-VT_seg-AAL_mimap.tsv
519+
atlas-ps13_space-fsaverage-hemi-L_stat-std_meas-VT_seg-AAL_mimap.json
520+
atlas-ps13_space-fsaverage-hemi-L_stat-std_meas-VT_seg-AAL_mimap.tsv
521+
atlas-ps13_space-fsaverage-hemi-R_stat-mean_meas-VT_seg-AAL_mimap.json
522+
atlas-ps13_space-fsaverage-hemi-R_stat-mean_meas-VT_seg-AAL_mimap.tsv
523+
atlas-ps13_space-fsaverage-hemi-R_stat-std_meas-VT_seg-AAL_mimap.json
524+
atlas-ps13_space-fsaverage-hemi-R_stat-std_meas-VT_seg-AAL_mimap.tsv
525+
atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_seg-AAL_mimap.json
526+
atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_seg-AAL_mimap.tsv
527+
atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_seg-AAL_mimap.json
528+
atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_seg-AAL_mimap.tsv
366529
```
367530

368531
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).

0 commit comments

Comments
 (0)