From dda7acaddb4db1842fd72be9c8b2655c5f26e120 Mon Sep 17 00:00:00 2001
From: oesteban <code@oscaresteban.es>
Date: Tue, 13 Aug 2019 10:38:47 -0700
Subject: [PATCH 01/26] fix: force-push a rewrite addressing minimal changes

---
 src/05-derivatives/02-common-data-types.md | 60 ++++++++++++++++++++--
 1 file changed, 55 insertions(+), 5 deletions(-)

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index d348f4b20a..c78bead4f9 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -8,7 +8,7 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         anat|func|dwi/
-        <source_keywords>[_space-<space>][_desc-<label>]_<suffix>.<ext>
+        <source_keywords>[_space-<space>][_desc-<label>][_res-<index>][_den-<label>]_<suffix>.<ext>
 ```
 
 Processing in this context means transformations of data that does not change
@@ -30,13 +30,22 @@ Note that even though `space` and `desc` are
 optional at least one of them needs to be defined to avoid name conflict with
 the raw file.
 
+**Sampling**. When two or more instances of a given derivative are provided with resolution
+(or surface sampling density) being the only difference between them, then the `res` 
+(for *resolution* of volumetric data) and/or `den` (for *density* of non-parametric surfaces)
+SHOULD be used to avoid name conflicts.
+Note that only CIFTI files combining both regularly gridded and surface sampled data 
+(and their downstream derivatives) are allowed to present both `res` and `den` keywords
+simultaneously.
+
 Examples:
 
 ```Text
 pipeline1/
     sub-001/
         func/
-            sub-001_task-rest_run-1_space-MNI305_bold.nii.gz
+            sub-001_task-rest_run-1_space-MNI305_res-1_bold.nii.gz
+            sub-001_task-rest_run-1_space-MNI305_res-2_bold.nii.gz
             sub-001_task-rest_run-1_space-MNI305_bold.json
 ```
 
@@ -62,9 +71,50 @@ makes them invalid (e.g., if a source 4D image is averaged to create a single
 static volume, a SamplingFrequency property would no longer be relevant). In
 addition, all processed files include the following metadata JSON fields:
 
-| **Key name**  | **Description**                                                                                 |
-| ------------- | ----------------------------------------------------------------------------------------------- |
-| SkullStripped | REQUIRED. Boolean. Whether the volume was skull stripped (non-brain voxels set to zero) or not. |
+| **Key name**  | **Description**                                                                                                              |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| SkullStripped | REQUIRED. Boolean. Whether the volume was skull stripped (non-brain voxels set to zero) or not.                              |
+| Resolution    | REQUIRED if `res` keyword present. Dictionary of Indexes to Strings. Specifies the interpretation of the resolution keyword. |
+| Density       | REQUIRED if `den` keyword present. Dictionary of Strings to Strings. Specifies the interpretation of the resolution keyword. |
+
+Example JSON file corresponding to `pipeline1/sub-001/func/sub-001_task-rest_run-1_space-MNI305_bold.json` above:
+
+```JSON
+{
+  "SkullStripped": true,
+  "Resolution": {
+    "1": "MNI305 1mm isotropic resolution",
+    "2": "MNI305 2mm isotropic resolution"
+  }
+}
+```
+
+Example of CIFTI files having both `res` and `den` keywords:
+
+```Text
+pipeline1/
+    sub-001/
+        func/
+            sub-001_task-rest_run-1_res-1_den-10k_bold.dtseries.nii
+            sub-001_task-rest_run-1_res-1_den-41k_bold.dtseries.nii
+            sub-001_task-rest_run-1_bold.dtseries.json
+```
+
+And the corresponding `sub-001_task-rest_run-1_bold.dtseries.json` file:
+
+```JSON
+{
+    "SkullStripped": true,
+    "Resolution": {
+        "1": "MNI152NLin6Asym 1.6mm isotropic"
+    },
+    "Density": {
+        "10k": "fsaverage5 (5th order icosahedron) - 10242 vertices per hemisphere",
+        "41k": "fsaverage6 (6th order icosahedron) - 40962 vertices per hemisphere"
+    }
+}
+```
+
 
 ## Masks
 

From e10f451693a8b62c06e96fcafcbbc3bb5d724cf9 Mon Sep 17 00:00:00 2001
From: oesteban <code@oscaresteban.es>
Date: Tue, 13 Aug 2019 11:55:58 -0700
Subject: [PATCH 02/26] sty: make linter happy

---
 src/05-derivatives/02-common-data-types.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index c78bead4f9..d9462f46ba 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -115,7 +115,6 @@ And the corresponding `sub-001_task-rest_run-1_bold.dtseries.json` file:
 }
 ```
 
-
 ## Masks
 
 Template:

From 3a85c0add37d8f53cf64bc2758c54e390df73550 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Thu, 15 Aug 2019 11:24:40 -0700
Subject: [PATCH 03/26] [STY] Add missing table fence

---
 src/05-derivatives/01-introduction.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 9172f94edd..55efef53ee 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -64,7 +64,7 @@ denotes a key in a subdictionary):
 | PipelineDescription.Name      | REQUIRED. Name of the pipeline that generated the outputs. In case the derived dataset is stored as a subfolder of the raw dataset this field MUST be a substring of the derived dataset folder name (a.k.a. `<pipeline_name>` - see above). |
 | PipelineDescription.Version   | OPTIONAL. Version of the pipeline.                                                                                                                                                                                                           |
 | PipelineDescription.CodeURL   | OPTIONAL. URL where the code for the analysis can be found.                                                                                                                                                                                  |
