[ENH] Add res and den keywords to indicate resolution of resampled data

mkdocs.yml

@@ -10,6 +10,7 @@ markdown_extensions:
     - toc:
         anchorlink: true
     - pymdownx.superfences
+    - admonition
 plugins:
     - search
     - branchcustomization:

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

src/05-derivatives/03-imaging.md

@@ -5,14 +5,111 @@ 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.
+
+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**                                                                                                                |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| 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:
+
+```JSON
+{
+  "SkullStripped": true,
+  "Resolution": {
+    "hi": "Matched with high-resolution T1w (0.7mm, isotropic)",
+    "lo": "Matched with original BOLD resolution (2x2x3 mm^3)"
+  }
+}
+```
 
-| **Key name**  | **Description**                                                                                 |
-| ------------- | ----------------------------------------------------------------------------------------------- |
-| SkullStripped | REQUIRED. Boolean. Whether the volume was skull stripped (non-brain voxels set to zero) or not. |
+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
+{
+  "SkullStripped": true,
+  "Resolution": "Matched with high-resolution T1w (0.7mm, isotropic)"
+}
+```
+
+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_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_space-fsLR_bold.json` file:
+
+```JSON
+{
+    "SkullStripped": true,
+    "Resolution": {
+        "1": "Matched with MNI152NLin6Asym 1.6mm isotropic",
+        "2": "Matched with MNI152NLin6Asym 2.0mm isotropic"
+    },
+    "Density": {
+        "10k": "10242 vertices per hemisphere (5th order icosahedron)",
+        "41k": "40962 vertices per hemisphere (6th order icosahedron)"
+    }
+}
+```
 
 ## Masks