-| PipelineDescription.Container | OPTIONAL. Object specifying the location and relevant attributes of software container image used to produce the derivative. Valid fields in this object include `Type`, `Tag` and `URI`.
+| PipelineDescription.Container | OPTIONAL. Object specifying the location and relevant attributes of software container image used to produce the derivative. Valid fields in this object include `Type`, `Tag` and `URI`.                                                    |
 | SourceDatasets                | OPTIONAL. A list of objects specifying the locations and relevant attributes of all source datasets. Valid fields in each object include `URL`, `DOI`, and `Version`.                                                                        |
 
 Example:

From 5ec2bf6f04e345e75afedc1083661a3ab700796b Mon Sep 17 00:00:00 2001
From: oesteban <code@oscaresteban.es>
Date: Tue, 13 Aug 2019 10:38:47 -0700
Subject: [PATCH 04/26] fix: force-push a rewrite addressing minimal changes

---
 src/05-derivatives/02-common-data-types.md | 60 ++++++++++++++++++++--
 1 file changed, 55 insertions(+), 5 deletions(-)

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index d348f4b20a..c78bead4f9 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -8,7 +8,7 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         anat|func|dwi/
-        <source_keywords>[_space-<space>][_desc-<label>]_<suffix>.<ext>
+        <source_keywords>[_space-<space>][_desc-<label>][_res-<index>][_den-<label>]_<suffix>.<ext>
 ```
 
 Processing in this context means transformations of data that does not change
@@ -30,13 +30,22 @@ Note that even though `space` and `desc` are
 optional at least one of them needs to be defined to avoid name conflict with
 the raw file.
 
+**Sampling**. When two or more instances of a given derivative are provided with resolution
+(or surface sampling density) being the only difference between them, then the `res` 
+(for *resolution* of volumetric data) and/or `den` (for *density* of non-parametric surfaces)
+SHOULD be used to avoid name conflicts.
+Note that only CIFTI files combining both regularly gridded and surface sampled data 
+(and their downstream derivatives) are allowed to present both `res` and `den` keywords
+simultaneously.
+
 Examples:
 
 ```Text
 pipeline1/
     sub-001/
         func/
-            sub-001_task-rest_run-1_space-MNI305_bold.nii.gz
+            sub-001_task-rest_run-1_space-MNI305_res-1_bold.nii.gz
+            sub-001_task-rest_run-1_space-MNI305_res-2_bold.nii.gz
             sub-001_task-rest_run-1_space-MNI305_bold.json
 ```
 
@@ -62,9 +71,50 @@ makes them invalid (e.g., if a source 4D image is averaged to create a single
 static volume, a SamplingFrequency property would no longer be relevant). In
 addition, all processed files include the following metadata JSON fields:
 
-| **Key name**  | **Description**                                                                                 |
-| ------------- | ----------------------------------------------------------------------------------------------- |
-| SkullStripped | REQUIRED. Boolean. Whether the volume was skull stripped (non-brain voxels set to zero) or not. |
+| **Key name**  | **Description**                                                                                                              |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| SkullStripped | REQUIRED. Boolean. Whether the volume was skull stripped (non-brain voxels set to zero) or not.                              |
+| Resolution    | REQUIRED if `res` keyword present. Dictionary of Indexes to Strings. Specifies the interpretation of the resolution keyword. |
+| Density       | REQUIRED if `den` keyword present. Dictionary of Strings to Strings. Specifies the interpretation of the resolution keyword. |
+
+Example JSON file corresponding to `pipeline1/sub-001/func/sub-001_task-rest_run-1_space-MNI305_bold.json` above:
+
+```JSON
+{
+  "SkullStripped": true,
+  "Resolution": {
+    "1": "MNI305 1mm isotropic resolution",
+    "2": "MNI305 2mm isotropic resolution"
+  }
+}
+```
+
+Example of CIFTI files having both `res` and `den` keywords:
+
+```Text
+pipeline1/
+    sub-001/
+        func/
+            sub-001_task-rest_run-1_res-1_den-10k_bold.dtseries.nii
+            sub-001_task-rest_run-1_res-1_den-41k_bold.dtseries.nii
+            sub-001_task-rest_run-1_bold.dtseries.json
+```
+
+And the corresponding `sub-001_task-rest_run-1_bold.dtseries.json` file:
+
+```JSON
+{
+    "SkullStripped": true,
+    "Resolution": {
+        "1": "MNI152NLin6Asym 1.6mm isotropic"
+    },
+    "Density": {
+        "10k": "fsaverage5 (5th order icosahedron) - 10242 vertices per hemisphere",
+        "41k": "fsaverage6 (6th order icosahedron) - 40962 vertices per hemisphere"
+    }
+}
+```
+
 
 ## Masks
 

From a428a9135e74ff6eb7ca5a3afba9c56fced26b61 Mon Sep 17 00:00:00 2001
From: oesteban <code@oscaresteban.es>
Date: Tue, 13 Aug 2019 11:55:58 -0700
Subject: [PATCH 05/26] sty: make linter happy

---
 src/05-derivatives/02-common-data-types.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index c78bead4f9..d9462f46ba 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -115,7 +115,6 @@ And the corresponding `sub-001_task-rest_run-1_bold.dtseries.json` file:
 }
 ```
 
-
 ## Masks
 
 Template:

From 542ad99d3884aa30d48958dac6580831e662032c Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Thu, 15 Aug 2019 08:36:36 -0700
Subject: [PATCH 06/26] Update src/05-derivatives/02-common-data-types.md

Co-Authored-By: Chris Markiewicz <effigies@gmail.com>
---
 src/05-derivatives/02-common-data-types.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index d9462f46ba..7fde3428b2 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -8,7 +8,7 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         anat|func|dwi/
-        <source_keywords>[_space-<space>][_desc-<label>][_res-<index>][_den-<label>]_<suffix>.<ext>
+        <source_keywords>[_space-<space>][_res-<index>][_den-<label>][_desc-<label>]_<suffix>.<ext>
 ```
 
 Processing in this context means transformations of data that does not change

From 9e4e3841f087cc2d85e815fa84efcd89368679cc Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Thu, 15 Aug 2019 08:59:04 -0700
Subject: [PATCH 07/26] Address @effigies' and @edickie's comments

---
 src/05-derivatives/02-common-data-types.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index 7fde3428b2..6e142495a3 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -83,8 +83,8 @@ Example JSON file corresponding to `pipeline1/sub-001/func/sub-001_task-rest_run
 {
   "SkullStripped": true,
   "Resolution": {
-    "1": "MNI305 1mm isotropic resolution",
-    "2": "MNI305 2mm isotropic resolution"
+    "1": "Matched with original BOLD resolution (2x2x3 mm^3)",
+    "2": "Matched with high-resolution T1w (0.7mm, isotropic)"
   }
 }
 ```
@@ -106,7 +106,7 @@ And the corresponding `sub-001_task-rest_run-1_bold.dtseries.json` file:
 {
     "SkullStripped": true,
     "Resolution": {
-        "1": "MNI152NLin6Asym 1.6mm isotropic"
+        "1": "Matched with MNI152NLin6Asym 1.6mm isotropic"
     },
     "Density": {
         "10k": "fsaverage5 (5th order icosahedron) - 10242 vertices per hemisphere",

From c3213e6f7e16521679ba34b8ae95941a41c87ef9 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Thu, 15 Aug 2019 11:34:46 -0700
Subject: [PATCH 08/26] sty: fix missaligned table fence

---
 src/05-derivatives/02-common-data-types.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index 6e142495a3..79ea139897 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -31,10 +31,10 @@ optional at least one of them needs to be defined to avoid name conflict with
 the raw file.
 
 **Sampling**. When two or more instances of a given derivative are provided with resolution
-(or surface sampling density) being the only difference between them, then the `res` 
+(or surface sampling density) being the only difference between them, then the `res`
 (for *resolution* of volumetric data) and/or `den` (for *density* of non-parametric surfaces)
 SHOULD be used to avoid name conflicts.
-Note that only CIFTI files combining both regularly gridded and surface sampled data 
+Note that only CIFTI files combining both regularly gridded and surface sampled data
 (and their downstream derivatives) are allowed to present both `res` and `den` keywords
 simultaneously.
 
@@ -133,7 +133,7 @@ be set to `orig`.
 JSON metadata fields:
 
 | **Key name** | **Description**                                                                                                                                |
-| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| ------------ |----------------------------------------------------------------------------------------------------------------------------------------------- |
 | RawSources   | Same as defined in [Introduction](01-introduction.md), but elevated from OPTIONAL to REQUIRED                                                  |
 | Type         | RECOMMENDED. Short identifier of the mask. Reserved values: `Brain` - brain mask, `Lesion` - lesion mask, `Face` - face mask, `ROI` - ROI mask |
 

From 9cdeea87c55116c9ea20822f98c732d54f64ba76 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Thu, 15 Aug 2019 11:41:42 -0700
Subject: [PATCH 09/26] fix: better description for example following
 @edickie's comment

---
 src/05-derivatives/02-common-data-types.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index 79ea139897..2cff5be5aa 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -109,8 +109,8 @@ And the corresponding `sub-001_task-rest_run-1_bold.dtseries.json` file:
         "1": "Matched with MNI152NLin6Asym 1.6mm isotropic"
     },
     "Density": {
-        "10k": "fsaverage5 (5th order icosahedron) - 10242 vertices per hemisphere",
-        "41k": "fsaverage6 (6th order icosahedron) - 40962 vertices per hemisphere"
+        "10k": "10242 vertices per hemisphere (5th order icosahedron)",
+        "41k": "40962 vertices per hemisphere (6th order icosahedron)"
     }
 }
 ```

From b071ebb72811a8e32f2bc0a8336100eb683bd16d Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Sat, 17 Aug 2019 23:15:19 -0700
Subject: [PATCH 10/26] More generalizable concepts (addressing
 @robertoostenveld's comments)

---
 src/05-derivatives/02-common-data-types.md | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index 2cff5be5aa..cfd6d06eed 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -32,9 +32,9 @@ the raw file.
 
 **Sampling**. When two or more instances of a given derivative are provided with resolution
 (or surface sampling density) being the only difference between them, then the `res`
-(for *resolution* of volumetric data) and/or `den` (for *density* of non-parametric surfaces)
-SHOULD be used to avoid name conflicts.
-Note that only CIFTI files combining both regularly gridded and surface sampled data
+(for *resolution* of regularly sampled N-D data) and/or `den` (for *density* of non-parametric 
+surfaces) SHOULD be used to avoid name conflicts.
+Note that only files combining both regularly sampled (e.g., gridded) and surface sampled data
 (and their downstream derivatives) are allowed to present both `res` and `den` keywords
 simultaneously.
 
@@ -89,7 +89,8 @@ Example JSON file corresponding to `pipeline1/sub-001/func/sub-001_task-rest_run
 }
 ```
 
-Example of CIFTI files having both `res` and `den` keywords:
+Example of CIFTI files (i.e., a file that combines regularly sampled data
+and non-parametric surfaces) having both `res` and `den` keywords:
 
 ```Text
 pipeline1/

From ea3183aba1eca0543679f45617325ba94f92b9b4 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Mon, 19 Aug 2019 09:59:30 -0700
Subject: [PATCH 11/26] Update src/05-derivatives/02-common-data-types.md

Co-Authored-By: Elizabeth DuPre <emd222@cornell.edu>
---
 src/05-derivatives/02-common-data-types.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index cfd6d06eed..6e6329b843 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -75,7 +75,7 @@ addition, all processed files include the following metadata JSON fields:
 | ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
 | SkullStripped | REQUIRED. Boolean. Whether the volume was skull stripped (non-brain voxels set to zero) or not.                              |
 | Resolution    | REQUIRED if `res` keyword present. Dictionary of Indexes to Strings. Specifies the interpretation of the resolution keyword. |
-| Density       | REQUIRED if `den` keyword present. Dictionary of Strings to Strings. Specifies the interpretation of the resolution keyword. |
+| Density       | REQUIRED if `den` keyword present. Dictionary of Strings to Strings. Specifies the interpretation of the density keyword. |
 
 Example JSON file corresponding to `pipeline1/sub-001/func/sub-001_task-rest_run-1_space-MNI305_bold.json` above:
 

From 6f215335482851a41ca64986e2630b7e38c1cea9 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Mon, 19 Aug 2019 10:01:40 -0700
Subject: [PATCH 12/26] Address @robertoostenveld's comment

---
 src/05-derivatives/02-common-data-types.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index 6e6329b843..4c72c580ba 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -7,7 +7,7 @@ Template:
 ```Text
 <pipeline_name>/
     sub-<participant_label>/
-        anat|func|dwi/
+        anat|func|dwi|meg|eeg|ieeg|beh/
         <source_keywords>[_space-<space>][_res-<index>][_den-<label>][_desc-<label>]_<suffix>.<ext>
 ```
 

From 46d577cdeeb84a67642b2da26428cb0c6bbf65cb Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Thu, 29 Aug 2019 18:32:22 -0700
Subject: [PATCH 13/26] fix: ``res-<index>`` -> ``res-<label>`` + admonitions

---
 mkdocs.yml                                 |  1 +
 src/05-derivatives/02-common-data-types.md | 38 ++++++++++++++--------
 2 files changed, 25 insertions(+), 14 deletions(-)

diff --git a/mkdocs.yml b/mkdocs.yml
index 9728116ab7..0fc53bfe0f 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -10,6 +10,7 @@ markdown_extensions:
     - toc:
         anchorlink: true
     - pymdownx.superfences
+    - admonition
 plugins:
     - search
 docs_dir: 'src'
diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index d19ae5477d..afde70acdf 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -8,7 +8,7 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         anat|func|dwi|meg|eeg|ieeg|beh/
-        <source_keywords>[_space-<space>][_res-<index>][_den-<label>][_desc-<label>]_<suffix>.<ext>
+        <source_keywords>[_space-<space>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<ext>
 ```
 
 Processing in this context means transformations of data that does not change
@@ -30,13 +30,20 @@ Note that even though `space` and `desc` are
 optional at least one of them needs to be defined to avoid name conflict with
 the raw file.
 
-**Sampling**. When two or more instances of a given derivative are provided with resolution
-(or surface sampling density) being the only difference between them, then the `res`
-(for *resolution* of regularly sampled N-D data) and/or `den` (for *density* of non-parametric 
-surfaces) SHOULD be used to avoid name conflicts.
-Note that only files combining both regularly sampled (e.g., gridded) and surface sampled data
-(and their downstream derivatives) are allowed to present both `res` and `den` keywords
-simultaneously.
+**Sampling**. When two or more instances of a given derivative are provided
+with resolution (or surface sampling density) being the only difference
+between them, then the `res` (for *resolution* of regularly sampled N-D data)
+and/or `den` (for *density* of non-parametric surfaces) SHOULD be used to avoid
+name conflicts.
+Note that only files combining both regularly sampled (e.g., gridded) and surface
+sampled data (and their downstream derivatives) are allowed to present both `res`
+and `den` keywords simultaneously.
+
+!!! tip "Recommendation"
+    Although the `res` entity accepts any BIDS-valid `<label>`, it is
+    recommended to use one-based, consecutive indexes as label to preempt
+    inconsistencies between the value of `res` and the metadata embedded
+    within the actual file.
 
 Examples:
 
@@ -44,8 +51,8 @@ Examples:
 pipeline1/
     sub-001/
         func/
-            sub-001_task-rest_run-1_space-MNI305_res-1_bold.nii.gz
-            sub-001_task-rest_run-1_space-MNI305_res-2_bold.nii.gz
+            sub-001_task-rest_run-1_space-MNI305_res-lo_bold.nii.gz
+            sub-001_task-rest_run-1_space-MNI305_res-hi_bold.nii.gz
             sub-001_task-rest_run-1_space-MNI305_bold.json
 ```
 
@@ -74,7 +81,7 @@ addition, all processed files include the following metadata JSON fields:
 | **Key name**  | **Description**                                                                                                              |
 | ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
 | SkullStripped | REQUIRED. Boolean. Whether the volume was skull stripped (non-brain voxels set to zero) or not.                              |
-| Resolution    | REQUIRED if `res` keyword present. Dictionary of Indexes to Strings. Specifies the interpretation of the resolution keyword. |
+| Resolution    | REQUIRED if `res` keyword present. Dictionary of Strings to Strings. Specifies the interpretation of the resolution keyword. |
 | Density       | REQUIRED if `den` keyword present. Dictionary of Strings to Strings. Specifies the interpretation of the density keyword.    |
 
 Example JSON file corresponding to
@@ -84,8 +91,8 @@ Example JSON file corresponding to
 {
   "SkullStripped": true,
   "Resolution": {
-    "1": "Matched with original BOLD resolution (2x2x3 mm^3)",
-    "2": "Matched with high-resolution T1w (0.7mm, isotropic)"
+    "hi": "Matched with high-resolution T1w (0.7mm, isotropic)",
+    "lo": "Matched with original BOLD resolution (2x2x3 mm^3)"
   }
 }
 ```
@@ -99,6 +106,8 @@ pipeline1/
         func/
             sub-001_task-rest_run-1_res-1_den-10k_bold.dtseries.nii
             sub-001_task-rest_run-1_res-1_den-41k_bold.dtseries.nii
+            sub-001_task-rest_run-1_res-2_den-10k_bold.dtseries.nii
+            sub-001_task-rest_run-1_res-2_den-41k_bold.dtseries.nii
             sub-001_task-rest_run-1_bold.dtseries.json
 ```
 
@@ -108,7 +117,8 @@ And the corresponding `sub-001_task-rest_run-1_bold.dtseries.json` file:
 {
     "SkullStripped": true,
     "Resolution": {
-        "1": "Matched with MNI152NLin6Asym 1.6mm isotropic"
+        "1": "Matched with MNI152NLin6Asym 1.6mm isotropic",
+        "2": "Matched with MNI152NLin6Asym 2.0mm isotropic"
     },
     "Density": {
         "10k": "10242 vertices per hemisphere (5th order icosahedron)",

From c8dd017076b597b1024ef90108a5c52584b3c243 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Thu, 29 Aug 2019 18:45:56 -0700
Subject: [PATCH 14/26] fix: cover one @effigies' suggestion

---
 src/05-derivatives/02-common-data-types.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index afde70acdf..104ce4eaf5 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -97,6 +97,27 @@ Example JSON file corresponding to
 }
 ```
 
+This would be equivalent to having two JSON metadata files, one
+corresponding to `res-lo`
+(`pipeline1/sub-001/func/sub-001_task-rest_run-1_space-MNI305_res-lo_bold.json`):
+
+```JSON
+{
+  "SkullStripped": true,
+  "Resolution": "Matched with original BOLD resolution (2x2x3 mm^3)"
+}
+```
+
+And one corresponding to `res-hi`
+(`pipeline1/sub-001/func/sub-001_task-rest_run-1_space-MNI305_res-hi_bold.json`):
+
+```JSON "pipeline1/sub-001/func/sub-001_task-rest_run-1_space-MNI305_res-hi_bold.json"
+{
+  "SkullStripped": true,
+  "Resolution": "Matched with high-resolution T1w (0.7mm, isotropic)"
+}
+```
+
 Example of CIFTI files (i.e., a file that combines regularly sampled data
 and non-parametric surfaces) having both `res` and `den` keywords:
 

From 7df08993e2ce29fcc0c0ca0e7ef99ded0a5c9b0f Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Thu, 29 Aug 2019 18:50:14 -0700
Subject: [PATCH 15/26] remove unnecessary edit

---
 src/05-derivatives/02-common-data-types.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index 104ce4eaf5..c8e7e97cd1 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -166,7 +166,7 @@ be set to `orig`.
 JSON metadata fields:
 
 | **Key name** | **Description**                                                                                                                                |
-| ------------ |----------------------------------------------------------------------------------------------------------------------------------------------- |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
 | RawSources   | Same as defined in [Introduction](01-introduction.md), but elevated from OPTIONAL to REQUIRED                                                  |
 | Type         | RECOMMENDED. Short identifier of the mask. Reserved values: `Brain` - brain mask, `Lesion` - lesion mask, `Face` - face mask, `ROI` - ROI mask |
 

From 0bbef9dcdd54ac32486cc1ac314d7c3c5a4b86f3 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Thu, 29 Aug 2019 19:04:46 -0700
Subject: [PATCH 16/26] fix: example with bad formatting

---
 src/05-derivatives/02-common-data-types.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index c8e7e97cd1..c4d04a2881 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -111,7 +111,7 @@ corresponding to `res-lo`
 And one corresponding to `res-hi`
 (`pipeline1/sub-001/func/sub-001_task-rest_run-1_space-MNI305_res-hi_bold.json`):
 
-```JSON "pipeline1/sub-001/func/sub-001_task-rest_run-1_space-MNI305_res-hi_bold.json"
+```JSON
 {
   "SkullStripped": true,
   "Resolution": "Matched with high-resolution T1w (0.7mm, isotropic)"

From c56fad628bd19ae12e5fd88d9bd00d8381a6b492 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Wed, 4 Dec 2019 12:39:04 -0500
Subject: [PATCH 17/26] RF: Move res/den keywords to imaging derivatives

---
 src/05-derivatives/02-common-data-types.md | 26 +-------------
 src/05-derivatives/03-imaging.md           | 41 +++++++++++++++++++++-
 2 files changed, 41 insertions(+), 26 deletions(-)

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index d6330d5241..8c6fc4b058 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -8,7 +8,7 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         <datatype>/
-            <source_keywords>[_space-<space>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<ext>
+            <source_keywords>[_space-<space>][_desc-<label>]_<suffix>.<ext>
 ```
 
 Preprocessing in this context means transformations of data that do not change
@@ -31,32 +31,8 @@ processing for the same input data.
 Note that even though `space` and `desc` are optional at least one of them MUST
 be defined to avoid name conflict with the raw file.
 
-**Sampling**. When two or more instances of a given derivative are provided
-with resolution (or surface sampling density) being the only difference
-between them, then the `res` (for *resolution* of regularly sampled N-D data)
-and/or `den` (for *density* of non-parametric surfaces) SHOULD be used to avoid
-name conflicts.
-Note that only files combining both regularly sampled (e.g., gridded) and surface
-sampled data (and their downstream derivatives) are allowed to present both `res`
-and `den` keywords simultaneously.
-
-!!! tip "Recommendation"
-    Although the `res` entity accepts any BIDS-valid `<label>`, it is
-    recommended to use one-based, consecutive indexes as label to preempt
-    inconsistencies between the value of `res` and the metadata embedded
-    within the actual file.
-
 Examples:
 
-```Text
-pipeline1/
-    sub-001/
-        func/
-            sub-001_task-rest_run-1_space-MNI305_res-lo_bold.nii.gz
-            sub-001_task-rest_run-1_space-MNI305_res-hi_bold.nii.gz
-            sub-001_task-rest_run-1_space-MNI305_bold.json
-```
-
 ```Text
 pipeline1/
     sub-001/
diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index 7af6315deb..77107ca5f4 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -5,10 +5,49 @@ extent and resolution.
 
 ## Preprocessed, coregistered and/or resampled volumes
 
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        <datatype>/
+            <source_keywords>[_space-<space>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<ext>
+```
+
+
 Volumetric preprocessing does not modify the number of dimensions, and so
 the specifications in [Preprocessed or cleaned data][common_preproc]
 apply.
-In addition, all processed files include the following metadata JSON fields:
+The use of surface meshes and volumetric measures sampled to those meshes is
+sufficiently similar in practice to treat them equivalently.
+
+When two or more instances of a given derivative are provided with resolution
+(or surface sampling density) being the only difference between them, then the
+`res` (for *resolution* of regularly sampled N-D data) and/or `den` (for
+*density* of non-parametric surfaces) SHOULD be used to avoid name conflicts.
+Note that only files combining both regularly sampled (e.g., gridded) and surface
+sampled data (and their downstream derivatives) are allowed to present both `res`
+and `den` keywords simultaneously.
+
+!!! tip "Recommendation"
+    Although the `res` entity accepts any BIDS-valid `<label>`, it is
+    recommended to use one-based, consecutive indices as label to avoid
+    inconsistencies between the value of `res` and the metadata embedded
+    within the actual file.
+
+Examples:
+
+```Text
+pipeline1/
+    sub-001/
+        func/
+            sub-001_task-rest_run-1_space-MNI305_res-lo_bold.nii.gz
+            sub-001_task-rest_run-1_space-MNI305_res-hi_bold.nii.gz
+            sub-001_task-rest_run-1_space-MNI305_bold.json
+```
+
+
+The following metadata JSON fields are defined for preprocessed images:
 
 | **Key name**  | **Description**                                                                                                              |
 | ------------- | ---------------------------------------------------------------------------------------------------------------------------- |

From 785c8cdcbcc5a75fe9b4bea12bf28e3e7bd4232c Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Mon, 9 Dec 2019 13:37:47 -0500
Subject: [PATCH 18/26] REVERT Removal of example from Common Data Types

---
 src/05-derivatives/02-common-data-types.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index 8c6fc4b058..6e58e42d23 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -33,6 +33,14 @@ be defined to avoid name conflict with the raw file.
 
 Examples:
 
+```Text
+pipeline1/
+    sub-001/
+        func/
+            sub-001_task-rest_run-1_space-MNI305_bold.nii.gz
+            sub-001_task-rest_run-1_space-MNI305_bold.json
+```
+
 ```Text
 pipeline1/
     sub-001/

From d4844167da2625dd75d12312040c25944ec05bb8 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Mon, 9 Dec 2019 13:38:59 -0500
Subject: [PATCH 19/26] Drop tip that does not match context

---
 src/05-derivatives/03-imaging.md | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index 77107ca5f4..fd29df78c4 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -29,12 +29,6 @@ Note that only files combining both regularly sampled (e.g., gridded) and surfac
 sampled data (and their downstream derivatives) are allowed to present both `res`
 and `den` keywords simultaneously.
 
-!!! tip "Recommendation"
-    Although the `res` entity accepts any BIDS-valid `<label>`, it is
-    recommended to use one-based, consecutive indices as label to avoid
-    inconsistencies between the value of `res` and the metadata embedded
-    within the actual file.
-
 Examples:
 
 ```Text

From 8f834c7b890b7d9dd13db3a2bc790acff67fa4d2 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Mon, 9 Dec 2019 13:41:49 -0500
Subject: [PATCH 20/26] STY: Satisfy linter

---
 src/05-derivatives/03-imaging.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index fd29df78c4..9f60d89d73 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -14,7 +14,6 @@ Template:
             <source_keywords>[_space-<space>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<ext>
 ```
 
-
 Volumetric preprocessing does not modify the number of dimensions, and so
 the specifications in [Preprocessed or cleaned data][common_preproc]
 apply.
@@ -40,7 +39,6 @@ pipeline1/
             sub-001_task-rest_run-1_space-MNI305_bold.json
 ```
 
-
 The following metadata JSON fields are defined for preprocessed images:
 
 | **Key name**  | **Description**                                                                                                              |

From 4002ab47411b13b37e95cc8148fd3a8a63f9a34e Mon Sep 17 00:00:00 2001
From: oesteban <code@oscaresteban.es>
Date: Tue, 28 Jan 2020 10:16:32 -0800
Subject: [PATCH 21/26] enh: include @robertoostenveld's suggestion

---
 src/05-derivatives/01-introduction.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index d96715bb9d..8dd652f093 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -148,7 +148,7 @@ share the following (non-required) ones:
 | Description      | RECOMMENDED. Free-form natural language description of the nature of the file.                                                                                                                                                                                                                                                                        |
 | Sources          | OPTIONAL. A list of paths relative to dataset root pointing to the file(s) that were directly used in the creation of this derivative. For example in a chain of A->B->C, “C” should only list “B” as Sources, and “B” should only list “A” as Sources. However in case X and Y jointly contribute to Z, then “Z” should list “X” and “Y” as Sources. |
 | RawSources       | OPTIONAL. A list of paths relative to dataset root pointing to the BIDS-Raw file(s) that were used in the creation of this derivative. When the derivative filename does not define a `space` keyword, the first entry of `RawSources` MUST be defined and it will define the `scanner` coordinate system that applies.                               |
-| SpatialReference | REQUIRED when a custom template or file is used. A path to a file that was used as, or can be used as, a reference image for determining the coordinate space of this file. The path should start with a `/` and should be relative to the root of the dataset.                                                                                       |
+| SpatialReference | REQUIRED in case a custom reference image was used. A path to a file that was used as, or can be used as, a reference image for determining the coordinate space of this file. The path should start with a `/` and should be relative to the root of the dataset.                                                                                    |
 
 ### SpatialReference key allowed values
 

From 0b99b7ce3df004b8d8ba488c600f21d28a1862ee Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Thu, 21 May 2020 09:18:51 -0400
Subject: [PATCH 22/26] ENH: Add SpatialReference dictionary option and example

---
 src/05-derivatives/01-introduction.md | 37 +++++++++++++++++++++++----
 1 file changed, 32 insertions(+), 5 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 8dd652f093..3f2c866222 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -113,7 +113,7 @@ The coordinate system (a.k.a. space) a particular derivative is in SHOULD be
 denoted using a filename keyword `space` whenever such keyword is present in
 the filename template of a given derivative type. The allowed values for this
 keyword depend are identifiers given in section [Image-Based Coordinate
-Systems](../99-appendices/08-coordinate-systems.md#image-based-coordinate-systems).
+Systems][coordsys].
 
 | File format                  | Description             |
 | ---------------------------- | ----------------------- |
@@ -148,14 +148,18 @@ share the following (non-required) ones:
 | Description      | RECOMMENDED. Free-form natural language description of the nature of the file.                                                                                                                                                                                                                                                                        |
 | Sources          | OPTIONAL. A list of paths relative to dataset root pointing to the file(s) that were directly used in the creation of this derivative. For example in a chain of A->B->C, “C” should only list “B” as Sources, and “B” should only list “A” as Sources. However in case X and Y jointly contribute to Z, then “Z” should list “X” and “Y” as Sources. |
 | RawSources       | OPTIONAL. A list of paths relative to dataset root pointing to the BIDS-Raw file(s) that were used in the creation of this derivative. When the derivative filename does not define a `space` keyword, the first entry of `RawSources` MUST be defined and it will define the `scanner` coordinate system that applies.                               |
-| SpatialReference | REQUIRED in case a custom reference image was used. A path to a file that was used as, or can be used as, a reference image for determining the coordinate space of this file. The path should start with a `/` and should be relative to the root of the dataset.                                                                                    |
+| SpatialReference | REQUIRED in case a custom reference image was used. OPTIONAL if a coordinate system listed in [Image-Based Coordinate Systems][coordsys] is used. For images with a single reference, the value MUST be a single string. For images with multiple references, such as surface and volume references, a data dictionary MUST be used.                  |
 
 ### SpatialReference key allowed values
 
-| **Value name** | **Description**                                                                                                               |
+| **Value**      | **Description**                                                                                                               |
 | -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| orig           | A (potentially unique) per-image space. Useful for describing the source of transforms from an input image to a target space. |
-| uri or path    | This can be used to point to a specific file.                                                                                 |
+| `"orig"`       | A (potentially unique) per-image space. Useful for describing the source of transforms from an input image to a target space. |
+| URI or path    | This can be used to point to a specific file. Paths are written relative to the root of the derivative dataset.               |
+
+In the case of images with multiple references, a data dictionary must link the relevant structures to reference files.
+If a single volumetric reference is used for multiple structures, the `VolumeReference` key MAY be used to reduce duplication.
+For CIFTI-2 images, the relevant structures are BrainStructure values defined in the BrainModel elements found in the CIFTI-2 header.
 
 ### Examples
 
@@ -173,6 +177,27 @@ sub-01/func/sub-01_task-rest_space-individual_bold.json
 }
 ```
 
+Preprocessed `bold` CIFTI-2 files that have been sampled to the fsLR surface
+meshes defined in the Conte69 atlas along with the MNI152NLin6Asym template.
+In this example, because all volumetric structures are sampled to the same
+reference, the `VolumeReference` key is used as a default, and only the
+surface references need to be specified by BrainStructure names.
+
+```Text
+sub-01/func/sub-01_task-rest_space-fsLR_den-91k_bold.dtseries.nii
+sub-01/func/sub-01_task-rest_space-fsLR_den-91k_bold.json
+```
+
+```JSON
+{
+    "SpatialReference": {
+        "VolumeReference": "https://templateflow.s3.amazonaws.com/tpl-MNI152NLin6Asym_res-02_T1w.nii.gz",
+        "CIFTI_STRUCTURE_CORTEX_LEFT": "https://github.com/mgxd/brainplot/raw/master/brainplot/Conte69_Atlas/Conte69.L.midthickness.32k_fs_LR.surf.gii",
+        "CIFTI_STRUCTURE_CORTEX_RIGHT": "https://github.com/mgxd/brainplot/raw/master/brainplot/Conte69_Atlas/Conte69.R.midthickness.32k_fs_LR.surf.gii"
+    }
+}
+```
+
 Participant cortical thickness GIFTI file in `individual` coordinate space.
 Please mind that in this case `SpatialReference` key is REQUIRED.
 
@@ -280,3 +305,5 @@ storage/distribution non-compliant derivatives of BIDS datasets.
 In particular, if a BIDS dataset contains a `derivatives/` sub-directory,
 the contents of that directory may be a heterogeneous mix of BIDS Derivatives
 datasets and non-compliant derivatives.
+
+[coordsys]: ../99-appendices/08-coordinate-systems.md#image-based-coordinate-systems

From f60de9064d462980d01d0f3a68d5d2a422a54811 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Thu, 21 May 2020 16:12:02 -0400
Subject: [PATCH 23/26] STY: Drop parens

---
 src/05-derivatives/03-imaging.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index fdb4171623..03720f3096 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -21,7 +21,7 @@ The use of surface meshes and volumetric measures sampled to those meshes is
 sufficiently similar in practice to treat them equivalently.
 
 When two or more instances of a given derivative are provided with resolution
-(or surface sampling density) being the only difference between them, then the
+or surface sampling density being the only difference between them, then the
 `res` (for *resolution* of regularly sampled N-D data) and/or `den` (for
 *density* of non-parametric surfaces) SHOULD be used to avoid name conflicts.
 Note that only files combining both regularly sampled (e.g., gridded) and surface

From e7f6341eace63b1a48f340df6fc597e2ed4c6a0c Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Thu, 21 May 2020 16:12:29 -0400
Subject: [PATCH 24/26] Allow resolution/density to be a string or dictionary

---
 src/05-derivatives/03-imaging.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index 03720f3096..ca0282ffb8 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -41,11 +41,11 @@ pipeline1/
 
 The following metadata JSON fields are defined for preprocessed images:
 
-| **Key name**  | **Description**                                                                                                              |
-| ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| SkullStripped | REQUIRED. Boolean. Whether the volume was skull stripped (non-brain voxels set to zero) or not.                              |
-| Resolution    | REQUIRED if `res` keyword present. Dictionary of Strings to Strings. Specifies the interpretation of the resolution keyword. |
-| Density       | REQUIRED if `den` keyword present. Dictionary of Strings to Strings. Specifies the interpretation of the density keyword.    |
+| **Key name**  | **Description**                                                                                                                |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| SkullStripped | REQUIRED. Boolean. Whether the volume was skull stripped (non-brain voxels set to zero) or not.                                |
+| Resolution    | REQUIRED if `res` is present. String or dictionary of label to string. Specifies the interpretation of the resolution keyword. |
+| Density       | REQUIRED if `den` is present. String or dictionary of label to string. Specifies the interpretation of the density keyword.    |
 
 Example JSON file corresponding to
 `pipeline1/sub-001/func/sub-001_task-rest_run-1_space-MNI305_bold.json` above:

From b874e086d1dd2f0cb9817c1c55b3079c406e75b0 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Thu, 21 May 2020 16:12:57 -0400
Subject: [PATCH 25/26] Eliminate dtseries.json example, add space-fsLR to
 avoid ambiguity

---
 src/05-derivatives/03-imaging.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index ca0282ffb8..5a5626a1dd 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -81,21 +81,21 @@ And one corresponding to `res-hi`
 }
 ```
 
-Example of CIFTI files (i.e., a file that combines regularly sampled data
+Example of CIFTI-2 files (a format that combines regularly sampled data
 and non-parametric surfaces) having both `res` and `den` keywords:
 
 ```Text
 pipeline1/
     sub-001/
         func/
-            sub-001_task-rest_run-1_res-1_den-10k_bold.dtseries.nii
-            sub-001_task-rest_run-1_res-1_den-41k_bold.dtseries.nii
-            sub-001_task-rest_run-1_res-2_den-10k_bold.dtseries.nii
-            sub-001_task-rest_run-1_res-2_den-41k_bold.dtseries.nii
-            sub-001_task-rest_run-1_bold.dtseries.json
+            sub-001_task-rest_run-1_space-fsLR_res-1_den-10k_bold.dtseries.nii
+            sub-001_task-rest_run-1_space-fsLR_res-1_den-41k_bold.dtseries.nii
+            sub-001_task-rest_run-1_space-fsLR_res-2_den-10k_bold.dtseries.nii
+            sub-001_task-rest_run-1_space-fsLR_res-2_den-41k_bold.dtseries.nii
+            sub-001_task-rest_run-1_space-fsLR_bold.json
 ```
 
-And the corresponding `sub-001_task-rest_run-1_bold.dtseries.json` file:
+And the corresponding `sub-001_task-rest_run-1_space-fsLR_bold.json` file:
 
 ```JSON
 {

From d51893377213b5f86a88e64261fe0a4817a58ec7 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Thu, 21 May 2020 19:11:46 -0400
Subject: [PATCH 26/26] Update src/05-derivatives/01-introduction.md

Co-authored-by: Oscar Esteban <code@oscaresteban.es>
---
 src/05-derivatives/01-introduction.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 39c549726f..4a30f16287 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -154,7 +154,7 @@ share the following (non-required) ones:
 
 | **Value**      | **Description**                                                                                                               |
 | -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `"orig"`       | A (potentially unique) per-image space. Useful for describing the source of transforms from an input image to a target space. |
+| `orig`         | A (potentially unique) per-image space. Useful for describing the source of transforms from an input image to a target space. |
 | URI or path    | This can be used to point to a specific file. Paths are written relative to the root of the derivative dataset.               |
 
 In the case of images with multiple references, a data dictionary must link the relevant structures to reference files.