From 58dcce72a20be8f4a2367c670777dbb9579af003 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Sun, 16 Dec 2018 11:41:38 -0800
Subject: [PATCH 001/191] Adding derivatives

---
 src/05-derivatives/01-introduction.md         | 218 ++++++++++
 src/05-derivatives/02-common-data-types.md    | 311 ++++++++++++++
 .../03-structural-derivatives.md              | 136 +++++++
 .../04-functional-derivatives.md              | 373 +++++++++++++++++
 .../05-diffusion-derivatives.md               | 381 ++++++++++++++++++
 src/99-appendices/08-coordinate-systems.md    |  55 ++-
 6 files changed, 1470 insertions(+), 4 deletions(-)
 create mode 100644 src/05-derivatives/01-introduction.md
 create mode 100644 src/05-derivatives/02-common-data-types.md
 create mode 100644 src/05-derivatives/03-structural-derivatives.md
 create mode 100644 src/05-derivatives/04-functional-derivatives.md
 create mode 100644 src/05-derivatives/05-diffusion-derivatives.md

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
new file mode 100644
index 0000000000..04276d1f24
--- /dev/null
+++ b/src/05-derivatives/01-introduction.md
@@ -0,0 +1,218 @@
+# Goals and scope
+
+Derivatives are outputs of common processing pipelines, capturing data and
+meta-data sufficient for a researcher to understand and (critically) reuse those
+outputs in subsequent processing. Standardizing derivatives is motivated by use
+cases where formalized machine-readable access to processed data enables higher
+level processing.
+
+## Storage of derived datasets
+
+Derivatives can be stored/distributed in two ways:
+
+1.  Under a `derivatives/` subfolder in the root of the source BIDS dataset
+    folder to make a clear distinction between raw data and results of data
+    processing. Each pipeline has a dedicated directory under which it stores
+    all of its outputs. There is no restriction on the directory name; however,
+    it is RECOMMENDED to use the format `<pipeline>-<variant>` in cases where it
+    is anticipated that the same pipeline will output more than one variant
+    (e.g., `AFNI-blurring`, `AFNI-noblurring`, etc.).
+
+    For example:
+
+    ```Text
+    <dataset>/derivatives/fmripreprocess_01/sub-0001
+    <dataset>/derivatives/spm/sub-0001
+    <dataset>/derivatives/vbm/sub-0001
+    ```
+
+1.  As a standalone dataset independent of the source (raw or derived) BIDS
+    dataset. This way of specifying derivatives is particularly useful when the
+    source dataset is provided with read-only access, and for publishing
+    derivatives as independent bodies of work, or for describing derivatives
+    that were created from more than one source dataset.
+
+The rest of the Derivatives specification assumes Case 1, but Case 2 applies
+after removing `/derivatives/<pipeline_name>` from template names. In both cases
+every derivatives dataset is considered a BIDS dataset and must include a
+`dataset_description.json` file at the root level. Consequently, files should be
+organized to comply with the BIDS to the full extent possible (i.e., unless
+explicitly contradicted below). Any subject-specific derivatives should be
+housed within each subject’s directory; if session-specific derivatives are
+generated, they should be deposited under a session subdirectory within the
+corresponding subject directory; and so on.
+
+In addition pipelines may generate derivatives that do not strictly belong to
+any single participant. To write group-level results, the `group/` folder for
+example `<dataset>/derivatives/<pipeline_name>/group/`.
+
+## Derived dataset and pipeline description
+
+As for any BIDS dataset a `dataset_description.json` file MUST be found at the
+top level of the particular pipeline:
+`<dataset>/derivatives/<pipeline_name>/dataset_description.json`
+
+In addition to raw BIDS datasets derived BIDS datasets includ the following
+required or recommended `dataset_description.json` keys (a dot in the Key name
+denotes a key in a subdictionary):
+
+| **Key name**                                | **Description**                                                                                                                                                       |
+| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| PipelineDescription.Name                    | REQUIRED. Name of the pipeline that generated the outputs.                                                                                                            |
+| PipelineDescription.Version                 | OPTIONAL. Version of the pipeline.                                                                                                                                    |
+| PipelineDescription.CodeURL                 | OPTIONAL. URL where the code for the analysis can be found.                                                                                                           |
+| PipelineDescription.DockerHubContainerTag   | OPTIONAL. Docker Hub tag where the software container image used in this analysis can be found.                                                                       |
+| PipelineDescription.SingularityContainerURL | OPTIONAL. URL where the Singularity software container image used in this analysis can be found.                                                                      |
+| 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:
+
+```JSON
+{
+    "Name": "FMRIPREP Outputs",
+    "BIDSVersion": "TODO (depends when this PR will be merged)",
+    "PipelineDescription": {
+        "Name": "FMRIPREP",
+        "Version": "1.2.5",
+        "DockerHubContainerTag": "poldracklab/fmriprep:1.2.5"
+        },
+    "SourceDatasets": [
+        {
+            "DOI": "10.18112/openneuro.ds000114.v1.0.1",
+            "URL": "https://openneuro.org/datasets/ds000114/versions/1.0.1",
+            "Version": "1.0.1"
+        }
+    ]
+}
+```
+
+## Common file level metadata fields
+
+Each derivative file SHOULD be described by a JSON file provided as a sidecar or
+higher up in the hierarchy of the derived dataset (according to Inheritance
+Principle - section 3.5 of the main specification) unless a particular
+derivative includes REQUIRED metadata fields in which case a JSON file is also
+REQUIRED. Each derivative type defines their own set of fields, but all of them
+share the following (non-required) ones:
+
+| **Key name**         | **Description**                                                                                                                                                                                                                                                                                                                                       |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Description          | RECOMMENDED. Freeform 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.                                                                                                                                                                                                               |
+| CoordinateSystem     | REQUIRED if no implicit coordinate system. Key indicates the coordinate system associated with the File. The coordinate system can be implicit to the File, for instance when data are images stored in NIfTI format. Can be a list. See Table below for list of allowed systems.                                                                     |
+| ReferenceMap         | REQUIRED when coordinate system is Aligned. Key indicates the reference atlas or map that the File is aligned to. See table below for list of common spaces.                                                                                                                                                                                          |
+| NonstandardReference | REQUIRED when a non standard template or space is used. (e.g., a custom template in MNI305 space). 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. If Space is a list, Space reference must also be a list.                                                                |
+| ReferenceIndex       | REQUIRED when an index into a 4D (ReferenceMap or NonstandardReference) file is used. Used to index into a 4D spatial-reference file.                                                                                                                                                                                                                 |
+| TransformFile        | OPTIONAL. A path to the file used to transform the source into this file.                                                                                                                                                                                                                                                                             |
+
+### CoordinateSystem key allowed values
+
+| **Value name** | **Description**                                                                                                                         |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| Device         | The coordinate system of the device used to acquire the data.                                                                           |
+| Aligned        | The coordinate system is specified by a target space (e.g., Talairach88, MNI305, etc.,.). See the Space keyword for details of targets. |
+| Custom         | A custom coordinate system that is not in alignment (dimensions, axis orientation, unit) with any device coordinate system.             |
+
+### ReferenceMap key allowed values
+
+In addition to values defined in
+[Appendix VII Table "Template based Coordinate Systems"](../99-appendices/08-coordinate-systems.md).
+
+| **Value name** | **Description**                                                                                                                                  |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| orig           | A (potentially unique) per-image space. Useful for describing the source of transforms from an input image to a target space.                    |
+| custom         | This can be used to point to the non-standard space of a file. This should be used only if the reference file is not in any of the other spaces. |
+
+### Example sidecar files
+
+For a NIFTI file (Single coordinate system), one could have registered the File
+on to the standard MNI305 template. The way to write the metadata of such 
+File is:
+
+```JSON
+{
+    "TransformFile": "/path/to/xfm",
+    "ReferenceMap": "MNI305"
+}
+```
+
+However, it could also be the case that a nonstandard derivative of MNI305 was 
+used as standard space for the File. That can be written as follows:
+
+```JSON
+{
+    "TransformFile": "/path/to/xfm",
+    "NonstandardReference": "uri or path to file"
+}
+```
+
+Some derivatives such as CIFTI Files allow for multiple coordinate systems. 
+Such possibility is enabled by using lists of spaces and references:
+
+```JSON
+{
+    "TransformFile": "/path/to/xfm",
+    "ReferenceMap": ["MNI305", "fsLR32k"] 
+}
+```
+
+Differing references of the same spaces with respect to the above example can 
+be expressed as follows:
+
+```JSON
+{
+    "TransformFile": "/path/to/xfm",
+    "ReferenceMap": ["MNI152Lin", "fsLR164k"] 
+}
+```
+
+## Metadata conventions
+
+-   Unless specified otherwise, individual sidecar JSON files and all metadata 
+    fields within are optional. However, the appropriate use of these files and 
+    pertinent fields is very valuable and thus encouraged. Moreover, for some 
+    types of files, there may be one or more required metadata fields, in which 
+    case at least one metadata file containing that field must be located 
+    somewhere within the file’s hierarchy (per the Inheritance Principle).
+
+-   When chaining derivative pipelines, any JSON fields that were specified as 
+    mandatory in the input files should be propagated forward in the output 
+    file’s JSON provided they remain valid. Non-required JSON fields can be 
+    propagated, and are highly useful, but it is the pipeline’s responsibility 
+    to ensure that the values are still relevant and appropriate to the type of 
+    output data.
+
+## File naming conventions
+
+-   Filenames that are permissible for a raw BIDS data type have a privileged 
+    status. Any modification of raw files must use a modified filename that 
+    does not conflict with the raw filename. Further, any files created as 
+    part of a derivatived dataset must not match a permissible filename of a 
+    valid raw dataset. Stated equivalently, if any filename in a derivatived 
+    dataset has a name permissible for a raw BIDS data, then that file must 
+    be an identical copy of that raw file.
+
+-   Each Derivatives filename MUST be of the form: 
+    `<source_keywords>[_keyword-<value>]_<suffix>.<ext>`
+
+-   When the derivatives chain involves outputs derived from a single raw 
+    input, `source_keywords` MUST be the entire source filename, with the 
+    ommission of the source suffix and extension. One exception to this rule 
+    is filename keywords that are no longer relevant (such as `sub-` in the 
+    case of group level derivatives). Depending on the nature of the 
+    derivative file, the suffix can either be the same as the source file if 
+    that suffix is still appropriate, or a new appropriate value selected 
+    from the controlled list. 
+
+-   There is no prohibition against identical filenames in different derived 
+    datasets, although users should be aware of the potential ambiguity this 
+    can create and use the sidecar JSON files to detail the specifics of 
+    individual files.
+
+-   When necessary to distinguish two files, the `_desc-<value>` keyword-value 
+    should be used. This includes the cases of needing to distinguish both 
+    differing inputs and differing outputs (e.g., `_desc-T1w` and `_desc-T2w` 
+    to distinguish brain mask files derived from T1w and T2w images; or 
+    `_desc-sm4` and `_desc-sm8` to distinguish between outputs generated with 
+     two different levels of smoothing).
diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
new file mode 100644
index 0000000000..26ade07bd8
--- /dev/null
+++ b/src/05-derivatives/02-common-data-types.md
@@ -0,0 +1,311 @@
+# Common data types
+
+## Processed, coregistered and/or resampled volumes
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        func|anat|dwi/
+        <source_keywords>[_referencemap-<referencemap>][_desc-<label>]_<suffix>.<ext>
+```
+
+Processing in this context means transformations of data that does not change
+the number of dimensions of the input and are not explicitly covered by other
+data types in the specification. Examples:
+
+-   Motion-corrected, temporally denoised, and transformed to MNI space bold
+    files.
+
+-   Inhomogeneity corrected and skull stripped T1w files.
+
+-   Motion-corrected DWI files.
+
+The `referencemap` keyword denotes reference atlas or map that the File is
+aligned to - see [Introduction](01-introduction.md) for allowed values. The
+`desc` keyword is a general purpose field with freeform values. To distinguish
+between multiple different versions of processing for the same input data the
+`desc` keyword should be used. Note that even though `referencemap` and `desc`
+are optional at least one of them needs to be defined to avoid name conflict
+with the raw file.
+
+Examples:
+
+```Text
+pipeline1/
+    sub-001/
+        func/
+            sub-001_task-rest_run-1_referencemap-MNI305_bold.nii.gz
+            sub-001_task-rest_run-1_referencemap-MNI305_bold.json
+```
+
+```Text
+pipeline1/
+    sub-001/
+        func/
+            sub-001_task-rest_run-1_desc-MC_bold.nii.gz
+            sub-001_task-rest_run-1_desc-MC_bold.json
+```
+
+```Text
+pipeline1/
+    sub-001/
+        func/
+            sub-001_task-rest_run-1_desc-fmriprep_bold.nii.gz
+            sub-001_task-rest_run-1_desc-fmriprep_bold.json
+```
+
+All REQUIRED metadata fields coming from a derivative file’s source file(s) MUST
+be propagated to the JSON description of the derivative unless the processing
+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. Whether the volume was skull stripped (non-brain voxels set to zero) or not. |
+
+## Masks
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        func|anat|dwi/
+        <source_keywords>[_referencemap-<referencemap>][_type-<type>][_desc-<label>]_mask.nii.gz
+```
+
+A binary (1 - inside, 0 outside) mask in the space defined by `<referencemap>`.
+By default (i.e., if no transformation has taken place) the value of
+`referencemap` should 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 |
+
+Examples:
+
+```Text
+func_loc/
+    sub-001/
+        func/
+           sub-001_task-rest_run-1_space-MNI305_desc-PFC_mask.nii.gz
+           sub-001_task-rest_run-1_space-MNI305_desc-PFC_mask.json
+```
+
+```Text
+manual_masks/
+    sub-001/
+        anat/
+            sub-001_T1w_label-desc_mask.nii.gz
+            sub-001_T1w_label-desc_mask.json
+```
+
+## Segmentations and parcellations
+
+Common JSON metadata fields:
+
+| **Key name** | **Description**                                                                                    |
+| ------------ | -------------------------------------------------------------------------------------------------- |
+| Manual       | OPTIONAL. Boolean. Indicates if the segmenation was performed manually or via an automated process |
+| Atlas        | OPTIONAL. Which atlas (if any) was used to derive the segmentation.                                |
+
+### Discrete Segmentations
+
+Discrete segmentations of brain tissue represent each tissue class with a unique
+integer label in a 3D volume. See "Anatomical Labels" for interpretation how
+integer values map to tissue classes.
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        func|anat|dwi/
+            <source_keywords>[_referencemap-<referencemap>space-<space>]_dseg.nii.gz
+```
+
+Example:
+
+```Text
+pipeline/
+    sub-001/
+        anat/
+            sub-001_space-ACPC_dseg.nii.gz
+            sub-001_space-ACPC_dseg.json
+```
+
+A segmentation could be a binary mask that functions as a discrete `label` for a
+single structure. In this case, the label key must be used to specify the
+corresponding structure. For example:
+
+```Text
+pipeline/
+    sub-001/
+        anat/
+            sub-001_space-ACPC_label-GM_dseg.nii.gz
+```
+
+See "Anatomical labels" for reserved key values for `label`.
+
+### Probabilistic Segmentations
+
+Probabilistic segmentations of brain tissue represent a single tissue class with
+values ranging from 0 to 1 in individual 3D volumes or across multiple frames.
+Similarly to a discrete, binary segmentation, the label key can be used to
+specify the corresponding structure.
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        func|anat|dwi/
+            <source_keywords>[_referencemap-<referencemap>space-<space>][_label-<label>]_probseg.nii.gz
+```
+
+Example:
+
+```Text
+pipeline/
+    sub-001/
+        anat/
+            sub-001_space-ACPC_label-BG_probseg.nii.gz
+            sub-001_space-ACPC_label-WM_probseg.nii.gz
+```
+
+See "Anatomical labels" for reserved key values for `label`.
+
+A 4D probabilistic segmentation, in which each frame corresponds to a different
+tissue class, must provide a label mapping in its JSON sidecar. For example:
+
+```Text
+pipeline/
+    sub-001/
+	    anat/
+		    sub-001_space-ACPC_probseg.nii.gz
+		    sub-001_space-ACPC_probseg.json
+```
+
+The JSON sidecar must include the label-map key that specifies a tissue label
+for each volume:
+
+```JSON
+{
+    "LabelMap": [
+        "BG",
+        "WM",
+        "GM"
+        ]
+}
+```
+
+Values of `label` need to map to Abbreviations defined in "Anatomical Labels".
+
+### Surface Parcellations
+
+Discrete parcellations (surface segmentations) of cortical structures should be
+stored as GIFTI or CIFTI file.
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        anat/
+            <source_keywords>[_hemi-{L|R}][_referencemap-<referencemap>]_dseg.{label.gii|dlabel.nii}
+```
+
+The REQUIRED extension for GIFTI parcellations is `.label.gii`. The hemi tag is
+REQUIRED for GIFTI files. For example:
+
+```Text
+pipeline/
+    sub-001/
+        anat/
+            sub-001_hemi-L_dparc.label.gii
+            sub-001_hemi-R_dparc.label.gii
+```
+
+The REQUIRED extension for CIFTI parcellations is `.dlabel.nii`. For example:
+
+```Text
+pipeline/
+    sub-001/
+        anat/
+            sub-001_dparc.dlabel.nii
+            sub-001_dparc.dlabel.nii
+```
+
+### Anatomical Labels
+
+BIDS supplies a standard, generic label-index dictionary, defined in the table
+below, that contains common tissue classes and can be used to map segmentations
+(and parcellations) between lookup tables.
+
+| Integer value | Description             | Abbreviation (label) |
+| ------------- | ----------------------- | -------------------- |
+| 0             | Background              | BG                   |
+| 1             | Grey Matter             | GM                   |
+| 2             | White Matter            | WM                   |
+| 3             | Cerebrospinal Fluid     | CSF                  |
+| 4             | Grey and White Matter   | GWM                  |
+| 5             | Bone                    | B                    |
+| 6             | Soft Tissue             | ST                   |
+| 7             | Non-brain               | NB                   |
+| 8             | Lesion                  | L                    |
+| 9             | Cortical Grey Matter    | CGM                  |
+| 10            | Subcortical Grey Matter | SCGM                 |
+| 11            | Brainstem               | BS                   |
+| 12            | Cerebellum              | CBM                  |
+
+These definitions can be overridden (or added to) by providing custom labels in
+a sidecar `<matches>.tsv` file, in which `<matches>` corresponds to segmentation
+filename.
+
+Example:
+
+```Text
+pipeline/
+    sub-001/
+        anat/
+            sub-001_space-ACPC_dseg.nii.gz
+            sub-001_space-ACPC_dseg.tsv
+```
+
+Definitions can also be specified with a top-level dseg.tsv, which propagates to
+segmentations in relative subdirectories.
+
+Example:
+
+```Text
+pipeline/
+	dseg.tsv
+    sub-001/
+        anat/
+            sub-001_space-ACPC_dseg.nii.gz
+```
+
+These tsv lookup tables should contain the following columns:
+
+| Column name | Description                                                             |
+| ----------- | ----------------------------------------------------------------------- |
+| index       | REQUIRED. The label integer index                                       |
+| name        | REQUIRED. The unique label name                                         |
+| abbr        | OPTIONAL. The unique label abbreviation                                 |
+| mapping     | OPTIONAL. Corresponding integer label in the standard BIDS label lookup |
+| color       | OPTIONAL. Hexadecimal. Label color for visualization                    |
+
+An example, custom dseg.tsv that defines three labels:
+
+```Text
+index   name            abbr	color       mapping
+100     "Grey Matter"	GM      #ff53bb	    1
+101     "White Matter"	WM      #2f8bbe	    2
+102     "Brainstem"     BS      #36de72	    11
+```
diff --git a/src/05-derivatives/03-structural-derivatives.md b/src/05-derivatives/03-structural-derivatives.md
new file mode 100644
index 0000000000..a2f3d14def
--- /dev/null
+++ b/src/05-derivatives/03-structural-derivatives.md
@@ -0,0 +1,136 @@
+# Structural (anatomical) derivatives
+
+## Reconstructed cortical surfaces
+
+Reconstructed cortical surfaces should be stored as GIFTI files, and each
+hemisphere should be stored separately.
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        anat/
+            <source_keywords>_hemi-{L|R}[_referencemap-<referencemap]_<surftype>.surf.gii
+```
+
+Example:
+
+```Text
+pipeline/
+    sub-001/
+        anat/
+            sub-001_hemi-L_pial.surf.gii
+            sub-001_hemi-R_pial.surf.gii
+```
+
+The supported surface types (`<surftype>` suffix) are:
+
+| Surface type | Description                                                          |
+| ------------ | -------------------------------------------------------------------- |
+| wm           | The gray matter / white matter border for the cortex                 |
+| smoothwm     | The smoothed matter / white matter border                            |
+| pial         | The gray matter / pial matter border                                 |
+| midthickness | The midpoints between wm and pial surfaces                           |
+| inflated     | An inflation of the midthickness surface (useful for visualization)  |
+| sphere       | The sphere (used for registration - see transforms for nomenclature) |
+| flat         | The flattened surface (used for visualization)                       |
+
+Note: reconstructed cortical surfaces are unique in that they contain both
+2-dimensional and 3-dimensional elements of "space".
+
+## Surface-Mapped Anatomical Scalar Derivatives
+
+Surface-mapped scalar overlays should be stored as either GIFTI or CIFTI files
+(which allow for the combination of left and right hemispheres).
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        anat/
+            <source_keywords>[_hemi-{L|R}][_referencemap-<referencemap>space-<space>]_<suffix>.{shape.gii|dscalar.nii}
+```
+
+The REQUIRED extension for scalar GiFTI files is `.shape.gii`. The `hemi` key is
+required for GiFTI files. For example:
+
+```Text
+pipeline/
+    sub-001/
+        anat/
+            sub-001_hemi-L_curv.shape.gii
+            sub-001_hemi-R_curv.shape.gii
+```
+
+The REQUIRED extension for scalar CIFTI files is `.dscalar.nii`. For example:
+
+```Text
+pipeline/
+    sub-001/
+        anat/
+            sub-001_curv.dscalar.nii
+```
+
+The file `<suffix>` should concisely describe the parameter that is represented
+in the overlay, and while the suffix can be individually customized, the
+following values should be reserved for their common use-cases:
+
+| Suffix       | Description                                           |
+| ------------ | ----------------------------------------------------- |
+| `curv`       | Cortical surface curvature indices                    |
+| `thickness`  | Cortical thickness                                    |
+| `area`       | Discretized surface area across regions               |
+| `dist`       | Distance from a point                                 |
+| `defects`    | Marked regions with surface defects                   |
+| `sulc`       | Sulcal depth                                          |
+| `myelinmap`  | Myelin map calculated from T1w to T2 ratio            |
+| `distortion` | Distortion map calculated from a surface registration |
+
+## Morphometrics
+
+Structural statistics produced by segmentation routines should be stored within
+tsv files, which could contain common parameters specified in the table below.
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        func|anat|dwi/
+            <source_keywords>[_desc-<label>]_morph.tsv
+
+```
+
+Example:
+
+```Text
+pipeline/
+    sub-001/
+        anat/
+            sub-001_desc-volumetric_morph.tsv
+```
+
+| Column name | Description                                     |
+| ----------- | ----------------------------------------------- |
+| index       | RECOMMENDED. Label integer index                |
+| name        | RECOMMENDED. Structure name                     |
+| centroid    | OPTIONAL. Center coordinate of structure        |
+| volume      | OPTIONAL. Volume of structure                   |
+| intensity   | OPTIONAL. Intensity of voxels within structure  |
+| thickness   | OPTIONAL. Thickness of cortical structure       |
+| area        | OPTIONAL. Surface area of cortical structure    |
+| curv        | OPTIONAL. Curvature index of cortical structure |
+
+Some parameters might require unit specification or have multiple associated
+statistics (such as avg, std, min, max, range). The suggested syntax for such
+columns is `<parameter>[-<stat>][-<units>]`. An example volumetric stats file
+might look something like this:
+
+```Text
+index  name               volume-mm3  intensity-avg  intensity-std
+11     Brainstem          23415.9     80.11          3.40
+32     Left-Hippocampus   5349.7      75.23          2.27
+32     Right-Hippocampus  4112.1      76.98          4.01
+```
diff --git a/src/05-derivatives/04-functional-derivatives.md b/src/05-derivatives/04-functional-derivatives.md
new file mode 100644
index 0000000000..431d803d24
--- /dev/null
+++ b/src/05-derivatives/04-functional-derivatives.md
@@ -0,0 +1,373 @@
+# Functional derivatives
+
+## Functional derivatives maps
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        func/
+            <source_keywords>[_referencemap-<referencemap>space-<space>][_desc-<label>]_<suffix>.nii[.gz]
+            <source_keywords>[_referencemap-<referencemap>space-<space>][_desc-<label>]_<suffix>.json
+```
+
+for example:
+
+```Text
+pipeline1/
+    sub-001/
+        func/
+            sub-001_task-rest_run-1_space-MNI305_mean.nii.gz
+            sub-001_task-rest_run-1_space-MNI305_mean.json
+```
+
+The following table lists allowed suffixes and their corresponding measures:
+
+| `<suffix>`       | Measure                                                          |
+| ---------------- | ---------------------------------------------------------------- |
+| `mean`           | Mean across the temporal/4th dimension of the data               |
+| `std`            | Standard deviation across the temporal/4th dimension of the data |
+| `tsnr`           | Temporal SNR (i.e. mean / std)                                   |
+| `sfs`            | Signal fluctuation sensitivity                                   |
+| `alff`           | Amplitude low frequency fluctuations                             |
+| `falff`          | Fractional amplitude of low frequency fluctuations               |
+| `reho`           | Regional homogeneity (voxelwise only)                            |
+| `dcb`, `dcw`     | Voxelwise degree centrality binary and weighted                  |
+| `ecb`, `ecw`     | Voxelwise eigenvector centrality binary and weighted             |
+| `lfcdb`, `lfcdw` | Local functional connectivity density                            |
+| `vmhc`           | Voxel mirrored homotopic connectivity                            |
+
+The following metadata JSON fields are valid for derivative maps:
+
+| Key name       | Description                                                               | Required for suffix        |
+| -------------- | ------------------------------------------------------------------------- | -------------------------- |
+| BandpassFilter | String describing all relevant parameters of the applied bandpass filter. | `alff`, `falff`            |
+| Neighborhood   | String describing neighborhood for regional measures.                     | `reho`                     |
+| Threshold      | String describing threshold used for determining graph edges.             | `dcb`, `dcw`, `ecb`, `ecw` |
+| Method         | String describing method used to calculate measure.                       | `dcb`, `dcw`, `ecb`, `ecw` |
+
+## Time series and regressors
+
+For the purposes of this section, a time series or regressor is a numeric series
+of values corresponding to volumes in a BOLD series. Time series is specifically
+used to indicate an aggregate time series within an ROI, while regressor is used
+as a more general term indicating series that may be derived from other sources,
+such as head motion estimates or physiological recordings.
+
+Regressors will generally be stored as tables, with a row of column headers
+indicating the name of the regressor. In the case where every voxel has a
+regressor, then the data should be stored in a 4D NIfTI file.
+
+Tabular regressor files MUST be accompanied by a data dictionary in JSON format,
+consistent with the format described in
+[Common princioples](../02common-principles.md).
+
+Volumetric regressor files MAY be accompanied by a data dictionary in JSON
+format, with OPTIONAL `LongName`, `Description`, `Levels`, `Units`, and
+`TermURL` fields.
+
+### General time series and regressors
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        func/
+	        <source_keywords>_[desc-<label>_]regressors.tsv
+	        <source_keywords>_[desc-<label>_]regressors.json
+```
+
+for example:
+
+```Text
+sub-001/
+    func/
+        sub-001_task-rest_run-1_desc-confounds_regressors.tsv
+        sub-001_task-rest_run-1_desc-confounds_regressors.json
+```
+
+Any time series or regressor with one value per BOLD volume may be stored in a
+regressors file. If a column is specified in another sub-section, then any
+additional required metadata MUST be stored in the JSON description of the
+column.
+
+#### Column names
+
+Column names are unique alphanumeric values that are defined in a relevant JSON
+sidecar file. For a series of related columns, it is RECOMMENDED to use
+zero-based indexing as a suffix. For example, the first six aCompCor components
+may be named `a_comp_cor_00` ... `a_comp_cor_05`. Custom column names must not
+conflict with reserved names specified in this document.
+
+Reserved names are specified in the remaining subsections.
+
+#### Time series transformations
+
+Any column may have the following suffixes appended to indicate transformations
+applied to the original time series data:
+
+| Transformation | Description                                                                 |
+| -------------- | --------------------------------------------------------------------------- |
+| `_shift_back`  | The time series has been lagged by one TR. `x_shift_back[i] = x[i-1]`       |
+| `_dt`          | The discrete first derivative of the time series. `x_dt[i] = x[i+1] - x[i]` |
+| `_sq`          | The square of the time series                                               |
+| `_var_norm`    | The time series has been variance normalized                                |
+| `_centered`    | The time series has had its mean subtracted                                 |
+
+For example, `rot_z_shift_back_sq` means the square of the lagged version of the
+Z rotation (see Motion-related regressors).
+
+### ROI-based time series extraction
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        func/
+            <source_keywords>_[atlas-<atlas_label>_][desc-<label>_]timeseries.<tsv|nii.gz>
+            <source_keywords>_[atlas-<atlas_label>_][desc-<label>_]timeseries.json
+```
+
+for example:
+
+```Text
+sub-001/
+    func/
+        sub-001_task-rest_run-1_atlas-AAL_timeseries.tsv
+        sub-001_task-rest_run-1_atlas-AAL_timeseries.json
+        sub-001_task-rest_run-1_desc-anaticor_timeseries.nii.gz
+        sub-001_task-rest_run-1_desc-anaticor_timeseries.json
+```
+
+Time series will generally be stored as tables, with a row of column headers
+indicating the name of the time series. In the case where every voxel has a time
+series (i.e., voxel-wise regressors, as in ANATICOR), then the time series
+should be saved as a NIfTI file.
+
+#### Column metadata special fields
+
+Atlas (optional) - A label indicating an atlas that defines a region or set of
+regions in the volume. An atlas may be three- or four-dimensional, which affects
+the interpretation of the roi index.
+
+ROI (optional) - For 3D atlases, the ROI label should be numeric, corresponding
+to the value of the voxels in the ROI. For 4D atlases, the ROI label should be
+numeric, corresponding to the volume index containing the ROI mask. The
+following special labels correspond to common ROIs that may be defined by many
+atlases or segmentation algorithms:
+
+| ROI Value      | Description                                                                            |
+| -------------- | -------------------------------------------------------------------------------------- |
+| WhiteMatter    | Signal derived from white matter ROI.                                                  |
+| CSF            | Signal derived from cerebro-spinal fluid ROI.                                          |
+| Background     | Signal derived from background (out of brain) ROI.                                     |
+| GreyMatter     | Signal derived from grey matter ROI.                                                   |
+| Ventricles     | Signal derived from ventricles ROI.                                                    |
+| CircleOfWillis | Signal derived from circle of Willis ROI.                                              |
+| GlobalSignal   | Vector of mean values within the brain mask. Can be used for Global Signal Regression. |
+
+#### Column names
+
+Column names are unique alphanumeric values that are defined in a relevant JSON
+sidecar file. A naming convention might be to concatenate the atlas, ROI index,
+summarization method (defined below) and transformations (see Time series
+transformations, above) using snake case. For example,
+`harvard_oxford_cortical_4_PC` could indicate ROI 4 of the Harvard-Oxford
+cortical atlas, summarized by taking the first principal component.
+
+#### Summarization methods
+
+To indicate the summarization method applied to construct a single time series
+for an ROI, the following column suffixes are defined:
+
+| Column suffix | Description of the transformation                                                                                                                       |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `_mean`       | The mean of voxel time series                                                                                                                           |
+| `_median`     | The median of voxel time series                                                                                                                         |
+| `_pc[_<x>]`   | The ith eigenvariate from principal component analysis, where `x` is 0 indexed. If `x` is not specified, the first component is implied (i.e., `pc_0`). |
+| `_spat_reg`   | Spatial regression                                                                                                                                      |
+
+Example:
+
+```Text
+sub-001/
+    func/
+        sub-001_task-rest_run-1_timeseries.tsv
+```
+
+```Text
+white_matter_mean global_signal_mean ventricles_mean
+12                98                 11
+11                34                 53
+54                34                 34
+```
+
+```Text
+sub-001/
+    func/
+        sub-001_task-rest_run-1_timeseries.json
+```
+
+```JSON
+{
+    "white_matter_mean": {
+        "ROI": "WhiteMatter"
+    },
+    "global_signal_mean": {
+        "ROI": "GlobalSignal"
+    },
+    "ventricles_mean": {
+        "ROI": "Ventricles"
+    }
+}
+```
+
+### Motion-related regressors
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+    func/
+        <source_keywords>_[desc-<label>_]motion.tsv
+        <source_keywords>_[desc-<label>_]motion.json
+```
+
+#### Column names
+
+The six basic motion parameters derived from motion correction have the
+following names and units:
+
+| Column name                     | Units   | Description            |
+| ------------------------------- | ------- | ---------------------- |
+| `trans_x`, `trans_y`, `trans_z` | mm      | Translation parameters |
+| `rot_x`, `rot_y`, `rot_z`       | radians | Rotation parameters    |
+
+Transformations (see Transformations) of motion parameters may be included in
+the same file. For example, rot_z_shift_back_sq means square of the lagged
+version of Z rotation.
+
+The following columns indicate summarized motion, as defined in the
+corresponding references:
+
+| Column name              | Units | Description                                                         |
+| ------------------------ | ----- | ------------------------------------------------------------------- |
+| `framewise_displacement` | mm    | Framewise displacement (Power, et al., 2012)                        |
+| `rmsd`                   | mm    | Root mean square deviation (Jenkinson, 1999)                        |
+| `rms`                    | mm    | Root mean square of translation parameters (Van Dijk, et al., 2012) |
+
+### Temporal outlier masks
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        func/
+	        <source_keywords>_[desc-<label>_]outliers.tsv
+            <source_keywords>_[desc-<label>_]outliers.json
+```
+
+Outlier masks are columns of zeros (0), with ones (1) indicating volumes that
+have been identified as outliers by some method.
+
+#### Column names
+
+Column names for outliers correspond to the type of outlier or method for
+identifying the outlier. Column names should take the form `method[XX]`, where
+`XX` is an optional index.
+
+For example, if a BOLD series included two initial dummy scans,
+`non_steady_state` may be a column with a 1 for the first two volumes, or
+`non_steady_state_00` and `non_steady_state_01` may be columns with a 1 in the
+first and second position, respectively.
+
+The following methods are defined as reserved words:
+
+| Column name            | Description                                              |
+| ---------------------- | -------------------------------------------------------- |
+| `non_steady_state_<x>` | Initial non-steady-state volumes. One column per volume. |
+
+### Other time series and regressors
+
+Time series and regressors that are not otherwise specified should be placed in
+a regressors.tsv file (see General time series and regressors).
+
+#### Column names
+
+The following regressors are defined as reserved words:
+
+| Column name    | Description                                           |
+| -------------- | ----------------------------------------------------- |
+| `dvars`        | Change in variance (Brett, 2006, Power, et al., 2012) |
+| `std_dvars`    | Standardized DVARS (Nichols, 2013)                    |
+| `cosine_<X>`   | Discrete cosine basis vectors                         |
+| `legendre_<X>` | Legendre polynomial basis vectors                     |
+
+### Spatiotemporal decompositions
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        func/
+            <source_keywords>_[desc-<label>_]<mixing|components>.tsv
+            <source_keywords>_[desc-<label>_]<mixing|components>.nii.gz
+            <source_keywords>_[desc-<label>_]decomposition.json
+```
+
+for example:
+
+```Text
+sub-001/
+    func/
+        sub-001_task-rest_run-1_desc-MELODIC_components.nii.gz
+        sub-001_task-rest_run-1_desc-MELODIC_mixing.tsv
+        sub-001_task-rest_run-1_desc-MELODIC_decomposition.json
+```
+
+```Text
+sub-001/
+    func/
+        sub-001_task-rest_run-1_desc-tICA_mixing.nii.gz
+        sub-001_task-rest_run-1_desc-tICA_components.tsv
+        sub-001_task-rest_run-1_desc-tICA_decomposition.json
+```
+
+Spatiotemporal decompositions produce either spatial or temporal components,
+along with conjugate mixing matrices that can be represented as time series and
+spatial maps, respectively. The combination of suffix and extension indicates
+which class of algorithm produced the outputs.
+
+Mixing matrices may be omitted for algorithms that are temporal decompositions
+with no spatial component, such as CompCor variants.
+
+Spatiotemporal decomposition files MUST be accompanied by a data dictionary in
+JSON format, consistent with Raw-BIDS section 4.2, which describes metadata for
+each column name. In addition to column names, the following MANDATORY field is
+added:
+
+| Key name | Description                                           |
+| -------- | ----------------------------------------------------- |
+| Method   | REQUIRED. Algorithm name and (if applicable) version. |
+
+#### Column names
+
+Column names in spatiotemporal decompositions take the form of
+`<decomposition>_<index>`, where `<decomposition>` is the name of the
+decomposition algorithm, and `<index>` is a numeric identifier. Indices SHOULD
+start at 0. If there is a natural ordering, indices should reflect that
+ordering. For example, the aCompCor component which explains the most variance
+should be named `a_comp_cor_00`.
+
+The following reserved words indicate common algorithms:
+
+| Column name              | Description                                                                                                                                                                                                |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `[a|t|w|c]_comp_cor_<x>` | CompCor (Behzadi, et al., 2007) calculated with voxels chosen based on: `a`: anatomically derived ROIs (white matter and CSF), `t`: temporal variance, `w`: white matter voxels only, `c`: CSF voxels only |
+| `melodic_<x>`            | Columns from the mixing matrix in FSL MELODIC                                                                                                                                                              |
diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
new file mode 100644
index 0000000000..badea94598
--- /dev/null
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -0,0 +1,381 @@
+# Diffusion derivatives
+
+## Preprocessed diffusion weighted images
+
+Multiple different versions of preprocessing can be stored for the same source
+data. To distinguish them from each other, the `desc` fileneame keyword can be
+used. Details of preprocessing performed for each variation of the processing
+should be included in the pipeline documentation.
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        dwi/
+          <source_keywords>[_referencemap-<referencemap>][_desc-<label>]_dwi.nii[.gz]
+          <source_keywords>[_referencemap-<referencemap>][_desc-<label>]_dwi.bvals
+          <source_keywords>[_referencemap-<referencemap>][_desc-<label>]_dwi.bvecs
+```
+
+The JSON sidecar file is REQUIRED (due to the REQUIRED `SkullStripped` field -
+see [Common Data Types](02-common-data-types.md)), and if present can be used to
+store information about what preprocessing options were used (for example
+whether motion compensation was performed, non-linear corrections were applied,
+whether Eddy current correction was performed, denoising, or intensity
+normalization were applied, etc).
+
+Additional reserved JSON metadata fields:
+
+| **Key name**           | **Description**                                                                                                          |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| MotionCompensation     | OPTONAL. Boolean. Motion compensation                                                                                    |
+| EddyCurrentCorrection  | OPTONAL. Boolean. Eddy currents corrections                                                                              |
+| Denoising              | OPTIONAL. String. Denoising method                                                                                       |
+| IntensityNormalization | OPTIONAL. Boolean. Intensity normalization                                                                               |
+| NonLinearCorrections   | OPTIONAL. Boolean. non-linear corrections                                                                                |
+| GradientNonLinearities | OPTIONAL. Correction for non-linear gradients. String with allowed values: `geometry`, `gradients`, `geometry&gradients` |
+
+## Diffusion Models (and input parameters)
+
+Diffusion MRI can be modeled using various paradigms to extract a more easily
+understandable representation of the diffusion process and the underlying
+structure. To do so, parameters might be needed to control how the signal is fit
+to the model. Those parameters are called **input parameters** in the following.
+Once the model is fit, the resulting representation can be saved using a number
+of values per voxel. Those values will be called **output** or **estimated
+parameters** in the following.
+
+**Estimated parameters** are saved as NIFTI files (see section Models for the
+expected content of each model), and **input parameters** are saved in the
+sidecar JSON file.
+
+The following is a general example of naming convention:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        dwi/
+            <source_keywords>[_referencemap-<referencemap>][_desc-<label>]_model-<label>_diffmodel.nii[.gz]
+            <source_keywords>[_referencemap-<referencemap>][_desc-<label>]_model-<label>_diffmodel.json
+```
+
+The following models are codified and should be used in the `model-<label>`
+field. If a new model is used, common sense should be used to derive a name
+following the BIDS standard, and should ideally be integrated in a follow-up
+version of the specification.
+
+| Model label | Citation                                                                                       | Description                                                                                                                                                                                                                                                                                                                                       |
+| ----------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DTI`       | Diffusion tensor imaging (Basser et al. 1994)                                                  | 4D image with Dxx, Dxy, Dxz, Dyy, Dyz, Dzz; the 6 unique parameters of the diffusion tensor.                                                                                                                                                                                                                                                      |
+| `DKI`       | Diffusion kurtosis imaging (Jensen et al., 2005)                                               | 4D image with Dxx, Dxy, Dxz, Dyy, Dyz, Dzz, Wxxxx, Wyyy, Wzzzz, Wxxxy, Wxxxz, Wxyyy, Wyyyz, Wxzzz, Wyzzz, Wxxyy, Wxxzz, Wyyzz, Wxxyz, Wxyyz, Wxyzz; Where D is the diffusion tensor and W is the kurtosis tensor.                                                                                                                                 |
+| `WMTI`      | White matter tract integrity (Fieremans et al., 2011)                                          | 4D image with Dxx, Dxy, Dxz, Dyy, Dyz, Dzz, Wxxxx, Wyyy, Wzzzz, Wxxxy, Wxxxz, Wxyyy, Wyyyz, Wxzzz, Wyzzz, Wxxyy, Wxxzz, Wyyzz, Wxxyz, Wxyyz, Wxyzz, Dhxx, Dhxy, Dhxz, Dhyy, Dhyz, Dhzz, Drxx, Drxy, Drxz, Dryy, Dryz, Drzz, AWF; where D is the diffusion tensor, W is the kurtosis tensor, AWF is the additional axonal water fraction parameter |
+| `CSD`       | Constrained Spherical Deconvolution (Tournier et al. 2007; Descoteaux et al. 2009)             | 4D image with SHM coefficients (size and ordering, depends on the model order and basis set, specified in the sidecar)                                                                                                                                                                                                                            |
+| `NODDI`     | Neurite Orientation Dispersion and Density Imaging (Zhang et al. 2012, Daducci et al., 2015)   | 4D image with ICVF, OD, ISOVF; where ICVF is the “intracellular volume fraction” (also known as NDI), OD is the “orientation dispersion” (the variance of the Bingham; also known as ODI) and ISOVF is the isotropic component volume fraction (also known as IVF).                                                                               |
+| `DSI`       | Diffusion Spectrum Imaging (Wedeen et al. 2008; Paquette et al 2017)                           | DSI is generally used mostly to compute the diffusion ODF (Orientation Distribution Function). No parameters are generally returned, but an ODF can be saved as a map.                                                                                                                                                                            |
+| `CSA`       | Constant solid angle (Aganj et al. 2010)                                                       | 4D image with SHM coefficients (size and ordering, depends on the model order and basis set, specified in the side-car)                                                                                                                                                                                                                           |
+| `SHORE`     | Simple Harmonic Oscillator based Reconstruction and Estimation. (Ozarslan et al. 2008)         | 4D image with basis coefficients depending on choice of basis.                                                                                                                                                                                                                                                                                    |
+| `MAPMRI`    | Mean Apparent Propagator MRI. (Ozarslan, 2013)                                                 | 4D image with basis coefficients depending on choice of basis.                                                                                                                                                                                                                                                                                    |
+| `FORECAST`  | Fiber ORientation Estimated using Continuous Axially Symmetric Tensors. (Zuchelli et al. 2017) | 4D image with SHM coefficients.                                                                                                                                                                                                                                                                                                                   |
+| `fwDTI`     | Free water DTI (Hoy et al. 2014)                                                               | 4D image with D_c_xx, D_c_xy, D_c_xz, D_c_yy, D_c_yz, D_c_zz, FWF; where D_c is the fw-corrected diffusion tensor in this voxel.                                                                                                                                                                                                                  |
+| `BedpostX`  | Ball-and-Stick model (Behrens et al. 2007; Jabdbi et al, MRM 2012)                             | 5D image (xyz, m, n) for m parameters and n MCMC samples (n=1 implies best-fit parameters). Parameters are f_i, th_i, ph_i (volume fraction, polar angle, azimuthal angle) for up to 3 fibres, d, d_std (for “multiexponential” model)                                                                                                            |
+
+The JSON sidecar contains the following key/value pairs common for all models:
+
+| **Key name** | **Description**                                                                                                                      |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+| Model        | Model label - see table above                                                                                                        |
+| Shells       | OPTIONAL. Shells that were utilized to fit the model, as a list of b-values. If the key is not present, all shells were used.        |
+| Gradients    | OPTIONAL. Subset of gradients utilized to fit the model, as a list of three-elements lists. If not present, all gradients were used. | ModelDescription | OPTIONAL. Extended information to describe the model. |
+| ModelURL     | OPTIONAL. URL to the implementation of the specific model utilized.                                                                  |
+| Parameters   | OPTIONAL. A dictionary of model parameters (see below for keys specific to each model)                                               |
+
+-   Model:
+
+    -   `DTI` :
+
+        - `FitMethod` : {`WLS`,`OLS`,`NLLS`,`RESTORE`}
+        - `RESTORE` : sigma
+
+    -   `DKI` and `WMTI`:
+
+        - `FitMethod` : {`WLS`,`OLS`,`NLLS`}
+
+    -   `CSD`:
+
+        - `SphericalHarmonicOrder` : value
+        - `ResponseFunctionOrder` : value
+        - `ResponseFunction` : \[1:response_function_order_value,b0mean\]
+        - `Basis` : {`MRtrix 0.2`,`MRtrix3`,`DESCOTEAUX`}
+
+    -   `CSDM`:
+
+        -   `SphericalHarmonicOrder` : \[values (1 x number of tissues)\]
+
+        -   `ResponseFunctionOrder` : \[values (1 x number of tissues)\]
+
+        -   `ResponseFunction` : \[values (1 x number of
+            tissues)\]\[1:response_function_order_value x number of tissues,
+            b0mean x number of tissues\]
+
+        -   `Basis` : {`MRtrix 0.2`,`MRtrix3`,`DESCOTEAUX`}
+
+    -   `NODDI`:
+
+        - `DPar` : value
+        - `DIso` : value
+        - `Lambda1` : value
+        - `Lambda2` : value
+
+    -   `DSI` :
+
+        - `GridSize` : value
+        - `RStart` : value
+        - `RStep` : value
+        - `REnd` : value
+        - `FilterWidth` : value
+
+    -   `CSA` :
+
+        - `SphericalHarmonicOrder` : value
+        - `Smoothing` : value
+        - `Basis` : value
+
+    -   `SHORE` :
+
+        - `RadialOrder` : value
+        - `Zeta` : value
+        - `LambdaN` : value
+        - `LambdaL` : value
+        - `Tau` : value
+        - `ConstrainE0` : value
+        - `PositiveConstraint` : value
+        - `PosGrid` : value
+        - `PosRadius` : value
+
+    -   `MAPMRI` :
+
+        - `RadialOrder` : value
+        - `LaplacianRegularization` : bool
+        - `LaplacianWeighting` : value
+        - `PositivityConstraint` : bool
+        - `Tau` : value
+        - `ConstrainE0` : value
+        - `PositiveConstraint` : value
+        - `PosGrid` : value
+        - `PosRadius` : value
+        - `AnisotropicScaling` : bool
+        - `EigenvalueThreshold` : value
+        - `PosGrid` : value
+        - `BvalThreshold` : value
+        - `DTIScaleEstimation` : bool
+        - `StaticDiffusivity` : value
+
+    -   `FORECAST` :
+
+        - `Sphere` : value
+        - `DecAlg` : value
+        - `LambdaLb` : value
+        - `SphericalHarmonicsOrder` : value
+
+    -   `fwDTI` :
+
+        - `FitMethod` : {"WLS","NLLS"}
+
+    -   `BEDPOSTX` :
+
+        -   `NFibers` : value
+
+        -   `Fudge` : value
+
+        -   `BurnIn` : value
+
+        -   `NJumps` : value
+
+        -   `SampleEvery` : value
+
+        -   `Model` : {`monoexponential`, `multiexponentialStick`,
+            `multiexponentialZeppelin`}
+
+Examples:
+
+A 4D volume with floating point numbers
+
+```Text
+my_diffusion_pipeline/
+    sub-01/
+        dwi/
+            sub-01_referenecemap-T1w_desc-WLS_model-DTI_diffmodel.nii.gz
+```
+
+```Text
+my_diffusion_pipeline/
+    sub-01/
+        dwi/
+            sub-01_referenecemap-T1w_desc-WLS_model-DTI_diffmodel.json
+```
+
+```JSON
+{
+    "Model": "DTI",
+    "Parameters": {
+        "FitMethod": "WLS"
+        }
+}
+```
+
+## Model-derived maps (output parameters)
+
+Models output maps of estimated parameters. Commonly one parameter is estimated
+per voxel, we call these maps of parameters. Two types of maps are described in
+this specification: scalar and vector maps. Scalar maps are saved as 3D
+.nii/nii.gz files. Vector maps are saved as 4D .nii/nii.gz files. Below the
+specification for the naming of the files and a the list of currently accepted
+fields for the maps.
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        dwi/
+            <source_keywords>[_referencemap-<referencemap>space-<space>][_model-<label>][_desc-<label>]_<map_label>.nii[.gz]
+```
+
+### Scalar maps
+
+These maps are saved 3D NIfTI files (x,y,z, 1).
+
+| `<map_label>` value | Description                                                                                                                 | Possible Model sources                                                                                                       | Unit or scale                                                                                                                                                                        |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| FA                  | Fractional Anisotropy                                                                                                       | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   | Unitless \[0-1\]                                                                                                                                                                     |
+| MD                  | Mean diffusivity (also called apparent diffusion coefficient, ADC)                                                          | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   | microns^2/ms (for example, for free water in body temperature, this should be 3)                                                                                                     |
+| AD                  | Axial Diffusivity (also called parallel diffusivity)                                                                        | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   | microns^2m/s (for example, for free water in body temperature, this should be 3)                                                                                                     |
+| RD                  | Radial Diffusivity (also called perpendicular diffusivity)                                                                  | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   | microns^2/ms (for example, for free water in body temperature, this should be 3)                                                                                                     |
+| MODE                | Mode of the tensor                                                                                                          | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   |                                                                                                                                                                                      |
+| LINEARITY           | Tensor linearity (Westin 1997)                                                                                              | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   |                                                                                                                                                                                      |
+| PLANARITY           | Tensor planarity (Westin 1997)                                                                                              | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   |                                                                                                                                                                                      |
+| SPHERICITY          | Tensor sphericity (Westin 1997)                                                                                             | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   |                                                                                                                                                                                      |
+| MK                  | Mean kurtosis                                                                                                               | DKI, WMTI                                                                                                                    | Unitless                                                                                                                                                                             |
+| RK                  | Radial kurtosis                                                                                                             | DKI, WMTI                                                                                                                    | Unitless                                                                                                                                                                             |
+| AK                  | Axial kurtosis                                                                                                              | DKI, WMTI                                                                                                                    | Unitless                                                                                                                                                                             |
+| ICVF                | Intracellular volume fraction. This can be calculated from different models, so can have slightly different interpretation. | WMTI (AWF), NODDI                                                                                                            | Proportion \[0-1\]                                                                                                                                                                   |
+| DECFA               | Directionally-encoded color (DEC) FA                                                                                        | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   | 3 8-bit floating point numbers that encode x,y,z of the principal diffusion direction in the voxel. The norm of the vector is the FA in the voxel.Need to set the NiFTI dtype to RGB |
+| ODI                 | Orientation dispersion index                                                                                                | NODDI                                                                                                                        | Normalised to \[0,1\]                                                                                                                                                                |
+| ISOVF               | Isotropic volume fraction                                                                                                   | NODDI                                                                                                                        | microns^2/ms (for example, for free water in body temperature, this should be 3)                                                                                                     |
+| TDI                 | Track Density Imaging                                                                                                       |                                                                                                                              | Streamline visitation counts?                                                                                                                                                        |
+| GFA                 | Generalized Fractional Anisotropy                                                                                           | CSA, CSD, SHORE, MAPMRI, Forecast (or any model that can be represented as an ODF)                                           | Proportion \[0 - 1\]                                                                                                                                                                 |
+| AFD                 | Apparent Fiber Density                                                                                                      |                                                                                                                              | positive, unitless                                                                                                                                                                   |
+| INDEX               | Scalar maps from bedpostx                                                                                                   | FSUM (sum of partial volume fractions of the sticks)F_i (volume fraction of stick i)D (diffusivity)DSTD (std of diffusivity) | FSUM \[0 - 1\]F_i \[0 - 1\]D and DSTD microns^2/ms (for example, for free water in body temperature, this should be 3)                                                               |
+| RTPP                | Return to the plane probability                                                                                             | MAPMRI                                                                                                                       | Probability \[0 - 1\]                                                                                                                                                                |
+| RTAP                | Return to axis probability                                                                                                  | MAPMRI                                                                                                                       | Probability \[0 - 1\]                                                                                                                                                                |
+
+### Vector-valued maps
+
+These maps are saved 4D NIfTI files (x,y,z, n\*(xyz)).
+
+| `<map_label>` values | Description                                                                                                                                                                                                                                                                                                          |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| fixel                | Fixel (Fiber bundle element) images. Different voxels can have different numbers of fixels, and therefore a sparse file format is required. This is not specific to Fibre Density derived via CSD. Several diffusion models provide fixel-specific measures (e.g. Ball and stick, CHARMED, CuspMFM, Myelin content). |
+| ODF                  | Orientation distribution function                                                                                                                                                                                                                                                                                    |
+| PDF                  | Diffusion propagator                                                                                                                                                                                                                                                                                                 |
+| FOD                  | Fiber orientation distribution (Sometimes known as fODF)                                                                                                                                                                                                                                                             |
+| EVECS                | Eigenvectors of a model that has eigenvectors (such as DTI)                                                                                                                                                                                                                                                          |
+| PEAKS                | Directions of ODF maxima on the sphere.                                                                                                                                                                                                                                                                              |
+
+## Describing tractography
+
+Tractography normally generates one of two primary file types: tractograms or
+NIfTi files containing maps. Tractograms are files containing a collection of
+streamlines, which are objects describing the path of idealized brain fiber
+fascicles (ensembles of neural fibers that travel together). Tractography maps
+contain visitation counts (i.e. 3D spatial histograms) of a collection of
+streamlines but do not contain the actual streamline objects. The main type of
+map represent the diffusion path probability, or how likely it is that diffusion
+between pairs of brain regions. Two tractogram file formats are supported,
+tractography maps should be saved as NIfTIs.
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        dwi/
+            <source_keywords>[_referencemap-<referencemap>][_desc-<label>][_subset-<label>]_tractography.[trk|tck|nii[.gz]]
+```
+
+### Filename keys
+
+`desc` (optional) – A way to refer to a specific instance of the tractography
+process. The combination of tractography methods and parameters that were used
+to create this tractography result should be described in the associated JSON
+file.
+
+`subset` (optional) – A label descriptor for the the subset of streamlines
+included in this file; if not specified, a whole brain tractography is assumed
+(a tractogram). Example of subsets can be `short` if only short streamlines were
+kept, or `subsampled50` if only 50% of the streamlines were kept.
+
+### File formats
+
+- [.trk - Diffusion Toolkit (+TrackVis)](http://www.trackvis.org/docs/?subsect=fileformatEmbeds)
+- [.tck - MRTrix](http://mrtrix.readthedocs.io/en/latest/getting_started/image_data.html#tracks-file-format-tckAssumes)
+
+### JSON Metadata
+
+We have two main classes of tractography algorithms: Global or Local
+tractography, each with various supported algorithms.
+
+| Class  | Algorithms | Reference                                                                                                                                                       |
+| ------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| LOCAL  | PROB       | Sherbondy, A.J., et al. (2008).Tournier J.D.et al. (2012).Behrens et al. (2007)                                                                                 |
+| LOCAL  | DET        | Conturo, T. et al. (1999)Mori, S. et al. (1999)                                                                                                                 |
+| LOCAL  | EUDX       | Garyfallidis et al. (2010)Mori, S. et al. (1999)                                                                                                                |
+| LOCAL  | FACT       | Jiang, H. et al. (2005)                                                                                                                                         |
+| LOCAL  | STT        | Lazar, M., et al. (2003)                                                                                                                                        |
+| GLOBAL | UKF        | Malcolm J-G., et al. (2009)                                                                                                                                     |
+| GLOBAL | SpinGlass  | Fillard P., et al. (2009)                                                                                                                                       |
+| GLOBAL | ENS        | Takemura et al. (2016)                                                                                                                                          |
+| GLOBAL | Other      | Mangin, J.F. et al. (2013).Aganj, I. et al. (2011).Neher, P.F. et al. (2012).Jbabdi, S., et al. (2007).Sherbondy, A.J., et al. (2009).Reisert, M. et al. (2011) |
+
+The JSON sidecar contains the following key/value pairs:
+
+| **Key name**       | **Description**                                                                                                  |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| TractographyClass  | REQUIRED. Allowed values: `local`, `global"`                                                                     |
+| TractographyMethod | REQUIRED. Allowed values: `probabilistic`,`deterministic`,`eudx`,`fact`,`stt`,`other`, `UKF`,`SpinGlass`,`other` |
+
+RECOMMENDED when TractographyMethod is `probabilistic`, `deterministic`, `eudx`,
+`fact`, `stt`, `other`:
+
+| **Key name**             | **Description**                                                 |
+| ------------------------ | --------------------------------------------------------------- |
+| StepSizeUnits            | "mm","norm"                                                     |
+| StepSize                 | value                                                           |
+| AngleCurvature           | value                                                           |
+| SeedingMethod            | "seedsPerVoxel", "globalSeedNumber", "totalStreamlinesNumber"   |
+| SeedingNumberMethod      | integer for the number of seeds                                 |
+| TerminationCriterion     | "leaveMask", "reachingTissueType”                               |
+| TerminationCriterionTest | "binary","ACT","CMC"                                            |
+
+Example:
+
+```Text
+sub01-dwi_desc-DET1_tractography.trk
+sub01-dwi_desc-DET1_tractography.json
+```
+
+```JSON
+{
+    "TractographyClass": "local",
+    "TractographyMethod": "deterministic",
+    "StepSize": 0.5
+}
+```
+
+```Text
+sub01-dwi_subset-AFLeft_tractography.trk
+sub01-dwi_subset-short_fibers_tractography.json
+```
+
+```JSON
+{
+    "TractographyClass": "global",
+ 	"TractographyMethod": "UKF",
+    "Description": "UKF tracking where only short fibers were kept."
+}
+```
diff --git a/src/99-appendices/08-coordinate-systems.md b/src/99-appendices/08-coordinate-systems.md
index 3ee9e60937..a54bf6f182 100644
--- a/src/99-appendices/08-coordinate-systems.md
+++ b/src/99-appendices/08-coordinate-systems.md
@@ -1,5 +1,49 @@
 # Appendix VIII: preferred names of Coordinate systems
 
+## Definitions
+
+### Coordinate System
+
+A coordinate system specifies the information necessary to interpret the
+coordinates associated with the data. A coordinate system can be described by
+its topology (cartesian, spherical, polar, etc.,.), dimensionality, and units of
+measurement along each dimension. Every device that makes spatial measurements
+or has sensors described in a space has a coordinate system (e.g., an MR
+scanner, an MEG scanner, an EEG cap, Polhemus digitizer). The data output by
+most of these devices describe the number of dimensions, the units along each
+dimension, and in some cases the details of origin (for example, time).
+
+### Space, atlas and map
+
+A space|atlas|map is embedded in a coordinate system to ascribe meaning to the
+coordinates. For instance, Scanner, Talairach88, MNI, FS are different
+coordinate systems, while the Talairach atlas, MNI152, and fsaverage ascribe
+meaning to the coordinates in terms of brain anatomy. As an example to
+distinguish coordinate systems and spaces/atlas/maps, a 4D fMRI timeseries
+acquired without motion correction has individual time points all in the same
+coordinate system, but the atlas/map is different (due to motion) in different
+time points.
+
+### Landmarks
+
+Landmarks are properties of the object being measured and can exist in any
+coordinate system in which the object is placed/measured. They can be relevant
+points of the imaged object's structure (i.e. anatomical landmarks) such as the
+anterior commissure in a brain. They can also be devices that generate a
+localizable signal that are placed in the intended position before scanning
+(i.e. markers). Positions of landmarks are identified via manual or automated
+algorithms that detect these landmarks in (e.g., MR) or from (e.g., MEG) the
+acquired data or via explicit encoding of position (e.g., EEG sensors,
+headshape/coil digitization).
+
+These landmarks can be coordinates in a file or voxel/pixel intensity relations
+in image files.This information (coordinates or intensity relations)
+representing landmarks of the same or similar object (e.g., a template brain) in
+different coordinate systems can be used to transform the object between
+coordinate systems.
+
+## Introduction
+
 To interpret a coordinate (x, y, z), it is required that you know relative to
 which origin the coordinates are expressed, you have to know the interpretation
 of the three axes, and you have to know the units in which the numbers are
@@ -54,7 +98,7 @@ Restricted keywords for the XXXCoordinateSystem field in the
 -   ChietiItab: RAS orientation and the origin between the ears
 
 -   Other: Use this for other coordinate systems and specify further details in
-  the `XXXCoordinateSystemDescription` field
+    the `XXXCoordinateSystemDescription` field
 
 Note that the short descriptions above do not capture all details, there are
 detailed descriptions of these coordinate systems on the FieldTrip toolbox web
@@ -92,9 +136,10 @@ specified explicitly in the sidecar file in the `XXCoordinateSystemUnits` field,
 the units are assumed to be mm.
 
 | Coordinate System                                   | Description                                                                                                                                                                                                                                                                                                                                                      |
-| ---------------------------------------------------   | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------   |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FS305                                               | FreeSurfer variant of the MNI305 space                                                                                                                                                                                                                                                                                                                           |
 | MNI152Lin                                           | Also known as ICBM (version with linear coregistration) [http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152Lin](http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152Lin)                                                                                                                                                                                       |
-| MNI152NLin6\[Sym&#124;Asym\]                        | Also known as ICBM 6th generation (non-linear coregistration). Used by SPM99 -   SPM8 and FSL (MNI152NLin6Sym). [http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin6](http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin6)                                                                                                                           |
+| MNI152NLin6\[Sym&#124;Asym\]                        | Also known as ICBM 6th generation (non-linear coregistration). Used by SPM99 - SPM8 and FSL (MNI152NLin6Sym). [http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin6](http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin6)                                                                                                                             |
 | MNI152NLin2009\[a-c\]\[Sym&#124;Asym\]              | Also known as ICBM (non-linear coregistration with 40 iterations, released in 2009). It comes in either three different flavours each in symmetric or asymmetric version. [http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin2009](http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin2009)                                                           |
 | MNIColin27                                          | Average of 27 T1 scans of a single subject [http://www.bic.mni.mcgill.ca/ServicesAtlases/Colin27Highres](http://www.bic.mni.mcgill.ca/ServicesAtlases/Colin27Highres)                                                                                                                                                                                            |
 | MNI305                                              | Also known as avg305.                                                                                                                                                                                                                                                                                                                                            |
@@ -105,7 +150,9 @@ the units are assumed to be mm.
 | ICBM452AirSpace                                     | Reference space defined by the "average of 452 T1-weighted MRIs of normal young adult brains" with "linear transforms of the subjects into the atlas space using a 12-parameter affine transformation" [http://www.loni.usc.edu/ICBM/Downloads/Downloads_452T1.shtml](http://www.loni.usc.edu/ICBM/Downloads/Downloads_452T1.shtml)                              |
 | ICBM452Warp5Space                                   | Reference space defined by the "average of 452 T1-weighted MRIs of normal young adult brains" "based on a 5th order polynomial transformation into the atlas space" [http://www.loni.usc.edu/ICBM/Downloads/Downloads_452T1.shtml](http://www.loni.usc.edu/ICBM/Downloads/Downloads_452T1.shtml)                                                                 |
 | IXI549Space                                         | Reference space defined by the average of the "549 (...) subjects from the IXI dataset" linearly transformed to ICBM MNI 452.Used by SPM12. [http://www.brain-development.org/](http://www.brain-development.org/)                                                                                                                                               |
+| fsnative                                            | Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image                                                                                                                                                                                                                                                                         |
 | fsaverage\[3&#124;4&#124;5&#124;6&#124;sym\]        | Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image, and registered to an fsaverage template                                                                                                                                                                                                                                |
-| UNCInfant\[0&#124;1&#124;2\]V\[21&#124;22&#124;23\] | Infant Brain Atlases from Neonates to 1-   and 2-year-olds. [https://www.nitrc.org/projects/pediatricatlas](https://www.nitrc.org/projects/pediatricatlas)                                                                                                                                                                                                       |
+| fsLR[164k                                           | 32k]                                                                                                                                                                                                                                                                                                                                                             | Images were sampled to the 164k or 32k fsaverage_LR surface reconstructed from the T1w image (high resolution space of the HCPPipelines) |
+| UNCInfant\[0&#124;1&#124;2\]V\[21&#124;22&#124;23\] | Infant Brain Atlases from Neonates to 1- and 2-year-olds. [https://www.nitrc.org/projects/pediatricatlas](https://www.nitrc.org/projects/pediatricatlas)                                                                                                                                                                                                         |
 
 ---

From ed96fdac5f75d28107fda52a5ee07d1cd06e958e Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Sun, 16 Dec 2018 11:42:11 -0800
Subject: [PATCH 002/191] adding derivatives to the index

---
 mkdocs.yml | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/mkdocs.yml b/mkdocs.yml
index a6149e3786..cae49d3888 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -15,7 +15,13 @@ nav:
         - Task events: 04-modality-specific-files/03-task-events.md
         - Physiological and other continous recordings: 04-modality-specific-files/04-physiological-and-other-continous-recordings.md
         - Behavioral experiments (with no MRI): 04-modality-specific-files/05-behavioural-experiments.md
-      - Longitudinal and multi-site studies: 05-longitudinal-and-multi-site-studies.md
+      - Derivatives:
+        - Introduction: 05-derivatives/01-introduction.md
+        - Common data types: 05-derivatives/02-common-data-types.md
+        - Structural derivatives: 05-derivatives/03-structural-derivatives.md
+        - Functional derivatives: 05-derivatives/04-functional-derivatives.md
+        - Diffusion derivatives: 05-derivatives/05-diffusion-derivatives.md
+      - Longitudinal and multi-site studies: 06-longitudinal-and-multi-site-studies.md
       - Extending the BIDS specification: 06-extensions.md
       - Appendix:
         - Contributors: 99-appendices/01-contributors.md

From 9a15097f89b3d583af986adebcda5aa5df7381d9 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Sun, 16 Dec 2018 11:43:23 -0800
Subject: [PATCH 003/191] rename

---
 ...-site-studies.md => 07-longitudinal-and-multi-site-studies.md} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename src/{05-longitudinal-and-multi-site-studies.md => 07-longitudinal-and-multi-site-studies.md} (100%)

diff --git a/src/05-longitudinal-and-multi-site-studies.md b/src/07-longitudinal-and-multi-site-studies.md
similarity index 100%
rename from src/05-longitudinal-and-multi-site-studies.md
rename to src/07-longitudinal-and-multi-site-studies.md

From 2e6d5e7b15f5045716e74d16f6496e1c74e63cb6 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Sun, 16 Dec 2018 11:44:30 -0800
Subject: [PATCH 004/191] rename

---
 ...-site-studies.md => 06-longitudinal-and-multi-site-studies.md} | 0
 src/{06-extensions.md => 07-extensions.md}                        | 0
 2 files changed, 0 insertions(+), 0 deletions(-)
 rename src/{07-longitudinal-and-multi-site-studies.md => 06-longitudinal-and-multi-site-studies.md} (100%)
 rename src/{06-extensions.md => 07-extensions.md} (100%)

diff --git a/src/07-longitudinal-and-multi-site-studies.md b/src/06-longitudinal-and-multi-site-studies.md
similarity index 100%
rename from src/07-longitudinal-and-multi-site-studies.md
rename to src/06-longitudinal-and-multi-site-studies.md
diff --git a/src/06-extensions.md b/src/07-extensions.md
similarity index 100%
rename from src/06-extensions.md
rename to src/07-extensions.md

From 9557d9cbd365c065c237f2bdb747983cf8341289 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Sun, 16 Dec 2018 11:48:21 -0800
Subject: [PATCH 005/191] fix index

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

diff --git a/mkdocs.yml b/mkdocs.yml
index cae49d3888..ffb07c0438 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -22,7 +22,7 @@ nav:
         - Functional derivatives: 05-derivatives/04-functional-derivatives.md
         - Diffusion derivatives: 05-derivatives/05-diffusion-derivatives.md
       - Longitudinal and multi-site studies: 06-longitudinal-and-multi-site-studies.md
-      - Extending the BIDS specification: 06-extensions.md
+      - Extending the BIDS specification: 07-extensions.md
       - Appendix:
         - Contributors: 99-appendices/01-contributors.md
         - Licenses: 99-appendices/02-licenses.md

From 32d0b333e8d523b8951190a5baaddbd5eb14e092 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Sun, 16 Dec 2018 12:21:30 -0800
Subject: [PATCH 006/191] fixed links

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

diff --git a/src/05-derivatives/04-functional-derivatives.md b/src/05-derivatives/04-functional-derivatives.md
index 431d803d24..8e8e3c2f36 100644
--- a/src/05-derivatives/04-functional-derivatives.md
+++ b/src/05-derivatives/04-functional-derivatives.md
@@ -61,7 +61,7 @@ regressor, then the data should be stored in a 4D NIfTI file.
 
 Tabular regressor files MUST be accompanied by a data dictionary in JSON format,
 consistent with the format described in
-[Common princioples](../02common-principles.md).
+[Common princioples](../02-common-principles.md).
 
 Volumetric regressor files MAY be accompanied by a data dictionary in JSON
 format, with OPTIONAL `LongName`, `Description`, `Levels`, `Units`, and

From 99a1cccef757fa7672685dde292b664c89f983bb Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Sun, 16 Dec 2018 12:31:38 -0800
Subject: [PATCH 007/191] fixed links

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

diff --git a/src/01-introduction.md b/src/01-introduction.md
index fbf0e68cc4..4e64480069 100644
--- a/src/01-introduction.md
+++ b/src/01-introduction.md
@@ -48,7 +48,7 @@ The BIDS specification can be extended in a backwards compatible way and will
 evolve over time. This is accomplished through community-driven BIDS Extention
 Proposals (BEPs). For more information about the BEP process, and list of
 current BEP proposals, see
-[Extending the BIDS specification](06-extensions.md).
+[Extending the BIDS specification](07-extensions.md).
 
 ## Citing BIDS
 

From 567f32940adfb6df8d6cecfdb8ae6da598b67a9a Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Mon, 31 Dec 2018 15:24:48 -0800
Subject: [PATCH 008/191] template cleanup

---
 .../04-functional-derivatives.md              | 746 +++++++++---------
 1 file changed, 373 insertions(+), 373 deletions(-)

diff --git a/src/05-derivatives/04-functional-derivatives.md b/src/05-derivatives/04-functional-derivatives.md
index 8e8e3c2f36..663f2decab 100644
--- a/src/05-derivatives/04-functional-derivatives.md
+++ b/src/05-derivatives/04-functional-derivatives.md
@@ -1,373 +1,373 @@
-# Functional derivatives
-
-## Functional derivatives maps
-
-Template:
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        func/
-            <source_keywords>[_referencemap-<referencemap>space-<space>][_desc-<label>]_<suffix>.nii[.gz]
-            <source_keywords>[_referencemap-<referencemap>space-<space>][_desc-<label>]_<suffix>.json
-```
-
-for example:
-
-```Text
-pipeline1/
-    sub-001/
-        func/
-            sub-001_task-rest_run-1_space-MNI305_mean.nii.gz
-            sub-001_task-rest_run-1_space-MNI305_mean.json
-```
-
-The following table lists allowed suffixes and their corresponding measures:
-
-| `<suffix>`       | Measure                                                          |
-| ---------------- | ---------------------------------------------------------------- |
-| `mean`           | Mean across the temporal/4th dimension of the data               |
-| `std`            | Standard deviation across the temporal/4th dimension of the data |
-| `tsnr`           | Temporal SNR (i.e. mean / std)                                   |
-| `sfs`            | Signal fluctuation sensitivity                                   |
-| `alff`           | Amplitude low frequency fluctuations                             |
-| `falff`          | Fractional amplitude of low frequency fluctuations               |
-| `reho`           | Regional homogeneity (voxelwise only)                            |
-| `dcb`, `dcw`     | Voxelwise degree centrality binary and weighted                  |
-| `ecb`, `ecw`     | Voxelwise eigenvector centrality binary and weighted             |
-| `lfcdb`, `lfcdw` | Local functional connectivity density                            |
-| `vmhc`           | Voxel mirrored homotopic connectivity                            |
-
-The following metadata JSON fields are valid for derivative maps:
-
-| Key name       | Description                                                               | Required for suffix        |
-| -------------- | ------------------------------------------------------------------------- | -------------------------- |
-| BandpassFilter | String describing all relevant parameters of the applied bandpass filter. | `alff`, `falff`            |
-| Neighborhood   | String describing neighborhood for regional measures.                     | `reho`                     |
-| Threshold      | String describing threshold used for determining graph edges.             | `dcb`, `dcw`, `ecb`, `ecw` |
-| Method         | String describing method used to calculate measure.                       | `dcb`, `dcw`, `ecb`, `ecw` |
-
-## Time series and regressors
-
-For the purposes of this section, a time series or regressor is a numeric series
-of values corresponding to volumes in a BOLD series. Time series is specifically
-used to indicate an aggregate time series within an ROI, while regressor is used
-as a more general term indicating series that may be derived from other sources,
-such as head motion estimates or physiological recordings.
-
-Regressors will generally be stored as tables, with a row of column headers
-indicating the name of the regressor. In the case where every voxel has a
-regressor, then the data should be stored in a 4D NIfTI file.
-
-Tabular regressor files MUST be accompanied by a data dictionary in JSON format,
-consistent with the format described in
-[Common princioples](../02-common-principles.md).
-
-Volumetric regressor files MAY be accompanied by a data dictionary in JSON
-format, with OPTIONAL `LongName`, `Description`, `Levels`, `Units`, and
-`TermURL` fields.
-
-### General time series and regressors
-
-Template:
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        func/
-	        <source_keywords>_[desc-<label>_]regressors.tsv
-	        <source_keywords>_[desc-<label>_]regressors.json
-```
-
-for example:
-
-```Text
-sub-001/
-    func/
-        sub-001_task-rest_run-1_desc-confounds_regressors.tsv
-        sub-001_task-rest_run-1_desc-confounds_regressors.json
-```
-
-Any time series or regressor with one value per BOLD volume may be stored in a
-regressors file. If a column is specified in another sub-section, then any
-additional required metadata MUST be stored in the JSON description of the
-column.
-
-#### Column names
-
-Column names are unique alphanumeric values that are defined in a relevant JSON
-sidecar file. For a series of related columns, it is RECOMMENDED to use
-zero-based indexing as a suffix. For example, the first six aCompCor components
-may be named `a_comp_cor_00` ... `a_comp_cor_05`. Custom column names must not
-conflict with reserved names specified in this document.
-
-Reserved names are specified in the remaining subsections.
-
-#### Time series transformations
-
-Any column may have the following suffixes appended to indicate transformations
-applied to the original time series data:
-
-| Transformation | Description                                                                 |
-| -------------- | --------------------------------------------------------------------------- |
-| `_shift_back`  | The time series has been lagged by one TR. `x_shift_back[i] = x[i-1]`       |
-| `_dt`          | The discrete first derivative of the time series. `x_dt[i] = x[i+1] - x[i]` |
-| `_sq`          | The square of the time series                                               |
-| `_var_norm`    | The time series has been variance normalized                                |
-| `_centered`    | The time series has had its mean subtracted                                 |
-
-For example, `rot_z_shift_back_sq` means the square of the lagged version of the
-Z rotation (see Motion-related regressors).
-
-### ROI-based time series extraction
-
-Template:
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        func/
-            <source_keywords>_[atlas-<atlas_label>_][desc-<label>_]timeseries.<tsv|nii.gz>
-            <source_keywords>_[atlas-<atlas_label>_][desc-<label>_]timeseries.json
-```
-
-for example:
-
-```Text
-sub-001/
-    func/
-        sub-001_task-rest_run-1_atlas-AAL_timeseries.tsv
-        sub-001_task-rest_run-1_atlas-AAL_timeseries.json
-        sub-001_task-rest_run-1_desc-anaticor_timeseries.nii.gz
-        sub-001_task-rest_run-1_desc-anaticor_timeseries.json
-```
-
-Time series will generally be stored as tables, with a row of column headers
-indicating the name of the time series. In the case where every voxel has a time
-series (i.e., voxel-wise regressors, as in ANATICOR), then the time series
-should be saved as a NIfTI file.
-
-#### Column metadata special fields
-
-Atlas (optional) - A label indicating an atlas that defines a region or set of
-regions in the volume. An atlas may be three- or four-dimensional, which affects
-the interpretation of the roi index.
-
-ROI (optional) - For 3D atlases, the ROI label should be numeric, corresponding
-to the value of the voxels in the ROI. For 4D atlases, the ROI label should be
-numeric, corresponding to the volume index containing the ROI mask. The
-following special labels correspond to common ROIs that may be defined by many
-atlases or segmentation algorithms:
-
-| ROI Value      | Description                                                                            |
-| -------------- | -------------------------------------------------------------------------------------- |
-| WhiteMatter    | Signal derived from white matter ROI.                                                  |
-| CSF            | Signal derived from cerebro-spinal fluid ROI.                                          |
-| Background     | Signal derived from background (out of brain) ROI.                                     |
-| GreyMatter     | Signal derived from grey matter ROI.                                                   |
-| Ventricles     | Signal derived from ventricles ROI.                                                    |
-| CircleOfWillis | Signal derived from circle of Willis ROI.                                              |
-| GlobalSignal   | Vector of mean values within the brain mask. Can be used for Global Signal Regression. |
-
-#### Column names
-
-Column names are unique alphanumeric values that are defined in a relevant JSON
-sidecar file. A naming convention might be to concatenate the atlas, ROI index,
-summarization method (defined below) and transformations (see Time series
-transformations, above) using snake case. For example,
-`harvard_oxford_cortical_4_PC` could indicate ROI 4 of the Harvard-Oxford
-cortical atlas, summarized by taking the first principal component.
-
-#### Summarization methods
-
-To indicate the summarization method applied to construct a single time series
-for an ROI, the following column suffixes are defined:
-
-| Column suffix | Description of the transformation                                                                                                                       |
-| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `_mean`       | The mean of voxel time series                                                                                                                           |
-| `_median`     | The median of voxel time series                                                                                                                         |
-| `_pc[_<x>]`   | The ith eigenvariate from principal component analysis, where `x` is 0 indexed. If `x` is not specified, the first component is implied (i.e., `pc_0`). |
-| `_spat_reg`   | Spatial regression                                                                                                                                      |
-
-Example:
-
-```Text
-sub-001/
-    func/
-        sub-001_task-rest_run-1_timeseries.tsv
-```
-
-```Text
-white_matter_mean global_signal_mean ventricles_mean
-12                98                 11
-11                34                 53
-54                34                 34
-```
-
-```Text
-sub-001/
-    func/
-        sub-001_task-rest_run-1_timeseries.json
-```
-
-```JSON
-{
-    "white_matter_mean": {
-        "ROI": "WhiteMatter"
-    },
-    "global_signal_mean": {
-        "ROI": "GlobalSignal"
-    },
-    "ventricles_mean": {
-        "ROI": "Ventricles"
-    }
-}
-```
-
-### Motion-related regressors
-
-Template:
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-    func/
-        <source_keywords>_[desc-<label>_]motion.tsv
-        <source_keywords>_[desc-<label>_]motion.json
-```
-
-#### Column names
-
-The six basic motion parameters derived from motion correction have the
-following names and units:
-
-| Column name                     | Units   | Description            |
-| ------------------------------- | ------- | ---------------------- |
-| `trans_x`, `trans_y`, `trans_z` | mm      | Translation parameters |
-| `rot_x`, `rot_y`, `rot_z`       | radians | Rotation parameters    |
-
-Transformations (see Transformations) of motion parameters may be included in
-the same file. For example, rot_z_shift_back_sq means square of the lagged
-version of Z rotation.
-
-The following columns indicate summarized motion, as defined in the
-corresponding references:
-
-| Column name              | Units | Description                                                         |
-| ------------------------ | ----- | ------------------------------------------------------------------- |
-| `framewise_displacement` | mm    | Framewise displacement (Power, et al., 2012)                        |
-| `rmsd`                   | mm    | Root mean square deviation (Jenkinson, 1999)                        |
-| `rms`                    | mm    | Root mean square of translation parameters (Van Dijk, et al., 2012) |
-
-### Temporal outlier masks
-
-Template:
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        func/
-	        <source_keywords>_[desc-<label>_]outliers.tsv
-            <source_keywords>_[desc-<label>_]outliers.json
-```
-
-Outlier masks are columns of zeros (0), with ones (1) indicating volumes that
-have been identified as outliers by some method.
-
-#### Column names
-
-Column names for outliers correspond to the type of outlier or method for
-identifying the outlier. Column names should take the form `method[XX]`, where
-`XX` is an optional index.
-
-For example, if a BOLD series included two initial dummy scans,
-`non_steady_state` may be a column with a 1 for the first two volumes, or
-`non_steady_state_00` and `non_steady_state_01` may be columns with a 1 in the
-first and second position, respectively.
-
-The following methods are defined as reserved words:
-
-| Column name            | Description                                              |
-| ---------------------- | -------------------------------------------------------- |
-| `non_steady_state_<x>` | Initial non-steady-state volumes. One column per volume. |
-
-### Other time series and regressors
-
-Time series and regressors that are not otherwise specified should be placed in
-a regressors.tsv file (see General time series and regressors).
-
-#### Column names
-
-The following regressors are defined as reserved words:
-
-| Column name    | Description                                           |
-| -------------- | ----------------------------------------------------- |
-| `dvars`        | Change in variance (Brett, 2006, Power, et al., 2012) |
-| `std_dvars`    | Standardized DVARS (Nichols, 2013)                    |
-| `cosine_<X>`   | Discrete cosine basis vectors                         |
-| `legendre_<X>` | Legendre polynomial basis vectors                     |
-
-### Spatiotemporal decompositions
-
-Template:
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        func/
-            <source_keywords>_[desc-<label>_]<mixing|components>.tsv
-            <source_keywords>_[desc-<label>_]<mixing|components>.nii.gz
-            <source_keywords>_[desc-<label>_]decomposition.json
-```
-
-for example:
-
-```Text
-sub-001/
-    func/
-        sub-001_task-rest_run-1_desc-MELODIC_components.nii.gz
-        sub-001_task-rest_run-1_desc-MELODIC_mixing.tsv
-        sub-001_task-rest_run-1_desc-MELODIC_decomposition.json
-```
-
-```Text
-sub-001/
-    func/
-        sub-001_task-rest_run-1_desc-tICA_mixing.nii.gz
-        sub-001_task-rest_run-1_desc-tICA_components.tsv
-        sub-001_task-rest_run-1_desc-tICA_decomposition.json
-```
-
-Spatiotemporal decompositions produce either spatial or temporal components,
-along with conjugate mixing matrices that can be represented as time series and
-spatial maps, respectively. The combination of suffix and extension indicates
-which class of algorithm produced the outputs.
-
-Mixing matrices may be omitted for algorithms that are temporal decompositions
-with no spatial component, such as CompCor variants.
-
-Spatiotemporal decomposition files MUST be accompanied by a data dictionary in
-JSON format, consistent with Raw-BIDS section 4.2, which describes metadata for
-each column name. In addition to column names, the following MANDATORY field is
-added:
-
-| Key name | Description                                           |
-| -------- | ----------------------------------------------------- |
-| Method   | REQUIRED. Algorithm name and (if applicable) version. |
-
-#### Column names
-
-Column names in spatiotemporal decompositions take the form of
-`<decomposition>_<index>`, where `<decomposition>` is the name of the
-decomposition algorithm, and `<index>` is a numeric identifier. Indices SHOULD
-start at 0. If there is a natural ordering, indices should reflect that
-ordering. For example, the aCompCor component which explains the most variance
-should be named `a_comp_cor_00`.
-
-The following reserved words indicate common algorithms:
-
-| Column name              | Description                                                                                                                                                                                                |
-| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `[a|t|w|c]_comp_cor_<x>` | CompCor (Behzadi, et al., 2007) calculated with voxels chosen based on: `a`: anatomically derived ROIs (white matter and CSF), `t`: temporal variance, `w`: white matter voxels only, `c`: CSF voxels only |
-| `melodic_<x>`            | Columns from the mixing matrix in FSL MELODIC                                                                                                                                                              |
+# Functional derivatives
+
+## Functional derivatives maps
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        func/
+            <source_keywords>[_referencemap-<referencemap>][_desc-<label>]_<suffix>.nii[.gz]
+            <source_keywords>[_referencemap-<referencemap>][_desc-<label>]_<suffix>.json
+```
+
+for example:
+
+```Text
+pipeline1/
+    sub-001/
+        func/
+            sub-001_task-rest_run-1_space-MNI305_mean.nii.gz
+            sub-001_task-rest_run-1_space-MNI305_mean.json
+```
+
+The following table lists allowed suffixes and their corresponding measures:
+
+| `<suffix>`       | Measure                                                          |
+| ---------------- | ---------------------------------------------------------------- |
+| `mean`           | Mean across the temporal/4th dimension of the data               |
+| `std`            | Standard deviation across the temporal/4th dimension of the data |
+| `tsnr`           | Temporal SNR (i.e. mean / std)                                   |
+| `sfs`            | Signal fluctuation sensitivity                                   |
+| `alff`           | Amplitude low frequency fluctuations                             |
+| `falff`          | Fractional amplitude of low frequency fluctuations               |
+| `reho`           | Regional homogeneity (voxelwise only)                            |
+| `dcb`, `dcw`     | Voxelwise degree centrality binary and weighted                  |
+| `ecb`, `ecw`     | Voxelwise eigenvector centrality binary and weighted             |
+| `lfcdb`, `lfcdw` | Local functional connectivity density                            |
+| `vmhc`           | Voxel mirrored homotopic connectivity                            |
+
+The following metadata JSON fields are valid for derivative maps:
+
+| Key name       | Description                                                               | Required for suffix        |
+| -------------- | ------------------------------------------------------------------------- | -------------------------- |
+| BandpassFilter | String describing all relevant parameters of the applied bandpass filter. | `alff`, `falff`            |
+| Neighborhood   | String describing neighborhood for regional measures.                     | `reho`                     |
+| Threshold      | String describing threshold used for determining graph edges.             | `dcb`, `dcw`, `ecb`, `ecw` |
+| Method         | String describing method used to calculate measure.                       | `dcb`, `dcw`, `ecb`, `ecw` |
+
+## Time series and regressors
+
+For the purposes of this section, a time series or regressor is a numeric series
+of values corresponding to volumes in a BOLD series. Time series is specifically
+used to indicate an aggregate time series within an ROI, while regressor is used
+as a more general term indicating series that may be derived from other sources,
+such as head motion estimates or physiological recordings.
+
+Regressors will generally be stored as tables, with a row of column headers
+indicating the name of the regressor. In the case where every voxel has a
+regressor, then the data should be stored in a 4D NIfTI file.
+
+Tabular regressor files MUST be accompanied by a data dictionary in JSON format,
+consistent with the format described in
+[Common princioples](../02-common-principles.md).
+
+Volumetric regressor files MAY be accompanied by a data dictionary in JSON
+format, with OPTIONAL `LongName`, `Description`, `Levels`, `Units`, and
+`TermURL` fields.
+
+### General time series and regressors
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        func/
+	        <source_keywords>[_desc-<label>]_regressors.tsv
+	        <source_keywords>[_desc-<label>]_regressors.json
+```
+
+for example:
+
+```Text
+sub-001/
+    func/
+        sub-001_task-rest_run-1_desc-confounds_regressors.tsv
+        sub-001_task-rest_run-1_desc-confounds_regressors.json
+```
+
+Any time series or regressor with one value per BOLD volume may be stored in a
+regressors file. If a column is specified in another sub-section, then any
+additional required metadata MUST be stored in the JSON description of the
+column.
+
+#### Column names
+
+Column names are unique alphanumeric values that are defined in a relevant JSON
+sidecar file. For a series of related columns, it is RECOMMENDED to use
+zero-based indexing as a suffix. For example, the first six aCompCor components
+may be named `a_comp_cor_00` ... `a_comp_cor_05`. Custom column names must not
+conflict with reserved names specified in this document.
+
+Reserved names are specified in the remaining subsections.
+
+#### Time series transformations
+
+Any column may have the following suffixes appended to indicate transformations
+applied to the original time series data:
+
+| Transformation | Description                                                                 |
+| -------------- | --------------------------------------------------------------------------- |
+| `_shift_back`  | The time series has been lagged by one TR. `x_shift_back[i] = x[i-1]`       |
+| `_dt`          | The discrete first derivative of the time series. `x_dt[i] = x[i+1] - x[i]` |
+| `_sq`          | The square of the time series                                               |
+| `_var_norm`    | The time series has been variance normalized                                |
+| `_centered`    | The time series has had its mean subtracted                                 |
+
+For example, `rot_z_shift_back_sq` means the square of the lagged version of the
+Z rotation (see Motion-related regressors).
+
+### ROI-based time series extraction
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        func/
+            <source_keywords>[_atlas-<atlas_label>][_desc-<label>]_timeseries.<tsv|nii.gz>
+            <source_keywords>[_atlas-<atlas_label>][_desc-<label>]_timeseries.json
+```
+
+for example:
+
+```Text
+sub-001/
+    func/
+        sub-001_task-rest_run-1_atlas-AAL_timeseries.tsv
+        sub-001_task-rest_run-1_atlas-AAL_timeseries.json
+        sub-001_task-rest_run-1_desc-anaticor_timeseries.nii.gz
+        sub-001_task-rest_run-1_desc-anaticor_timeseries.json
+```
+
+Time series will generally be stored as tables, with a row of column headers
+indicating the name of the time series. In the case where every voxel has a time
+series (i.e., voxel-wise regressors, as in ANATICOR), then the time series
+should be saved as a NIfTI file.
+
+#### Column metadata special fields
+
+Atlas (optional) - A label indicating an atlas that defines a region or set of
+regions in the volume. An atlas may be three- or four-dimensional, which affects
+the interpretation of the roi index.
+
+ROI (optional) - For 3D atlases, the ROI label should be numeric, corresponding
+to the value of the voxels in the ROI. For 4D atlases, the ROI label should be
+numeric, corresponding to the volume index containing the ROI mask. The
+following special labels correspond to common ROIs that may be defined by many
+atlases or segmentation algorithms:
+
+| ROI Value      | Description                                                                            |
+| -------------- | -------------------------------------------------------------------------------------- |
+| WhiteMatter    | Signal derived from white matter ROI.                                                  |
+| CSF            | Signal derived from cerebro-spinal fluid ROI.                                          |
+| Background     | Signal derived from background (out of brain) ROI.                                     |
+| GreyMatter     | Signal derived from grey matter ROI.                                                   |
+| Ventricles     | Signal derived from ventricles ROI.                                                    |
+| CircleOfWillis | Signal derived from circle of Willis ROI.                                              |
+| GlobalSignal   | Vector of mean values within the brain mask. Can be used for Global Signal Regression. |
+
+#### Column names
+
+Column names are unique alphanumeric values that are defined in a relevant JSON
+sidecar file. A naming convention might be to concatenate the atlas, ROI index,
+summarization method (defined below) and transformations (see Time series
+transformations, above) using snake case. For example,
+`harvard_oxford_cortical_4_PC` could indicate ROI 4 of the Harvard-Oxford
+cortical atlas, summarized by taking the first principal component.
+
+#### Summarization methods
+
+To indicate the summarization method applied to construct a single time series
+for an ROI, the following column suffixes are defined:
+
+| Column suffix | Description of the transformation                                                                                                                       |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `_mean`       | The mean of voxel time series                                                                                                                           |
+| `_median`     | The median of voxel time series                                                                                                                         |
+| `_pc[_<x>]`   | The ith eigenvariate from principal component analysis, where `x` is 0 indexed. If `x` is not specified, the first component is implied (i.e., `pc_0`). |
+| `_spat_reg`   | Spatial regression                                                                                                                                      |
+
+Example:
+
+```Text
+sub-001/
+    func/
+        sub-001_task-rest_run-1_timeseries.tsv
+```
+
+```Text
+white_matter_mean global_signal_mean ventricles_mean
+12                98                 11
+11                34                 53
+54                34                 34
+```
+
+```Text
+sub-001/
+    func/
+        sub-001_task-rest_run-1_timeseries.json
+```
+
+```JSON
+{
+    "white_matter_mean": {
+        "ROI": "WhiteMatter"
+    },
+    "global_signal_mean": {
+        "ROI": "GlobalSignal"
+    },
+    "ventricles_mean": {
+        "ROI": "Ventricles"
+    }
+}
+```
+
+### Motion-related regressors
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+    func/
+        <source_keywords>[_desc-<label>]_motion.tsv
+        <source_keywords>[_desc-<label>]_motion.json
+```
+
+#### Column names
+
+The six basic motion parameters derived from motion correction have the
+following names and units:
+
+| Column name                     | Units   | Description            |
+| ------------------------------- | ------- | ---------------------- |
+| `trans_x`, `trans_y`, `trans_z` | mm      | Translation parameters |
+| `rot_x`, `rot_y`, `rot_z`       | radians | Rotation parameters    |
+
+Transformations (see Transformations) of motion parameters may be included in
+the same file. For example, rot_z_shift_back_sq means square of the lagged
+version of Z rotation.
+
+The following columns indicate summarized motion, as defined in the
+corresponding references:
+
+| Column name              | Units | Description                                                         |
+| ------------------------ | ----- | ------------------------------------------------------------------- |
+| `framewise_displacement` | mm    | Framewise displacement (Power, et al., 2012)                        |
+| `rmsd`                   | mm    | Root mean square deviation (Jenkinson, 1999)                        |
+| `rms`                    | mm    | Root mean square of translation parameters (Van Dijk, et al., 2012) |
+
+### Temporal outlier masks
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        func/
+	        <source_keywords>[_desc-<label>]_outliers.tsv
+            <source_keywords>[_desc-<label>]_outliers.json
+```
+
+Outlier masks are columns of zeros (0), with ones (1) indicating volumes that
+have been identified as outliers by some method.
+
+#### Column names
+
+Column names for outliers correspond to the type of outlier or method for
+identifying the outlier. Column names should take the form `method[XX]`, where
+`XX` is an optional index.
+
+For example, if a BOLD series included two initial dummy scans,
+`non_steady_state` may be a column with a 1 for the first two volumes, or
+`non_steady_state_00` and `non_steady_state_01` may be columns with a 1 in the
+first and second position, respectively.
+
+The following methods are defined as reserved words:
+
+| Column name            | Description                                              |
+| ---------------------- | -------------------------------------------------------- |
+| `non_steady_state_<x>` | Initial non-steady-state volumes. One column per volume. |
+
+### Other time series and regressors
+
+Time series and regressors that are not otherwise specified should be placed in
+a regressors.tsv file (see General time series and regressors).
+
+#### Column names
+
+The following regressors are defined as reserved words:
+
+| Column name    | Description                                           |
+| -------------- | ----------------------------------------------------- |
+| `dvars`        | Change in variance (Brett, 2006, Power, et al., 2012) |
+| `std_dvars`    | Standardized DVARS (Nichols, 2013)                    |
+| `cosine_<X>`   | Discrete cosine basis vectors                         |
+| `legendre_<X>` | Legendre polynomial basis vectors                     |
+
+### Spatiotemporal decompositions
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        func/
+            <source_keywords>[_desc-<label>]_<mixing|components>.tsv
+            <source_keywords>[_desc-<label>]_<mixing|components>.nii.gz
+            <source_keywords>[_desc-<label>]_decomposition.json
+```
+
+for example:
+
+```Text
+sub-001/
+    func/
+        sub-001_task-rest_run-1_desc-MELODIC_components.nii.gz
+        sub-001_task-rest_run-1_desc-MELODIC_mixing.tsv
+        sub-001_task-rest_run-1_desc-MELODIC_decomposition.json
+```
+
+```Text
+sub-001/
+    func/
+        sub-001_task-rest_run-1_desc-tICA_mixing.nii.gz
+        sub-001_task-rest_run-1_desc-tICA_components.tsv
+        sub-001_task-rest_run-1_desc-tICA_decomposition.json
+```
+
+Spatiotemporal decompositions produce either spatial or temporal components,
+along with conjugate mixing matrices that can be represented as time series and
+spatial maps, respectively. The combination of suffix and extension indicates
+which class of algorithm produced the outputs.
+
+Mixing matrices may be omitted for algorithms that are temporal decompositions
+with no spatial component, such as CompCor variants.
+
+Spatiotemporal decomposition files MUST be accompanied by a data dictionary in
+JSON format, consistent with Raw-BIDS section 4.2, which describes metadata for
+each column name. In addition to column names, the following MANDATORY field is
+added:
+
+| Key name | Description                                           |
+| -------- | ----------------------------------------------------- |
+| Method   | REQUIRED. Algorithm name and (if applicable) version. |
+
+#### Column names
+
+Column names in spatiotemporal decompositions take the form of
+`<decomposition>_<index>`, where `<decomposition>` is the name of the
+decomposition algorithm, and `<index>` is a numeric identifier. Indices SHOULD
+start at 0. If there is a natural ordering, indices should reflect that
+ordering. For example, the aCompCor component which explains the most variance
+should be named `a_comp_cor_00`.
+
+The following reserved words indicate common algorithms:
+
+| Column name              | Description                                                                                                                                                                                                |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `[a|t|w|c]_comp_cor_<x>` | CompCor (Behzadi, et al., 2007) calculated with voxels chosen based on: `a`: anatomically derived ROIs (white matter and CSF), `t`: temporal variance, `w`: white matter voxels only, `c`: CSF voxels only |
+| `melodic_<x>`            | Columns from the mixing matrix in FSL MELODIC                                                                                                                                                              |

From 5ef3b65f70553868751875041a4491ff36603c3d Mon Sep 17 00:00:00 2001
From: Franco Pestilli <frakkopesto@gmail.com>
Date: Thu, 3 Jan 2019 14:45:43 -0800
Subject: [PATCH 009/191] Update src/05-derivatives/05-diffusion-derivatives.md

Co-Authored-By: chrisfilo <krzysztof.gorgolewski@gmail.com>
---
 src/05-derivatives/05-diffusion-derivatives.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index badea94598..45b756e7ce 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -20,7 +20,7 @@ The JSON sidecar file is REQUIRED (due to the REQUIRED `SkullStripped` field -
 see [Common Data Types](02-common-data-types.md)), and if present can be used to
 store information about what preprocessing options were used (for example
 whether motion compensation was performed, non-linear corrections were applied,
-whether Eddy current correction was performed, denoising, or intensity
+ whether eddy current correction was performed, denoising, or intensity
 normalization were applied, etc).
 
 Additional reserved JSON metadata fields:

From 548b4358f53b2cba554080ea0796c7d325a0f3e3 Mon Sep 17 00:00:00 2001
From: Franco Pestilli <frakkopesto@gmail.com>
Date: Thu, 3 Jan 2019 14:46:05 -0800
Subject: [PATCH 010/191] Update src/05-derivatives/05-diffusion-derivatives.md

Co-Authored-By: chrisfilo <krzysztof.gorgolewski@gmail.com>
---
 src/05-derivatives/05-diffusion-derivatives.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 45b756e7ce..ce5bccdccb 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -27,7 +27,7 @@ Additional reserved JSON metadata fields:
 
 | **Key name**           | **Description**                                                                                                          |
 | ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| MotionCompensation     | OPTONAL. Boolean. Motion compensation                                                                                    |
+ | MotionCorrection     | OPTONAL. Boolean. Motion correction                                                                                    |
 | EddyCurrentCorrection  | OPTONAL. Boolean. Eddy currents corrections                                                                              |
 | Denoising              | OPTIONAL. String. Denoising method                                                                                       |
 | IntensityNormalization | OPTIONAL. Boolean. Intensity normalization                                                                               |

From a2fd24b991b362e3040fae3cf99648abeb95dc84 Mon Sep 17 00:00:00 2001
From: Franco Pestilli <frakkopesto@gmail.com>
Date: Thu, 3 Jan 2019 14:46:18 -0800
Subject: [PATCH 011/191] Update src/05-derivatives/05-diffusion-derivatives.md

Co-Authored-By: chrisfilo <krzysztof.gorgolewski@gmail.com>
---
 src/05-derivatives/05-diffusion-derivatives.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index ce5bccdccb..aac5b6eecc 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -323,7 +323,7 @@ tractography, each with various supported algorithms.
 | Class  | Algorithms | Reference                                                                                                                                                       |
 | ------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | LOCAL  | PROB       | Sherbondy, A.J., et al. (2008).Tournier J.D.et al. (2012).Behrens et al. (2007)                                                                                 |
-| LOCAL  | DET        | Conturo, T. et al. (1999)Mori, S. et al. (1999)                                                                                                                 |
+ | LOCAL  | DET        | Conturo, T. et al. (1999); Mori, S. et al. (1999)                                                                                                                 |
 | LOCAL  | EUDX       | Garyfallidis et al. (2010)Mori, S. et al. (1999)                                                                                                                |
 | LOCAL  | FACT       | Jiang, H. et al. (2005)                                                                                                                                         |
 | LOCAL  | STT        | Lazar, M., et al. (2003)                                                                                                                                        |

From 5cbf9e39faa6942ee0b8b9042ce4ad6b7c31fcff Mon Sep 17 00:00:00 2001
From: Franco Pestilli <frakkopesto@gmail.com>
Date: Thu, 3 Jan 2019 14:46:33 -0800
Subject: [PATCH 012/191] Update src/05-derivatives/05-diffusion-derivatives.md

Co-Authored-By: chrisfilo <krzysztof.gorgolewski@gmail.com>
---
 src/05-derivatives/05-diffusion-derivatives.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index aac5b6eecc..ece903f1a0 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -324,7 +324,7 @@ tractography, each with various supported algorithms.
 | ------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | LOCAL  | PROB       | Sherbondy, A.J., et al. (2008).Tournier J.D.et al. (2012).Behrens et al. (2007)                                                                                 |
  | LOCAL  | DET        | Conturo, T. et al. (1999); Mori, S. et al. (1999)                                                                                                                 |
-| LOCAL  | EUDX       | Garyfallidis et al. (2010)Mori, S. et al. (1999)                                                                                                                |
+ | LOCAL  | EUDX       | Garyfallidis et al. (2010); Mori, S. et al. (1999)                                                                                                                |
 | LOCAL  | FACT       | Jiang, H. et al. (2005)                                                                                                                                         |
 | LOCAL  | STT        | Lazar, M., et al. (2003)                                                                                                                                        |
 | GLOBAL | UKF        | Malcolm J-G., et al. (2009)                                                                                                                                     |

From 0d1bf410ed65f89df9527736e24f98312540fce8 Mon Sep 17 00:00:00 2001
From: Franco Pestilli <frakkopesto@gmail.com>
Date: Thu, 3 Jan 2019 14:46:48 -0800
Subject: [PATCH 013/191] Update src/05-derivatives/05-diffusion-derivatives.md

Co-Authored-By: chrisfilo <krzysztof.gorgolewski@gmail.com>
---
 src/05-derivatives/05-diffusion-derivatives.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index ece903f1a0..ad27de49f9 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -322,7 +322,7 @@ tractography, each with various supported algorithms.
 
 | Class  | Algorithms | Reference                                                                                                                                                       |
 | ------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| LOCAL  | PROB       | Sherbondy, A.J., et al. (2008).Tournier J.D.et al. (2012).Behrens et al. (2007)                                                                                 |
+ | LOCAL  | PROB       | Sherbondy, A.J., et al. (2008); Tournier J.D.et al. (2012); Behrens et al. (2007)                                                                                 |
  | LOCAL  | DET        | Conturo, T. et al. (1999); Mori, S. et al. (1999)                                                                                                                 |
  | LOCAL  | EUDX       | Garyfallidis et al. (2010); Mori, S. et al. (1999)                                                                                                                |
 | LOCAL  | FACT       | Jiang, H. et al. (2005)                                                                                                                                         |

From 5ce934748b22bb87aee0fbf527f2a1fd3db31899 Mon Sep 17 00:00:00 2001
From: Franco Pestilli <frakkopesto@gmail.com>
Date: Thu, 3 Jan 2019 14:47:14 -0800
Subject: [PATCH 014/191] Update src/05-derivatives/05-diffusion-derivatives.md

Co-Authored-By: chrisfilo <krzysztof.gorgolewski@gmail.com>
---
 src/05-derivatives/05-diffusion-derivatives.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index ad27de49f9..e1df6ce363 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -330,7 +330,7 @@ tractography, each with various supported algorithms.
 | GLOBAL | UKF        | Malcolm J-G., et al. (2009)                                                                                                                                     |
 | GLOBAL | SpinGlass  | Fillard P., et al. (2009)                                                                                                                                       |
 | GLOBAL | ENS        | Takemura et al. (2016)                                                                                                                                          |
-| GLOBAL | Other      | Mangin, J.F. et al. (2013).Aganj, I. et al. (2011).Neher, P.F. et al. (2012).Jbabdi, S., et al. (2007).Sherbondy, A.J., et al. (2009).Reisert, M. et al. (2011) |
+ | GLOBAL | Other      | Mangin, J.F. et al. (2013); Aganj, I. et al. (2011); Neher, P.F. et al. (2012); Jbabdi, S., et al. (2007); Sherbondy, A.J., et al. (2009); Reisert, M. et al. (2011) |
 
 The JSON sidecar contains the following key/value pairs:
 

From a5917b154dcd7d347c426b209808cf908a75ac0e Mon Sep 17 00:00:00 2001
From: Franco Pestilli <frakkopesto@gmail.com>
Date: Thu, 3 Jan 2019 14:47:40 -0800
Subject: [PATCH 015/191] Update src/05-derivatives/05-diffusion-derivatives.md

Co-Authored-By: chrisfilo <krzysztof.gorgolewski@gmail.com>
---
 src/05-derivatives/05-diffusion-derivatives.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index e1df6ce363..6fedb37629 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -259,7 +259,7 @@ These maps are saved 3D NIfTI files (x,y,z, 1).
 | DECFA               | Directionally-encoded color (DEC) FA                                                                                        | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   | 3 8-bit floating point numbers that encode x,y,z of the principal diffusion direction in the voxel. The norm of the vector is the FA in the voxel.Need to set the NiFTI dtype to RGB |
 | ODI                 | Orientation dispersion index                                                                                                | NODDI                                                                                                                        | Normalised to \[0,1\]                                                                                                                                                                |
 | ISOVF               | Isotropic volume fraction                                                                                                   | NODDI                                                                                                                        | microns^2/ms (for example, for free water in body temperature, this should be 3)                                                                                                     |
-| TDI                 | Track Density Imaging                                                                                                       |                                                                                                                              | Streamline visitation counts?                                                                                                                                                        |
+ | TDI                 | Track Density Imaging                                                                                                       |                                                                                                                              | Streamline visitation counts                                                                                                                                                       |
 | GFA                 | Generalized Fractional Anisotropy                                                                                           | CSA, CSD, SHORE, MAPMRI, Forecast (or any model that can be represented as an ODF)                                           | Proportion \[0 - 1\]                                                                                                                                                                 |
 | AFD                 | Apparent Fiber Density                                                                                                      |                                                                                                                              | positive, unitless                                                                                                                                                                   |
 | INDEX               | Scalar maps from bedpostx                                                                                                   | FSUM (sum of partial volume fractions of the sticks)F_i (volume fraction of stick i)D (diffusivity)DSTD (std of diffusivity) | FSUM \[0 - 1\]F_i \[0 - 1\]D and DSTD microns^2/ms (for example, for free water in body temperature, this should be 3)                                                               |

From 0f29a1f1c1926eeb85bbaf86544c8bdf650e5355 Mon Sep 17 00:00:00 2001
From: Franco Pestilli <frakkopesto@gmail.com>
Date: Thu, 3 Jan 2019 14:47:54 -0800
Subject: [PATCH 016/191] Update src/05-derivatives/05-diffusion-derivatives.md

Co-Authored-By: chrisfilo <krzysztof.gorgolewski@gmail.com>
---
 src/05-derivatives/05-diffusion-derivatives.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 6fedb37629..3c1e0f3d25 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -312,7 +312,7 @@ kept, or `subsampled50` if only 50% of the streamlines were kept.
 
 ### File formats
 
-- [.trk - Diffusion Toolkit (+TrackVis)](http://www.trackvis.org/docs/?subsect=fileformatEmbeds)
+ - [.trk - Diffusion Toolkit (+TrackVis)](http://www.trackvis.org/docs/?subsect=fileformat)
 - [.tck - MRTrix](http://mrtrix.readthedocs.io/en/latest/getting_started/image_data.html#tracks-file-format-tckAssumes)
 
 ### JSON Metadata

From b515b044b347ba87c21ffa418b983ddf5ea7621d Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Thu, 3 Jan 2019 15:06:29 -0800
Subject: [PATCH 017/191] syntax fixes

---
 .../05-diffusion-derivatives.md               | 146 +++++++++---------
 1 file changed, 73 insertions(+), 73 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 3c1e0f3d25..320fc49b89 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -20,14 +20,14 @@ The JSON sidecar file is REQUIRED (due to the REQUIRED `SkullStripped` field -
 see [Common Data Types](02-common-data-types.md)), and if present can be used to
 store information about what preprocessing options were used (for example
 whether motion compensation was performed, non-linear corrections were applied,
- whether eddy current correction was performed, denoising, or intensity
+whether eddy current correction was performed, denoising, or intensity
 normalization were applied, etc).
 
 Additional reserved JSON metadata fields:
 
 | **Key name**           | **Description**                                                                                                          |
 | ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
- | MotionCorrection     | OPTONAL. Boolean. Motion correction                                                                                    |
+| MotionCorrection       | OPTONAL. Boolean. Motion correction                                                                                      |
 | EddyCurrentCorrection  | OPTONAL. Boolean. Eddy currents corrections                                                                              |
 | Denoising              | OPTIONAL. String. Denoising method                                                                                       |
 | IntensityNormalization | OPTIONAL. Boolean. Intensity normalization                                                                               |
@@ -92,19 +92,19 @@ The JSON sidecar contains the following key/value pairs common for all models:
 
     -   `DTI` :
 
-        - `FitMethod` : {`WLS`,`OLS`,`NLLS`,`RESTORE`}
-        - `RESTORE` : sigma
+        -   `FitMethod` : {`WLS`,`OLS`,`NLLS`,`RESTORE`}
+        -   `RESTORE` : sigma
 
     -   `DKI` and `WMTI`:
 
-        - `FitMethod` : {`WLS`,`OLS`,`NLLS`}
+        -   `FitMethod` : {`WLS`,`OLS`,`NLLS`}
 
     -   `CSD`:
 
-        - `SphericalHarmonicOrder` : value
-        - `ResponseFunctionOrder` : value
-        - `ResponseFunction` : \[1:response_function_order_value,b0mean\]
-        - `Basis` : {`MRtrix 0.2`,`MRtrix3`,`DESCOTEAUX`}
+        -   `SphericalHarmonicOrder` : value
+        -   `ResponseFunctionOrder` : value
+        -   `ResponseFunction` : \[1:response_function_order_value,b0mean\]
+        -   `Basis` : {`MRtrix 0.2`,`MRtrix3`,`DESCOTEAUX`}
 
     -   `CSDM`:
 
@@ -120,65 +120,65 @@ The JSON sidecar contains the following key/value pairs common for all models:
 
     -   `NODDI`:
 
-        - `DPar` : value
-        - `DIso` : value
-        - `Lambda1` : value
-        - `Lambda2` : value
+        -   `DPar` : value
+        -   `DIso` : value
+        -   `Lambda1` : value
+        -   `Lambda2` : value
 
     -   `DSI` :
 
-        - `GridSize` : value
-        - `RStart` : value
-        - `RStep` : value
-        - `REnd` : value
-        - `FilterWidth` : value
+        -   `GridSize` : value
+        -   `RStart` : value
+        -   `RStep` : value
+        -   `REnd` : value
+        -   `FilterWidth` : value
 
     -   `CSA` :
 
-        - `SphericalHarmonicOrder` : value
-        - `Smoothing` : value
-        - `Basis` : value
+        -   `SphericalHarmonicOrder` : value
+        -   `Smoothing` : value
+        -   `Basis` : value
 
     -   `SHORE` :
 
-        - `RadialOrder` : value
-        - `Zeta` : value
-        - `LambdaN` : value
-        - `LambdaL` : value
-        - `Tau` : value
-        - `ConstrainE0` : value
-        - `PositiveConstraint` : value
-        - `PosGrid` : value
-        - `PosRadius` : value
+        -   `RadialOrder` : value
+        -   `Zeta` : value
+        -   `LambdaN` : value
+        -   `LambdaL` : value
+        -   `Tau` : value
+        -   `ConstrainE0` : value
+        -   `PositiveConstraint` : value
+        -   `PosGrid` : value
+        -   `PosRadius` : value
 
     -   `MAPMRI` :
 
-        - `RadialOrder` : value
-        - `LaplacianRegularization` : bool
-        - `LaplacianWeighting` : value
-        - `PositivityConstraint` : bool
-        - `Tau` : value
-        - `ConstrainE0` : value
-        - `PositiveConstraint` : value
-        - `PosGrid` : value
-        - `PosRadius` : value
-        - `AnisotropicScaling` : bool
-        - `EigenvalueThreshold` : value
-        - `PosGrid` : value
-        - `BvalThreshold` : value
-        - `DTIScaleEstimation` : bool
-        - `StaticDiffusivity` : value
+        -   `RadialOrder` : value
+        -   `LaplacianRegularization` : bool
+        -   `LaplacianWeighting` : value
+        -   `PositivityConstraint` : bool
+        -   `Tau` : value
+        -   `ConstrainE0` : value
+        -   `PositiveConstraint` : value
+        -   `PosGrid` : value
+        -   `PosRadius` : value
+        -   `AnisotropicScaling` : bool
+        -   `EigenvalueThreshold` : value
+        -   `PosGrid` : value
+        -   `BvalThreshold` : value
+        -   `DTIScaleEstimation` : bool
+        -   `StaticDiffusivity` : value
 
     -   `FORECAST` :
 
-        - `Sphere` : value
-        - `DecAlg` : value
-        - `LambdaLb` : value
-        - `SphericalHarmonicsOrder` : value
+        -   `Sphere` : value
+        -   `DecAlg` : value
+        -   `LambdaLb` : value
+        -   `SphericalHarmonicsOrder` : value
 
     -   `fwDTI` :
 
-        - `FitMethod` : {"WLS","NLLS"}
+        -   `FitMethod` : {"WLS","NLLS"}
 
     -   `BEDPOSTX` :
 
@@ -259,7 +259,7 @@ These maps are saved 3D NIfTI files (x,y,z, 1).
 | DECFA               | Directionally-encoded color (DEC) FA                                                                                        | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   | 3 8-bit floating point numbers that encode x,y,z of the principal diffusion direction in the voxel. The norm of the vector is the FA in the voxel.Need to set the NiFTI dtype to RGB |
 | ODI                 | Orientation dispersion index                                                                                                | NODDI                                                                                                                        | Normalised to \[0,1\]                                                                                                                                                                |
 | ISOVF               | Isotropic volume fraction                                                                                                   | NODDI                                                                                                                        | microns^2/ms (for example, for free water in body temperature, this should be 3)                                                                                                     |
- | TDI                 | Track Density Imaging                                                                                                       |                                                                                                                              | Streamline visitation counts                                                                                                                                                       |
+| TDI                 | Track Density Imaging                                                                                                       |                                                                                                                              | Streamline visitation counts                                                                                                                                                         |
 | GFA                 | Generalized Fractional Anisotropy                                                                                           | CSA, CSD, SHORE, MAPMRI, Forecast (or any model that can be represented as an ODF)                                           | Proportion \[0 - 1\]                                                                                                                                                                 |
 | AFD                 | Apparent Fiber Density                                                                                                      |                                                                                                                              | positive, unitless                                                                                                                                                                   |
 | INDEX               | Scalar maps from bedpostx                                                                                                   | FSUM (sum of partial volume fractions of the sticks)F_i (volume fraction of stick i)D (diffusivity)DSTD (std of diffusivity) | FSUM \[0 - 1\]F_i \[0 - 1\]D and DSTD microns^2/ms (for example, for free water in body temperature, this should be 3)                                                               |
@@ -312,25 +312,25 @@ kept, or `subsampled50` if only 50% of the streamlines were kept.
 
 ### File formats
 
- - [.trk - Diffusion Toolkit (+TrackVis)](http://www.trackvis.org/docs/?subsect=fileformat)
-- [.tck - MRTrix](http://mrtrix.readthedocs.io/en/latest/getting_started/image_data.html#tracks-file-format-tckAssumes)
+-   [.trk - Diffusion Toolkit (+TrackVis)](https://web.archive.org/web/20190103230122/http://www.trackvis.org/docs/?subsect=fileformat)
+-   [.tck - MRTrix](https://web.archive.org/web/20190103230209/https://mrtrix.readthedocs.io/en/latest/getting_started/image_data.html)
 
 ### JSON Metadata
 
 We have two main classes of tractography algorithms: Global or Local
 tractography, each with various supported algorithms.
 
-| Class  | Algorithms | Reference                                                                                                                                                       |
-| ------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
- | LOCAL  | PROB       | Sherbondy, A.J., et al. (2008); Tournier J.D.et al. (2012); Behrens et al. (2007)                                                                                 |
- | LOCAL  | DET        | Conturo, T. et al. (1999); Mori, S. et al. (1999)                                                                                                                 |
- | LOCAL  | EUDX       | Garyfallidis et al. (2010); Mori, S. et al. (1999)                                                                                                                |
-| LOCAL  | FACT       | Jiang, H. et al. (2005)                                                                                                                                         |
-| LOCAL  | STT        | Lazar, M., et al. (2003)                                                                                                                                        |
-| GLOBAL | UKF        | Malcolm J-G., et al. (2009)                                                                                                                                     |
-| GLOBAL | SpinGlass  | Fillard P., et al. (2009)                                                                                                                                       |
-| GLOBAL | ENS        | Takemura et al. (2016)                                                                                                                                          |
- | GLOBAL | Other      | Mangin, J.F. et al. (2013); Aganj, I. et al. (2011); Neher, P.F. et al. (2012); Jbabdi, S., et al. (2007); Sherbondy, A.J., et al. (2009); Reisert, M. et al. (2011) |
+| Class  | Algorithms | Reference                                                                                                                                                            |
+| ------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| LOCAL  | PROB       | Sherbondy, A.J., et al. (2008); Tournier J.D.et al. (2012); Behrens et al. (2007)                                                                                    |
+| LOCAL  | DET        | Conturo, T. et al. (1999); Mori, S. et al. (1999)                                                                                                                    |
+| LOCAL  | EUDX       | Garyfallidis et al. (2010); Mori, S. et al. (1999)                                                                                                                   |
+| LOCAL  | FACT       | Jiang, H. et al. (2005)                                                                                                                                              |
+| LOCAL  | STT        | Lazar, M. et al. (2003)                                                                                                                                              |
+| GLOBAL | UKF        | Malcolm J-G. et al. (2009)                                                                                                                                           |
+| GLOBAL | SpinGlass  | Fillard P. et al. (2009)                                                                                                                                             |
+| GLOBAL | ENS        | Takemura et al. (2016)                                                                                                                                               |
+| GLOBAL | Other      | Mangin, J.F. et al. (2013); Aganj, I. et al. (2011); Neher, P.F. et al. (2012); Jbabdi, S., et al. (2007); Sherbondy, A.J., et al. (2009); Reisert, M. et al. (2011) |
 
 The JSON sidecar contains the following key/value pairs:
 
@@ -342,15 +342,15 @@ The JSON sidecar contains the following key/value pairs:
 RECOMMENDED when TractographyMethod is `probabilistic`, `deterministic`, `eudx`,
 `fact`, `stt`, `other`:
 
-| **Key name**             | **Description**                                                 |
-| ------------------------ | --------------------------------------------------------------- |
-| StepSizeUnits            | "mm","norm"                                                     |
-| StepSize                 | value                                                           |
-| AngleCurvature           | value                                                           |
-| SeedingMethod            | "seedsPerVoxel", "globalSeedNumber", "totalStreamlinesNumber"   |
-| SeedingNumberMethod      | integer for the number of seeds                                 |
-| TerminationCriterion     | "leaveMask", "reachingTissueType”                               |
-| TerminationCriterionTest | "binary","ACT","CMC"                                            |
+| **Key name**             | **Description**                                               |
+| ------------------------ | ------------------------------------------------------------- |
+| StepSizeUnits            | "mm","norm"                                                   |
+| StepSize                 | value                                                         |
+| AngleCurvature           | value                                                         |
+| SeedingMethod            | "seedsPerVoxel", "globalSeedNumber", "totalStreamlinesNumber" |
+| SeedingNumberMethod      | integer for the number of seeds                               |
+| TerminationCriterion     | "leaveMask", "reachingTissueType”                             |
+| TerminationCriterionTest | "binary","ACT","CMC"                                          |
 
 Example:
 

From 447c63bd8cd49297abae3e0a7894d705df6a7f2c Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Thu, 3 Jan 2019 15:13:17 -0800
Subject: [PATCH 018/191] remove old extensions

---
 src/07-extensions.md | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/src/07-extensions.md b/src/07-extensions.md
index 8a090a43df..e8f3fb6445 100644
--- a/src/07-extensions.md
+++ b/src/07-extensions.md
@@ -33,18 +33,12 @@ Below is a table of currently-active BEPs.
 | :---------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------- |
 | [BEP001](https://docs.google.com/document/d/1QwfHyBzOyFWOLO4u_kkojLpUhW0-4_M7Ubafu9Gf4Gg) | [Structural acquisitions that include multiple contrasts (multi echo, flip angle, inversion time) sequences](https://docs.google.com/document/d/1QwfHyBzOyFWOLO4u_kkojLpUhW0-4_M7Ubafu9Gf4Gg) | Gilles de Hollander                                            |
 | [BEP002](https://docs.google.com/document/d/1bq5eNDHTb6Nkx3WUiOBgKvLNnaa5OMcGtD0AZ9yms2M) | [The BIDS Models Specification](https://docs.google.com/document/d/1bq5eNDHTb6Nkx3WUiOBgKvLNnaa5OMcGtD0AZ9yms2M)                                                                              | Tal Yarkoni                                                    |
-| [BEP003](https://docs.google.com/document/d/1Wwc4A6Mow4ZPPszDIWfCUCRNstn7d_zzaWPcfcHmgI4) | [Common Derivatives](https://docs.google.com/document/d/1Wwc4A6Mow4ZPPszDIWfCUCRNstn7d_zzaWPcfcHmgI4)                                                                                         | Chris Gorgolewski                                              |
 | [BEP004](https://docs.google.com/document/d/1kyw9mGgacNqeMbp4xZet3RnDhcMmf4_BmRgKaOkO2Sc) | [Susceptibility Weighted Imaging (SWI)](https://docs.google.com/document/d/1kyw9mGgacNqeMbp4xZet3RnDhcMmf4_BmRgKaOkO2Sc)                                                                      | Fidel Alfaro Almagro                                           |
 | [BEP005](https://docs.google.com/document/d/15tnn5F10KpgHypaQJNNGiNKsni9035GtDqJzWqkkP6c) | [Arterial Spin Labeling (ASL)](https://docs.google.com/document/d/15tnn5F10KpgHypaQJNNGiNKsni9035GtDqJzWqkkP6c)                                                                               | Henk-Jan Mutsaerts and Michael Chappell                        |
 | [BEP006](https://docs.google.com/document/d/1ArMZ9Y_quTKXC-jNXZksnedK2VHHoKP3HCeO5HPcgLE) | [Electroencephalography (EEG)](https://docs.google.com/document/d/1ArMZ9Y_quTKXC-jNXZksnedK2VHHoKP3HCeO5HPcgLE)                                                                               | Cyril R Pernet, Robert Oostenveld, Stefan Appelhoff            |
 | [BEP009](https://docs.google.com/document/d/1mqMLnxVdLwZjDd4ZiWFqjEAmOmfcModA_R535v3eQs0) | [Positron Emission Tomography (PET)](https://docs.google.com/document/d/1mqMLnxVdLwZjDd4ZiWFqjEAmOmfcModA_R535v3eQs0)                                                                         | Melanie Ganz                                                   |
 | [BEP010](https://docs.google.com/document/d/1qMUkoaXzRMlJuOcfTYNr3fTsrl4SewWjffjMD5Ew6GY) | [intracranial Electroencephalography (iEEG)](https://docs.google.com/document/d/1qMUkoaXzRMlJuOcfTYNr3fTsrl4SewWjffjMD5Ew6GY)                                                                 | Dora Hermes and Chris Holdgraf                                 |
-| [BEP011](https://docs.google.com/document/d/1YG2g4UkEio4t_STIBOqYOwneLEs1emHIXbGKynx7V0Y) | [The structural preprocessing derivatives](https://docs.google.com/document/d/1YG2g4UkEio4t_STIBOqYOwneLEs1emHIXbGKynx7V0Y)                                                                   | Andrew Hoopes                                                  |
-| [BEP012](https://docs.google.com/document/d/16CvBwVMAs0IMhdoKmlmcm3W8254dQmNARo-7HhE-lJU) | [The functional preprocessing derivatives](https://docs.google.com/document/d/16CvBwVMAs0IMhdoKmlmcm3W8254dQmNARo-7HhE-lJU)                                                                   | Camille Maumet and Chris Markiewicz                            |
-| [BEP013](https://docs.google.com/document/d/1qBNQimDx6CuvHjbDvuFyBIrf2WRFUOJ-u50canWjjaw) | [The resting state fMRI derivatives](https://docs.google.com/document/d/1qBNQimDx6CuvHjbDvuFyBIrf2WRFUOJ-u50canWjjaw)                                                                         | Steven Giavasis                                                |
-| [BEP014](https://docs.google.com/document/d/11gCzXOPUbYyuQx8fErtMO9tnOKC3kTWiL9axWkkILNE) | [The affine transformations and nonlinear field warps](https://docs.google.com/document/d/11gCzXOPUbYyuQx8fErtMO9tnOKC3kTWiL9axWkkILNE)                                                       | Oscar Esteban                                                  |
 | [BEP015](https://docs.google.com/document/d/1WYOTXDB7GzlHoWqLjd45I3uGBgPxXddST-NTqBnroJE) | [Mapping file](https://docs.google.com/document/d/1WYOTXDB7GzlHoWqLjd45I3uGBgPxXddST-NTqBnroJE)                                                                                               | Eric Earl, Camille Maumet, and Vasudev Raguram                 |
-| [BEP016](https://docs.google.com/document/d/1cQYBvToU7tUEtWMLMwXUCB_T8gebCotE1OczUpMYW60) | [The diffusion weighted imaging derivatives](https://docs.google.com/document/d/1cQYBvToU7tUEtWMLMwXUCB_T8gebCotE1OczUpMYW60)                                                                 | Franco Pestilli and Oscar Esteban                              |
 | [BEP017](https://docs.google.com/document/d/1ugBdUF6dhElXdj3u9vw0iWjE6f_Bibsro3ah7sRV0GA) | [Generic BIDS connectivity data schema](https://docs.google.com/document/d/1ugBdUF6dhElXdj3u9vw0iWjE6f_Bibsro3ah7sRV0GA)                                                                      | Eugene Duff and Paul McCarthy                                  |
 | [BEP018](https://docs.google.com/document/d/1uRkgyzESLKuGjXi98Z97Wh6vt-iLN5nOAb9TG16CjUs) | [Genetic information](https://docs.google.com/document/d/1uRkgyzESLKuGjXi98Z97Wh6vt-iLN5nOAb9TG16CjUs)                                                                                        | Cyril R Pernet, Clara Moreau, and Thomas Nichols               |
 | [BEP019](https://docs.google.com/document/d/1FqJI791ycXr0bfRg2qyLqAf0RpVttJ2cInOgMWrKsNU) | [DICOM Metadata](https://docs.google.com/document/d/1FqJI791ycXr0bfRg2qyLqAf0RpVttJ2cInOgMWrKsNU)                                                                                             | Satrajit Ghosh                                                 |

From 43017d1a6694f75293093374806cf494002d66bb Mon Sep 17 00:00:00 2001
From: Satrajit Ghosh <satrajit.ghosh@gmail.com>
Date: Thu, 28 Feb 2019 15:36:07 -0800
Subject: [PATCH 019/191] Update src/99-appendices/08-coordinate-systems.md

Co-Authored-By: chrisfilo <krzysztof.gorgolewski@gmail.com>
---
 src/99-appendices/08-coordinate-systems.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/99-appendices/08-coordinate-systems.md b/src/99-appendices/08-coordinate-systems.md
index b7d4395be1..43bcd4d604 100644
--- a/src/99-appendices/08-coordinate-systems.md
+++ b/src/99-appendices/08-coordinate-systems.md
@@ -32,7 +32,7 @@ points of the imaged object's structure (i.e. anatomical landmarks) such as the
 anterior commissure in a brain. They can also be devices that generate a
 localizable signal that are placed in the intended position before scanning
 (i.e. markers). Positions of landmarks are identified via manual or automated
-algorithms that detect these landmarks in (e.g., MR) or from (e.g., MEG) the
+algorithms that detect these fiducials in (e.g., MR) or from (e.g., MEG) the
 acquired data or via explicit encoding of position (e.g., EEG sensors,
 headshape/coil digitization).
 

From df3b737ecec54c1c8406ad3c1b68a14913d7e9f9 Mon Sep 17 00:00:00 2001
From: Satrajit Ghosh <satrajit.ghosh@gmail.com>
Date: Thu, 28 Feb 2019 15:36:22 -0800
Subject: [PATCH 020/191] Update src/99-appendices/08-coordinate-systems.md

Co-Authored-By: chrisfilo <krzysztof.gorgolewski@gmail.com>
---
 src/99-appendices/08-coordinate-systems.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/99-appendices/08-coordinate-systems.md b/src/99-appendices/08-coordinate-systems.md
index 43bcd4d604..4ea201d459 100644
--- a/src/99-appendices/08-coordinate-systems.md
+++ b/src/99-appendices/08-coordinate-systems.md
@@ -29,7 +29,7 @@ time points.
 Landmarks are properties of the object being measured and can exist in any
 coordinate system in which the object is placed/measured. They can be relevant
 points of the imaged object's structure (i.e. anatomical landmarks) such as the
-anterior commissure in a brain. They can also be devices that generate a
+anterior commissure in a brain. They can also be fiducials that generate a
 localizable signal that are placed in the intended position before scanning
 (i.e. markers). Positions of landmarks are identified via manual or automated
 algorithms that detect these fiducials in (e.g., MR) or from (e.g., MEG) the

From af0ff9a318def636da472939b8971f4fe142e287 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Thu, 28 Feb 2019 15:46:56 -0800
Subject: [PATCH 021/191] bring back space

---
 .../02-magnetoencephalography.md              |  2 +-
 .../03-electroencephalography.md              |  2 +-
 .../04-intracranial-electroencephalography.md |  2 +-
 src/05-derivatives/02-common-data-types.md    | 22 +++++++++----------
 .../03-structural-derivatives.md              |  4 ++--
 .../04-functional-derivatives.md              |  4 ++--
 6 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/src/04-modality-specific-files/02-magnetoencephalography.md b/src/04-modality-specific-files/02-magnetoencephalography.md
index 88d67ed680..3fe864fe81 100644
--- a/src/04-modality-specific-files/02-magnetoencephalography.md
+++ b/src/04-modality-specific-files/02-magnetoencephalography.md
@@ -1,6 +1,6 @@
 # Magnetoencephalography (MEG)
 
-Support for MEG was developed as a [BIDS Extension Proposal](../06-extensions.md#bids-extension-proposals).
+Support for MEG was developed as a [BIDS Extension Proposal](../07-extensions.md#bids-extension-proposals).
 Please cite the following paper when referring to this part of the standard in
 context of the academic literature:
 
diff --git a/src/04-modality-specific-files/03-electroencephalography.md b/src/04-modality-specific-files/03-electroencephalography.md
index 6e6029f9e8..7985129c2d 100644
--- a/src/04-modality-specific-files/03-electroencephalography.md
+++ b/src/04-modality-specific-files/03-electroencephalography.md
@@ -1,6 +1,6 @@
 # Electroencephalography (EEG)
 
-Support for EEG was developed as a [BIDS Extension Proposal](../06-extensions.md#bids-extension-proposals).
+Support for EEG was developed as a [BIDS Extension Proposal](../07-extensions.md#bids-extension-proposals).
 Please cite the following paper when referring to this part of the standard in
 context of the academic literature:
 
diff --git a/src/04-modality-specific-files/04-intracranial-electroencephalography.md b/src/04-modality-specific-files/04-intracranial-electroencephalography.md
index 31d8aec2ae..d7763f7b99 100644
--- a/src/04-modality-specific-files/04-intracranial-electroencephalography.md
+++ b/src/04-modality-specific-files/04-intracranial-electroencephalography.md
@@ -1,6 +1,6 @@
 # intracranial Electroencephalography (iEEG)
 
-Support for iEEG was developed as a [BIDS Extension Proposal](../06-extensions.md#bids-extension-proposals).
+Support for iEEG was developed as a [BIDS Extension Proposal](../07-extensions.md#bids-extension-proposals).
 Please cite the following paper when referring to this part of the standard in
 context of the academic literature:
 
diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index 26ade07bd8..b1e2c20594 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>/
         func|anat|dwi/
-        <source_keywords>[_referencemap-<referencemap>][_desc-<label>]_<suffix>.<ext>
+        <source_keywords>[_space-<space>][_desc-<label>]_<suffix>.<ext>
 ```
 
 Processing in this context means transformations of data that does not change
@@ -22,11 +22,11 @@ data types in the specification. Examples:
 
 -   Motion-corrected DWI files.
 
-The `referencemap` keyword denotes reference atlas or map that the File is
+The `space` keyword denotes reference atlas or map that the File is
 aligned to - see [Introduction](01-introduction.md) for allowed values. The
 `desc` keyword is a general purpose field with freeform values. To distinguish
 between multiple different versions of processing for the same input data the
-`desc` keyword should be used. Note that even though `referencemap` and `desc`
+`desc` keyword should be used. 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.
 
@@ -36,8 +36,8 @@ Examples:
 pipeline1/
     sub-001/
         func/
-            sub-001_task-rest_run-1_referencemap-MNI305_bold.nii.gz
-            sub-001_task-rest_run-1_referencemap-MNI305_bold.json
+            sub-001_task-rest_run-space-MNI305_bold.nii.gz
+            sub-001_task-rest_run-space-MNI305_bold.json
 ```
 
 ```Text
@@ -74,12 +74,12 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         func|anat|dwi/
-        <source_keywords>[_referencemap-<referencemap>][_type-<type>][_desc-<label>]_mask.nii.gz
+        <source_keywords>[_space-<space>][_type-<type>][_desc-<label>]_mask.nii.gz
 ```
 
-A binary (1 - inside, 0 outside) mask in the space defined by `<referencemap>`.
+A binary (1 - inside, 0 outside) mask in the space defined by `<space>`.
 By default (i.e., if no transformation has taken place) the value of
-`referencemap` should be set to `orig`.
+`space` should be set to `orig`.
 
 JSON metadata fields:
 
@@ -127,7 +127,7 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         func|anat|dwi/
-            <source_keywords>[_referencemap-<referencemap>space-<space>]_dseg.nii.gz
+            <source_keywords>[_space-<space>]_dseg.nii.gz
 ```
 
 Example:
@@ -166,7 +166,7 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         func|anat|dwi/
-            <source_keywords>[_referencemap-<referencemap>space-<space>][_label-<label>]_probseg.nii.gz
+            <source_keywords>[space-<space>][_label-<label>]_probseg.nii.gz
 ```
 
 Example:
@@ -218,7 +218,7 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         anat/
-            <source_keywords>[_hemi-{L|R}][_referencemap-<referencemap>]_dseg.{label.gii|dlabel.nii}
+            <source_keywords>[_hemi-{L|R}][_space-<space>]_dseg.{label.gii|dlabel.nii}
 ```
 
 The REQUIRED extension for GIFTI parcellations is `.label.gii`. The hemi tag is
diff --git a/src/05-derivatives/03-structural-derivatives.md b/src/05-derivatives/03-structural-derivatives.md
index a2f3d14def..b0631c095f 100644
--- a/src/05-derivatives/03-structural-derivatives.md
+++ b/src/05-derivatives/03-structural-derivatives.md
@@ -11,7 +11,7 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         anat/
-            <source_keywords>_hemi-{L|R}[_referencemap-<referencemap]_<surftype>.surf.gii
+            <source_keywords>_hemi-{L|R}[_space-<space]_<surftype>.surf.gii
 ```
 
 Example:
@@ -50,7 +50,7 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         anat/
-            <source_keywords>[_hemi-{L|R}][_referencemap-<referencemap>space-<space>]_<suffix>.{shape.gii|dscalar.nii}
+            <source_keywords>[_hemi-{L|R}][_space-<space>]_<suffix>.{shape.gii|dscalar.nii}
 ```
 
 The REQUIRED extension for scalar GiFTI files is `.shape.gii`. The `hemi` key is
diff --git a/src/05-derivatives/04-functional-derivatives.md b/src/05-derivatives/04-functional-derivatives.md
index 663f2decab..63045a8663 100644
--- a/src/05-derivatives/04-functional-derivatives.md
+++ b/src/05-derivatives/04-functional-derivatives.md
@@ -8,8 +8,8 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         func/
-            <source_keywords>[_referencemap-<referencemap>][_desc-<label>]_<suffix>.nii[.gz]
-            <source_keywords>[_referencemap-<referencemap>][_desc-<label>]_<suffix>.json
+            <source_keywords>[_space-<space>][_desc-<label>]_<suffix>.nii[.gz]
+            <source_keywords>[_space-<space>][_desc-<label>]_<suffix>.json
 ```
 
 for example:

From 140868bf61ff16deb3a6ed3591d3b523dbd09a19 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Mon, 4 Mar 2019 09:25:45 -0800
Subject: [PATCH 022/191] Update src/05-derivatives/01-introduction.md

Co-Authored-By: chrisfilo <krzysztof.gorgolewski@gmail.com>
---
 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 04276d1f24..a471e2b620 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -97,7 +97,7 @@ share the following (non-required) ones:
 
 | **Key name**         | **Description**                                                                                                                                                                                                                                                                                                                                       |
 | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Description          | RECOMMENDED. Freeform natural language description of the nature of the file.                                                                                                                                                                                                                                                                         |
+| 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.                                                                                                                                                                                                               |
 | CoordinateSystem     | REQUIRED if no implicit coordinate system. Key indicates the coordinate system associated with the File. The coordinate system can be implicit to the File, for instance when data are images stored in NIfTI format. Can be a list. See Table below for list of allowed systems.                                                                     |

From df9fee66f1d9b6b8cadb34cd55f4a48bab5180a0 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Mon, 4 Mar 2019 09:26:18 -0800
Subject: [PATCH 023/191] Update src/05-derivatives/01-introduction.md

Co-Authored-By: chrisfilo <krzysztof.gorgolewski@gmail.com>
---
 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 a471e2b620..6cf7268383 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -99,7 +99,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.                                                                                                                                                                                                               |
+| 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.                                                                                                                                                                                                               |
 | CoordinateSystem     | REQUIRED if no implicit coordinate system. Key indicates the coordinate system associated with the File. The coordinate system can be implicit to the File, for instance when data are images stored in NIfTI format. Can be a list. See Table below for list of allowed systems.                                                                     |
 | ReferenceMap         | REQUIRED when coordinate system is Aligned. Key indicates the reference atlas or map that the File is aligned to. See table below for list of common spaces.                                                                                                                                                                                          |
 | NonstandardReference | REQUIRED when a non standard template or space is used. (e.g., a custom template in MNI305 space). 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. If Space is a list, Space reference must also be a list.                                                                |

From 8dc0d1bc19f635c7ea493942671e20f59ab68464 Mon Sep 17 00:00:00 2001
From: Yaroslav Halchenko <debian@onerussian.com>
Date: Mon, 4 Mar 2019 09:26:47 -0800
Subject: [PATCH 024/191] Update src/05-derivatives/02-common-data-types.md

Co-Authored-By: chrisfilo <krzysztof.gorgolewski@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 b1e2c20594..adfa1f963d 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -37,7 +37,7 @@ pipeline1/
     sub-001/
         func/
             sub-001_task-rest_run-space-MNI305_bold.nii.gz
-            sub-001_task-rest_run-space-MNI305_bold.json
+            sub-001_task-rest_run-1_space-MNI305_bold.json
 ```
 
 ```Text

From 8182a8b5dc33bc245583eb73c4aea6eade455ab4 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Mon, 4 Mar 2019 09:27:10 -0800
Subject: [PATCH 025/191] Update src/99-appendices/08-coordinate-systems.md

Co-Authored-By: chrisfilo <krzysztof.gorgolewski@gmail.com>
---
 src/99-appendices/08-coordinate-systems.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/99-appendices/08-coordinate-systems.md b/src/99-appendices/08-coordinate-systems.md
index 4ea201d459..79d37e980b 100644
--- a/src/99-appendices/08-coordinate-systems.md
+++ b/src/99-appendices/08-coordinate-systems.md
@@ -15,7 +15,7 @@ dimension, and in some cases the details of origin (for example, time).
 
 ### Space, atlas and map
 
-A space|atlas|map is embedded in a coordinate system to ascribe meaning to the
+A space/atlas/map is embedded in a coordinate system to ascribe meaning to the
 coordinates. For instance, Scanner, Talairach88, MNI, FS are different
 coordinate systems, while the Talairach atlas, MNI152, and fsaverage ascribe
 meaning to the coordinates in terms of brain anatomy. As an example to

From a51949961ae421360e393312b538fa2d8c3fb5b8 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Mon, 4 Mar 2019 09:27:38 -0800
Subject: [PATCH 026/191] Update src/05-derivatives/02-common-data-types.md

Co-Authored-By: chrisfilo <krzysztof.gorgolewski@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 adfa1f963d..7d5dcde63b 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -77,7 +77,7 @@ Template:
         <source_keywords>[_space-<space>][_type-<type>][_desc-<label>]_mask.nii.gz
 ```
 
-A binary (1 - inside, 0 outside) mask in the space defined by `<space>`.
+A binary (1 - inside, 0 - outside) mask in the space defined by `<space>`.
 By default (i.e., if no transformation has taken place) the value of
 `space` should be set to `orig`.
 

From a97a5ad9ac69c5421a242cda71fa0b8a5aee7dd3 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Mon, 4 Mar 2019 09:28:31 -0800
Subject: [PATCH 027/191] Update src/05-derivatives/02-common-data-types.md

Co-Authored-By: chrisfilo <krzysztof.gorgolewski@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 7d5dcde63b..ddf96ed539 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -285,7 +285,7 @@ Example:
 
 ```Text
 pipeline/
-	dseg.tsv
+	  dseg.tsv
     sub-001/
         anat/
             sub-001_space-ACPC_dseg.nii.gz

From 2c41d50966d9fd9cd22da67ed88e11c102d4380a Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Mon, 4 Mar 2019 09:29:04 -0800
Subject: [PATCH 028/191] Update
 src/05-derivatives/03-structural-derivatives.md

Co-Authored-By: chrisfilo <krzysztof.gorgolewski@gmail.com>
---
 src/05-derivatives/03-structural-derivatives.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/05-derivatives/03-structural-derivatives.md b/src/05-derivatives/03-structural-derivatives.md
index b0631c095f..a7234962b1 100644
--- a/src/05-derivatives/03-structural-derivatives.md
+++ b/src/05-derivatives/03-structural-derivatives.md
@@ -29,7 +29,7 @@ The supported surface types (`<surftype>` suffix) are:
 | Surface type | Description                                                          |
 | ------------ | -------------------------------------------------------------------- |
 | wm           | The gray matter / white matter border for the cortex                 |
-| smoothwm     | The smoothed matter / white matter border                            |
+| smoothwm     | The smoothed gray matter / white matter border                       |
 | pial         | The gray matter / pial matter border                                 |
 | midthickness | The midpoints between wm and pial surfaces                           |
 | inflated     | An inflation of the midthickness surface (useful for visualization)  |

From cf3e9904f0511c67b24b433386f90286b2041b73 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Mon, 4 Mar 2019 09:29:30 -0800
Subject: [PATCH 029/191] Update
 src/05-derivatives/03-structural-derivatives.md

Co-Authored-By: chrisfilo <krzysztof.gorgolewski@gmail.com>
---
 src/05-derivatives/03-structural-derivatives.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/05-derivatives/03-structural-derivatives.md b/src/05-derivatives/03-structural-derivatives.md
index a7234962b1..211adddfc6 100644
--- a/src/05-derivatives/03-structural-derivatives.md
+++ b/src/05-derivatives/03-structural-derivatives.md
@@ -53,7 +53,7 @@ Template:
             <source_keywords>[_hemi-{L|R}][_space-<space>]_<suffix>.{shape.gii|dscalar.nii}
 ```
 
-The REQUIRED extension for scalar GiFTI files is `.shape.gii`. The `hemi` key is
+The REQUIRED extension for scalar GIFTI files is `.shape.gii`. The `hemi` key is
 required for GiFTI files. For example:
 
 ```Text

From 7351e2ae3df28ebdf99b26a5d3b7b2a192901228 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Mon, 4 Mar 2019 09:29:54 -0800
Subject: [PATCH 030/191] Update
 src/05-derivatives/03-structural-derivatives.md

Co-Authored-By: chrisfilo <krzysztof.gorgolewski@gmail.com>
---
 src/05-derivatives/03-structural-derivatives.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/05-derivatives/03-structural-derivatives.md b/src/05-derivatives/03-structural-derivatives.md
index 211adddfc6..a9d1e5c351 100644
--- a/src/05-derivatives/03-structural-derivatives.md
+++ b/src/05-derivatives/03-structural-derivatives.md
@@ -54,7 +54,7 @@ Template:
 ```
 
 The REQUIRED extension for scalar GIFTI files is `.shape.gii`. The `hemi` key is
-required for GiFTI files. For example:
+required for GIFTI files. For example:
 
 ```Text
 pipeline/

From b941c3c242fb2ad44303ec44d885d69ffe979eb4 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Mon, 4 Mar 2019 09:33:53 -0800
Subject: [PATCH 031/191] fix formatting

---
 src/01-introduction.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/01-introduction.md b/src/01-introduction.md
index 9c9194a83c..0621fc01c4 100644
--- a/src/01-introduction.md
+++ b/src/01-introduction.md
@@ -47,8 +47,7 @@ different backgrounds.
 The BIDS specification can be extended in a backwards compatible way and will
 evolve over time. This is accomplished through community-driven BIDS Extention
 Proposals (BEPs). For more information about the BEP process, and list of
-current BEP proposals, see
-[Extending the BIDS specification](07-extensions.md).
+current BEP proposals, see [Extending the BIDS specification](07-extensions.md).
 
 ## Citing BIDS
 

From eec7a3e15b403ccbbcff0bc840fdff51078e70a3 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Mon, 4 Mar 2019 13:36:14 -0800
Subject: [PATCH 032/191] added a rule concerning pipline_name consistency

---
 src/05-derivatives/01-introduction.md | 125 +++++++++++++-------------
 1 file changed, 63 insertions(+), 62 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 6cf7268383..08eef325cf 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -13,15 +13,17 @@ Derivatives can be stored/distributed in two ways:
 1.  Under a `derivatives/` subfolder in the root of the source BIDS dataset
     folder to make a clear distinction between raw data and results of data
     processing. Each pipeline has a dedicated directory under which it stores
-    all of its outputs. There is no restriction on the directory name; however,
-    it is RECOMMENDED to use the format `<pipeline>-<variant>` in cases where it
-    is anticipated that the same pipeline will output more than one variant
-    (e.g., `AFNI-blurring`, `AFNI-noblurring`, etc.).
+    all of its outputs. There are few restriction on the directory name; it is
+    RECOMMENDED to use the format `<pipeline>-<variant>` in cases where it is
+    anticipated that the same pipeline will output more than one variant (e.g.,
+    `AFNI-blurring`, `AFNI-noblurring`, etc.). For the sake of consistency, the
+    subfolder name needs to be a substring of `PipelineDescription.Name` field
+    in the `dataset_description.json` (see below).
 
     For example:
 
     ```Text
-    <dataset>/derivatives/fmripreprocess_01/sub-0001
+    <dataset>/derivatives/fmripreprocess-v1/sub-0001
     <dataset>/derivatives/spm/sub-0001
     <dataset>/derivatives/vbm/sub-0001
     ```
@@ -56,14 +58,14 @@ In addition to raw BIDS datasets derived BIDS datasets includ the following
 required or recommended `dataset_description.json` keys (a dot in the Key name
 denotes a key in a subdictionary):
 
-| **Key name**                                | **Description**                                                                                                                                                       |
-| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| PipelineDescription.Name                    | REQUIRED. Name of the pipeline that generated the outputs.                                                                                                            |
-| PipelineDescription.Version                 | OPTIONAL. Version of the pipeline.                                                                                                                                    |
-| PipelineDescription.CodeURL                 | OPTIONAL. URL where the code for the analysis can be found.                                                                                                           |
-| PipelineDescription.DockerHubContainerTag   | OPTIONAL. Docker Hub tag where the software container image used in this analysis can be found.                                                                       |
-| PipelineDescription.SingularityContainerURL | OPTIONAL. URL where the Singularity software container image used in this analysis can be found.                                                                      |
-| 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`. |
+| **Key name**                                | **Description**                                                                                                                                                                                                                              |
+| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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.DockerHubContainerTag   | OPTIONAL. Docker Hub tag where the software container image used in this analysis can be found.                                                                                                                                              |
+| PipelineDescription.SingularityContainerURL | OPTIONAL. URL where the Singularity software container image used in this analysis can be found.                                                                                                                                             |
+| 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:
 
@@ -97,9 +99,9 @@ share the following (non-required) ones:
 
 | **Key name**         | **Description**                                                                                                                                                                                                                                                                                                                                       |
 | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Description          | RECOMMENDED. Free-form natural language description of the nature of the file.                                                                                                                                                                                                                                                                         |
+| 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.                                                                                                                                                                                                               |
+| 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.                                                                                                                                                                                                                |
 | CoordinateSystem     | REQUIRED if no implicit coordinate system. Key indicates the coordinate system associated with the File. The coordinate system can be implicit to the File, for instance when data are images stored in NIfTI format. Can be a list. See Table below for list of allowed systems.                                                                     |
 | ReferenceMap         | REQUIRED when coordinate system is Aligned. Key indicates the reference atlas or map that the File is aligned to. See table below for list of common spaces.                                                                                                                                                                                          |
 | NonstandardReference | REQUIRED when a non standard template or space is used. (e.g., a custom template in MNI305 space). 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. If Space is a list, Space reference must also be a list.                                                                |
@@ -127,8 +129,8 @@ In addition to values defined in
 ### Example sidecar files
 
 For a NIFTI file (Single coordinate system), one could have registered the File
-on to the standard MNI305 template. The way to write the metadata of such 
-File is:
+on to the standard MNI305 template. The way to write the metadata of such File
+is:
 
 ```JSON
 {
@@ -137,7 +139,7 @@ File is:
 }
 ```
 
-However, it could also be the case that a nonstandard derivative of MNI305 was 
+However, it could also be the case that a nonstandard derivative of MNI305 was
 used as standard space for the File. That can be written as follows:
 
 ```JSON
@@ -147,72 +149,71 @@ used as standard space for the File. That can be written as follows:
 }
 ```
 
-Some derivatives such as CIFTI Files allow for multiple coordinate systems. 
-Such possibility is enabled by using lists of spaces and references:
+Some derivatives such as CIFTI Files allow for multiple coordinate systems. Such
+possibility is enabled by using lists of spaces and references:
 
 ```JSON
 {
     "TransformFile": "/path/to/xfm",
-    "ReferenceMap": ["MNI305", "fsLR32k"] 
+    "ReferenceMap": ["MNI305", "fsLR32k"]
 }
 ```
 
-Differing references of the same spaces with respect to the above example can 
-be expressed as follows:
+Differing references of the same spaces with respect to the above example can be
+expressed as follows:
 
 ```JSON
 {
     "TransformFile": "/path/to/xfm",
-    "ReferenceMap": ["MNI152Lin", "fsLR164k"] 
+    "ReferenceMap": ["MNI152Lin", "fsLR164k"]
 }
 ```
 
 ## Metadata conventions
 
--   Unless specified otherwise, individual sidecar JSON files and all metadata 
-    fields within are optional. However, the appropriate use of these files and 
-    pertinent fields is very valuable and thus encouraged. Moreover, for some 
-    types of files, there may be one or more required metadata fields, in which 
-    case at least one metadata file containing that field must be located 
+-   Unless specified otherwise, individual sidecar JSON files and all metadata
+    fields within are optional. However, the appropriate use of these files and
+    pertinent fields is very valuable and thus encouraged. Moreover, for some
+    types of files, there may be one or more required metadata fields, in which
+    case at least one metadata file containing that field must be located
     somewhere within the file’s hierarchy (per the Inheritance Principle).
 
--   When chaining derivative pipelines, any JSON fields that were specified as 
-    mandatory in the input files should be propagated forward in the output 
-    file’s JSON provided they remain valid. Non-required JSON fields can be 
-    propagated, and are highly useful, but it is the pipeline’s responsibility 
-    to ensure that the values are still relevant and appropriate to the type of 
+-   When chaining derivative pipelines, any JSON fields that were specified as
+    mandatory in the input files should be propagated forward in the output
+    file’s JSON provided they remain valid. Non-required JSON fields can be
+    propagated, and are highly useful, but it is the pipeline’s responsibility
+    to ensure that the values are still relevant and appropriate to the type of
     output data.
 
 ## File naming conventions
 
--   Filenames that are permissible for a raw BIDS data type have a privileged 
-    status. Any modification of raw files must use a modified filename that 
-    does not conflict with the raw filename. Further, any files created as 
-    part of a derivatived dataset must not match a permissible filename of a 
-    valid raw dataset. Stated equivalently, if any filename in a derivatived 
-    dataset has a name permissible for a raw BIDS data, then that file must 
-    be an identical copy of that raw file.
+-   Filenames that are permissible for a raw BIDS data type have a privileged
+    status. Any modification of raw files must use a modified filename that does
+    not conflict with the raw filename. Further, any files created as part of a
+    derivatived dataset must not match a permissible filename of a valid raw
+    dataset. Stated equivalently, if any filename in a derivatived dataset has a
+    name permissible for a raw BIDS data, then that file must be an identical
+    copy of that raw file.
 
--   Each Derivatives filename MUST be of the form: 
+-   Each Derivatives filename MUST be of the form:
     `<source_keywords>[_keyword-<value>]_<suffix>.<ext>`
 
--   When the derivatives chain involves outputs derived from a single raw 
-    input, `source_keywords` MUST be the entire source filename, with the 
-    ommission of the source suffix and extension. One exception to this rule 
-    is filename keywords that are no longer relevant (such as `sub-` in the 
-    case of group level derivatives). Depending on the nature of the 
-    derivative file, the suffix can either be the same as the source file if 
-    that suffix is still appropriate, or a new appropriate value selected 
-    from the controlled list. 
-
--   There is no prohibition against identical filenames in different derived 
-    datasets, although users should be aware of the potential ambiguity this 
-    can create and use the sidecar JSON files to detail the specifics of 
-    individual files.
-
--   When necessary to distinguish two files, the `_desc-<value>` keyword-value 
-    should be used. This includes the cases of needing to distinguish both 
-    differing inputs and differing outputs (e.g., `_desc-T1w` and `_desc-T2w` 
-    to distinguish brain mask files derived from T1w and T2w images; or 
-    `_desc-sm4` and `_desc-sm8` to distinguish between outputs generated with 
-     two different levels of smoothing).
+-   When the derivatives chain involves outputs derived from a single raw input,
+    `source_keywords` MUST be the entire source filename, with the ommission of
+    the source suffix and extension. One exception to this rule is filename
+    keywords that are no longer relevant (such as `sub-` in the case of group
+    level derivatives). Depending on the nature of the derivative file, the
+    suffix can either be the same as the source file if that suffix is still
+    appropriate, or a new appropriate value selected from the controlled list.
+
+-   There is no prohibition against identical filenames in different derived
+    datasets, although users should be aware of the potential ambiguity this can
+    create and use the sidecar JSON files to detail the specifics of individual
+    files.
+
+-   When necessary to distinguish two files, the `_desc-<value>` keyword-value
+    should be used. This includes the cases of needing to distinguish both
+    differing inputs and differing outputs (e.g., `_desc-T1w` and `_desc-T2w` to
+    distinguish brain mask files derived from T1w and T2w images; or `_desc-sm4`
+    and `_desc-sm8` to distinguish between outputs generated with two different
+    levels of smoothing).

From efd1cf0daf8deefbdf2d4ec35ab086808bfe45a0 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Mon, 4 Mar 2019 13:45:02 -0800
Subject: [PATCH 033/191] fix spaces

---
 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 ddf96ed539..fbaa477133 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -285,7 +285,7 @@ Example:
 
 ```Text
 pipeline/
-	  dseg.tsv
+    dseg.tsv
     sub-001/
         anat/
             sub-001_space-ACPC_dseg.nii.gz

From e0f82dad3c86c11aef356724777128fceed7d174 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Mon, 4 Mar 2019 13:57:18 -0800
Subject: [PATCH 034/191] get rid of derivatived

---
 src/05-derivatives/01-introduction.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 08eef325cf..83c10b0c5c 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -190,8 +190,8 @@ expressed as follows:
 -   Filenames that are permissible for a raw BIDS data type have a privileged
     status. Any modification of raw files must use a modified filename that does
     not conflict with the raw filename. Further, any files created as part of a
-    derivatived dataset must not match a permissible filename of a valid raw
-    dataset. Stated equivalently, if any filename in a derivatived dataset has a
+    derivative dataset must not match a permissible filename of a valid raw
+    dataset. Stated equivalently, if any filename in a derivative dataset has a
     name permissible for a raw BIDS data, then that file must be an identical
     copy of that raw file.
 

From be7f54759f4402073a630de61ce8a3be934753c6 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Mon, 4 Mar 2019 16:13:50 -0800
Subject: [PATCH 035/191] add mention of source data in stanalone derivatives
 datasets

---
 src/05-derivatives/01-introduction.md | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 83c10b0c5c..ec76f43c0e 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -32,7 +32,11 @@ Derivatives can be stored/distributed in two ways:
     dataset. This way of specifying derivatives is particularly useful when the
     source dataset is provided with read-only access, and for publishing
     derivatives as independent bodies of work, or for describing derivatives
-    that were created from more than one source dataset.
+    that were created from more than one source dataset. It is consistent with 
+    BIDS principles for the `sourcedata/` subdirectory to be used to include or 
+    reference the source dataset(s) as it existed when the derivatives were 
+    generated. Likewise, any code used to generate the derivatives from the 
+    source data may be included in the `code/` subdirectory.
 
 The rest of the Derivatives specification assumes Case 1, but Case 2 applies
 after removing `/derivatives/<pipeline_name>` from template names. In both cases

From c6fc93f2c947a3f5c0bbae4815f2852f478b0395 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Mon, 4 Mar 2019 16:19:54 -0800
Subject: [PATCH 036/191] fix label T1w example

---
 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 fbaa477133..3225628f39 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -102,8 +102,8 @@ func_loc/
 manual_masks/
     sub-001/
         anat/
-            sub-001_T1w_label-desc_mask.nii.gz
-            sub-001_T1w_label-desc_mask.json
+            sub-001_desc-tumor_mask.nii.gz
+            sub-001_desc-tumor_mask.json
 ```
 
 ## Segmentations and parcellations

From 0c52a0d75337ad580e3c0c16b56b4cfb65837355 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Mon, 4 Mar 2019 16:25:31 -0800
Subject: [PATCH 037/191] fix missing bracket

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

diff --git a/src/05-derivatives/03-structural-derivatives.md b/src/05-derivatives/03-structural-derivatives.md
index a9d1e5c351..a9f85dc47d 100644
--- a/src/05-derivatives/03-structural-derivatives.md
+++ b/src/05-derivatives/03-structural-derivatives.md
@@ -11,7 +11,7 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         anat/
-            <source_keywords>_hemi-{L|R}[_space-<space]_<surftype>.surf.gii
+            <source_keywords>_hemi-{L|R}[_space-<space>]_<surftype>.surf.gii
 ```
 
 Example:

From a75283d6fec289a26fb4c5e9ec2e6e517cba50e5 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Mon, 4 Mar 2019 16:27:55 -0800
Subject: [PATCH 038/191] add missing 'w' in T2w

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

diff --git a/src/05-derivatives/03-structural-derivatives.md b/src/05-derivatives/03-structural-derivatives.md
index a9f85dc47d..a13f2d3766 100644
--- a/src/05-derivatives/03-structural-derivatives.md
+++ b/src/05-derivatives/03-structural-derivatives.md
@@ -85,7 +85,7 @@ following values should be reserved for their common use-cases:
 | `dist`       | Distance from a point                                 |
 | `defects`    | Marked regions with surface defects                   |
 | `sulc`       | Sulcal depth                                          |
-| `myelinmap`  | Myelin map calculated from T1w to T2 ratio            |
+| `myelinmap`  | Myelin map calculated from T1w to T2w ratio           |
 | `distortion` | Distortion map calculated from a surface registration |
 
 ## Morphometrics

From 672585c6d679b3e253d03f08f8dd44e886fa1d37 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Mon, 4 Mar 2019 16:29:45 -0800
Subject: [PATCH 039/191] Limit number of allowed suffixes for scalar
 derivatives

---
 src/05-derivatives/03-structural-derivatives.md | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/src/05-derivatives/03-structural-derivatives.md b/src/05-derivatives/03-structural-derivatives.md
index a13f2d3766..534942984e 100644
--- a/src/05-derivatives/03-structural-derivatives.md
+++ b/src/05-derivatives/03-structural-derivatives.md
@@ -26,7 +26,7 @@ pipeline/
 
 The supported surface types (`<surftype>` suffix) are:
 
-| Surface type | Description                                                          |
+| `<surftype>` | Description                                                          |
 | ------------ | -------------------------------------------------------------------- |
 | wm           | The gray matter / white matter border for the cortex                 |
 | smoothwm     | The smoothed gray matter / white matter border                       |
@@ -73,11 +73,9 @@ pipeline/
             sub-001_curv.dscalar.nii
 ```
 
-The file `<suffix>` should concisely describe the parameter that is represented
-in the overlay, and while the suffix can be individually customized, the
-following values should be reserved for their common use-cases:
+The file `<suffix>` MUST be one of the following values:
 
-| Suffix       | Description                                           |
+| `<suffix>`   | Description                                           |
 | ------------ | ----------------------------------------------------- |
 | `curv`       | Cortical surface curvature indices                    |
 | `thickness`  | Cortical thickness                                    |

From f549b42814eeff9594fb8a1d478580aa9d891d81 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Mon, 4 Mar 2019 17:11:38 -0800
Subject: [PATCH 040/191] Update src/99-appendices/08-coordinate-systems.md

Co-Authored-By: chrisfilo <krzysztof.gorgolewski@gmail.com>
---
 src/99-appendices/08-coordinate-systems.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/99-appendices/08-coordinate-systems.md b/src/99-appendices/08-coordinate-systems.md
index 79d37e980b..000a2d7f87 100644
--- a/src/99-appendices/08-coordinate-systems.md
+++ b/src/99-appendices/08-coordinate-systems.md
@@ -173,7 +173,7 @@ the units are assumed to be mm.
 | IXI549Space                                         | Reference space defined by the average of the "549 (...) subjects from the IXI dataset" linearly transformed to ICBM MNI 452.Used by SPM12. [http://www.brain-development.org/](http://www.brain-development.org/)                                                                                                                                               |
 | fsnative                                            | Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image                                                                                                                                                                                                                                                                         |
 | fsaverage\[3&#124;4&#124;5&#124;6&#124;sym\]        | Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image, and registered to an fsaverage template                                                                                                                                                                                                                                |
-| fsLR[164k                                           | 32k]                                                                                                                                                                                                                                                                                                                                                             | Images were sampled to the 164k or 32k fsaverage_LR surface reconstructed from the T1w image (high resolution space of the HCPPipelines) |
+| fsLR\[164k&#124;32k\]                                      | Images were sampled to the 164k or 32k fsaverage_LR surface reconstructed from the T1w image (high resolution space of the HCPPipelines) |
 | UNCInfant\[0&#124;1&#124;2\]V\[21&#124;22&#124;23\] | Infant Brain Atlases from Neonates to 1- and 2-year-olds. [https://www.nitrc.org/projects/pediatricatlas](https://www.nitrc.org/projects/pediatricatlas)                                                                                                                                                                                                         |
 
 ---

From e2c3d3936585359c79b329beb4c5f9f298ea540c Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Mon, 4 Mar 2019 17:14:56 -0800
Subject: [PATCH 041/191] adding CODEOWNERS

---
 CODEOWNERS | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/CODEOWNERS b/CODEOWNERS
index 39a7964049..6d474c98c4 100644
--- a/CODEOWNERS
+++ b/CODEOWNERS
@@ -12,3 +12,6 @@
 /src/01-common-principles.md @chrisfilo
 /src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md @chrisfilo
 /src/04-modality-specific-files/03-electroencephalography.md @sappelhoff
+/src/05-derivatives/03-structural-derivatives.md @edickie @ahoopes
+/src/05-derivatives/04-functional-derivatives.md @effigies
+/src/05-derivatives/05-diffusion-derivatives.md @francopestilli @oesteban
\ No newline at end of file

From 6864ba90574b561710c4f41288f18347c70593da Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Mon, 4 Mar 2019 17:17:10 -0800
Subject: [PATCH 042/191] adding missing end line

---
 CODEOWNERS | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CODEOWNERS b/CODEOWNERS
index 6d474c98c4..78c346386d 100644
--- a/CODEOWNERS
+++ b/CODEOWNERS
@@ -14,4 +14,4 @@
 /src/04-modality-specific-files/03-electroencephalography.md @sappelhoff
 /src/05-derivatives/03-structural-derivatives.md @edickie @ahoopes
 /src/05-derivatives/04-functional-derivatives.md @effigies
-/src/05-derivatives/05-diffusion-derivatives.md @francopestilli @oesteban
\ No newline at end of file
+/src/05-derivatives/05-diffusion-derivatives.md @francopestilli @oesteban

From 374a85dc1b2964221946a67f256053e4c045eddb Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Mon, 4 Mar 2019 17:19:29 -0800
Subject: [PATCH 043/191] fix syntax

---
 src/99-appendices/08-coordinate-systems.md | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/src/99-appendices/08-coordinate-systems.md b/src/99-appendices/08-coordinate-systems.md
index 000a2d7f87..5cc16b1024 100644
--- a/src/99-appendices/08-coordinate-systems.md
+++ b/src/99-appendices/08-coordinate-systems.md
@@ -88,9 +88,9 @@ information (origin, orientation) are specified in `XXXCoordinateSystem`, and
 the units are specified in `XXXCoordinateSystemUnits`.
 
 Allowed values for the `XXXCoordinateSystem` field come from a list of
-restricted keywords, as listed in the sections below. If no value from the
-list of restricted keywords fits, there is always the option to specify the
-value as follows:
+restricted keywords, as listed in the sections below. If no value from the list
+of restricted keywords fits, there is always the option to specify the value as
+follows:
 
 -   `Other`: Use this for other coordinate systems and specify further details
     in the `XXXCoordinateSystemDescription` field
@@ -126,7 +126,8 @@ Restricted keywords for the `XXXCoordinateSystem` field in the
 Note that the short descriptions above do not capture all details, There are
 detailed extensive descriptions of these EEG coordinate systems on the
 [FieldTrip toolbox web page](http://www.fieldtriptoolbox.org/faq/how_are_the_different_head_and_mri_coordinate_systems_defined)
-and on the [BESA wiki](http://wiki.besa.de/index.php?title=Electrodes_and_Surface_Locations#Coordinate_systems).
+and on the
+[BESA wiki](http://wiki.besa.de/index.php?title=Electrodes_and_Surface_Locations#Coordinate_systems).
 
 ## iEEG Specific Coordinate Systems
 
@@ -145,8 +146,9 @@ Restricted keywords for the `XXXCoordinateSystem` field in the
     positive z-axis is passing through a mid-hemispheric point in the superior
     direction. The anatomical landmarks are determined in the individual's
     anatomical scan and no scaling or deformations have been applied to the
-    individual's anatomical scan. For more information, see the [ACPC site](http://www.fieldtriptoolbox.org/faq/acpc/)
-    on the FieldTrip toolbox wiki.
+    individual's anatomical scan. For more information, see the
+    [ACPC site](http://www.fieldtriptoolbox.org/faq/acpc/) on the FieldTrip
+    toolbox wiki.
 
 ## Template Based Coordinate Systems
 
@@ -173,7 +175,7 @@ the units are assumed to be mm.
 | IXI549Space                                         | Reference space defined by the average of the "549 (...) subjects from the IXI dataset" linearly transformed to ICBM MNI 452.Used by SPM12. [http://www.brain-development.org/](http://www.brain-development.org/)                                                                                                                                               |
 | fsnative                                            | Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image                                                                                                                                                                                                                                                                         |
 | fsaverage\[3&#124;4&#124;5&#124;6&#124;sym\]        | Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image, and registered to an fsaverage template                                                                                                                                                                                                                                |
-| fsLR\[164k&#124;32k\]                                      | Images were sampled to the 164k or 32k fsaverage_LR surface reconstructed from the T1w image (high resolution space of the HCPPipelines) |
+| fsLR\[164k&#124;32k\]                               | Images were sampled to the 164k or 32k fsaverage_LR surface reconstructed from the T1w image (high resolution space of the HCPPipelines)                                                                                                                                                                                                                         |
 | UNCInfant\[0&#124;1&#124;2\]V\[21&#124;22&#124;23\] | Infant Brain Atlases from Neonates to 1- and 2-year-olds. [https://www.nitrc.org/projects/pediatricatlas](https://www.nitrc.org/projects/pediatricatlas)                                                                                                                                                                                                         |
 
 ---

From 0c1d4a84bcbf4fc9d9d846c687f3cf90da4f57ca Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Tue, 5 Mar 2019 08:37:32 -0800
Subject: [PATCH 044/191] removing group

---
 src/05-derivatives/01-introduction.md | 12 ++++--------
 1 file changed, 4 insertions(+), 8 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index ec76f43c0e..adaa7f1149 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -48,10 +48,6 @@ housed within each subject’s directory; if session-specific derivatives are
 generated, they should be deposited under a session subdirectory within the
 corresponding subject directory; and so on.
 
-In addition pipelines may generate derivatives that do not strictly belong to
-any single participant. To write group-level results, the `group/` folder for
-example `<dataset>/derivatives/<pipeline_name>/group/`.
-
 ## Derived dataset and pipeline description
 
 As for any BIDS dataset a `dataset_description.json` file MUST be found at the
@@ -205,10 +201,10 @@ expressed as follows:
 -   When the derivatives chain involves outputs derived from a single raw input,
     `source_keywords` MUST be the entire source filename, with the ommission of
     the source suffix and extension. One exception to this rule is filename
-    keywords that are no longer relevant (such as `sub-` in the case of group
-    level derivatives). Depending on the nature of the derivative file, the
-    suffix can either be the same as the source file if that suffix is still
-    appropriate, or a new appropriate value selected from the controlled list.
+    keywords that are no longer relevant. Depending on the nature of the 
+    derivative file, the suffix can either be the same as the source file if 
+    that suffix is still appropriate, or a new appropriate value selected from 
+    the controlled list.
 
 -   There is no prohibition against identical filenames in different derived
     datasets, although users should be aware of the potential ambiguity this can

From a6f55ee7b60b0658bccb51154be29de9b058bb5f Mon Sep 17 00:00:00 2001
From: Erin W Dickie <edickie@users.noreply.github.com>
Date: Tue, 5 Mar 2019 21:34:03 -0500
Subject: [PATCH 045/191] [ENC] getting rid of type- key

I don't know where the type key came from.
I also tried to remove the reference to a space table in the introduction that has moved (is it in the appendix?)

(I'll post this an issue)
So currently we have. _dseg.tsv suffix for color lookup tables. A label-<label> key value pair for specifying the label in _probseg.nii.gz files. And files with multiple mask (i.e. atlases having a _dseg.nii.gz) extension. And and atlas-<label> key value pair that appears in fmri..

1. is it ok for _dseg.nii.gz and _dseg.tsc to have the same suffix? or are suffixes supposed to associate with a specific file type.
2. technically the _dparc.dlabel.nii could be _dseg.dlabel.nii because they have similar concepts (just cifti vs nifti).
3.
---
 src/05-derivatives/02-common-data-types.md | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index 3225628f39..d53f6fddfe 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -22,9 +22,7 @@ data types in the specification. Examples:
 
 -   Motion-corrected DWI files.
 
-The `space` keyword denotes reference atlas or map that the File is
-aligned to - see [Introduction](01-introduction.md) for allowed values. The
-`desc` keyword is a general purpose field with freeform values. To distinguish
+The `space` keyword is recomended to distinguish files with different underlying coordinate systems or registered to different reference maps. The `desc` keyword is a general purpose field with freeform values. To distinguish
 between multiple different versions of processing for the same input data the
 `desc` keyword should be used. Note that even though `space` and `desc`
 are optional at least one of them needs to be defined to avoid name conflict
@@ -74,7 +72,7 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         func|anat|dwi/
-        <source_keywords>[_space-<space>][_type-<type>][_desc-<label>]_mask.nii.gz
+        <source_keywords>[_space-<space>][_desc-<label>]_mask.nii.gz
 ```
 
 A binary (1 - inside, 0 - outside) mask in the space defined by `<space>`.

From 12ff0a6667dba274e17c22ee23fbc96f6816e2a7 Mon Sep 17 00:00:00 2001
From: Erin W Dickie <edickie@users.noreply.github.com>
Date: Tue, 5 Mar 2019 21:55:08 -0500
Subject: [PATCH 046/191] bringing back space

---
 src/05-derivatives/05-diffusion-derivatives.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 320fc49b89..525f6113b2 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -11,9 +11,9 @@ should be included in the pipeline documentation.
 <pipeline_name>/
     sub-<participant_label>/
         dwi/
-          <source_keywords>[_referencemap-<referencemap>][_desc-<label>]_dwi.nii[.gz]
-          <source_keywords>[_referencemap-<referencemap>][_desc-<label>]_dwi.bvals
-          <source_keywords>[_referencemap-<referencemap>][_desc-<label>]_dwi.bvecs
+          <source_keywords>[_space-<space>][_desc-<label>]_dwi.nii[.gz]
+          <source_keywords>[_space-<space>][_desc-<label>]_dwi.bvals
+          <source_keywords>[_space-<space>][_desc-<label>]_dwi.bvecs
 ```
 
 The JSON sidecar file is REQUIRED (due to the REQUIRED `SkullStripped` field -
@@ -54,8 +54,8 @@ The following is a general example of naming convention:
 <pipeline_name>/
     sub-<participant_label>/
         dwi/
-            <source_keywords>[_referencemap-<referencemap>][_desc-<label>]_model-<label>_diffmodel.nii[.gz]
-            <source_keywords>[_referencemap-<referencemap>][_desc-<label>]_model-<label>_diffmodel.json
+            <source_keywords>[_space-<space>][_desc-<label>]_model-<label>_diffmodel.nii[.gz]
+            <source_keywords>[_space-<space>][_desc-<label>]_model-<label>_diffmodel.json
 ```
 
 The following models are codified and should be used in the `model-<label>`
@@ -203,14 +203,14 @@ A 4D volume with floating point numbers
 my_diffusion_pipeline/
     sub-01/
         dwi/
-            sub-01_referenecemap-T1w_desc-WLS_model-DTI_diffmodel.nii.gz
+            sub-01_space-T1w_desc-WLS_model-DTI_diffmodel.nii.gz
 ```
 
 ```Text
 my_diffusion_pipeline/
     sub-01/
         dwi/
-            sub-01_referenecemap-T1w_desc-WLS_model-DTI_diffmodel.json
+            sub-01_space-T1w_desc-WLS_model-DTI_diffmodel.json
 ```
 
 ```JSON
@@ -235,7 +235,7 @@ fields for the maps.
 <pipeline_name>/
     sub-<participant_label>/
         dwi/
-            <source_keywords>[_referencemap-<referencemap>space-<space>][_model-<label>][_desc-<label>]_<map_label>.nii[.gz]
+            <source_keywords>[_space-<space>][_model-<label>][_desc-<label>]_<map_label>.nii[.gz]
 ```
 
 ### Scalar maps
@@ -295,7 +295,7 @@ tractography maps should be saved as NIfTIs.
 <pipeline_name>/
     sub-<participant_label>/
         dwi/
-            <source_keywords>[_referencemap-<referencemap>][_desc-<label>][_subset-<label>]_tractography.[trk|tck|nii[.gz]]
+            <source_keywords>[_space-<space>][_desc-<label>][_subset-<label>]_tractography.[trk|tck|nii[.gz]]
 ```
 
 ### Filename keys

From 1e2cc33ed62ac768940ea888d0220932213e671e Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Tue, 5 Mar 2019 19:04:44 -0800
Subject: [PATCH 047/191] clarify allowed values for 'space'

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

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index d53f6fddfe..e1ecec90a4 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -22,11 +22,14 @@ data types in the specification. Examples:
 
 -   Motion-corrected DWI files.
 
-The `space` keyword is recomended to distinguish files with different underlying coordinate systems or registered to different reference maps. The `desc` keyword is a general purpose field with freeform values. To distinguish
+The `space` keyword is recomended to distinguish files with different underlying
+coordinate systems or registered to different reference maps. Its values are
+restricted to the same vocabulary as `ReferenceMap` JSON field (see below). The
+`desc` keyword is a general purpose field with freeform values. To distinguish
 between multiple different versions of processing for the same input data the
-`desc` keyword should be used. 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.
+`desc` keyword should be used. 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.
 
 Examples:
 
@@ -34,7 +37,7 @@ Examples:
 pipeline1/
     sub-001/
         func/
-            sub-001_task-rest_run-space-MNI305_bold.nii.gz
+            sub-001_task-rest_run-1_space-MNI305_bold.nii.gz
             sub-001_task-rest_run-1_space-MNI305_bold.json
 ```
 
@@ -75,9 +78,9 @@ Template:
         <source_keywords>[_space-<space>][_desc-<label>]_mask.nii.gz
 ```
 
-A binary (1 - inside, 0 - outside) mask in the space defined by `<space>`.
-By default (i.e., if no transformation has taken place) the value of
-`space` should be set to `orig`.
+A binary (1 - inside, 0 - outside) mask in the space defined by `<space>`. By
+default (i.e., if no transformation has taken place) the value of `space` should
+be set to `orig`.
 
 JSON metadata fields:
 

From 7be89b7ecd640c0ff81389d56108e8ce96682fdd Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Tue, 5 Mar 2019 19:19:01 -0800
Subject: [PATCH 048/191] adding volumetric template used in in HCP

---
 src/99-appendices/08-coordinate-systems.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/99-appendices/08-coordinate-systems.md b/src/99-appendices/08-coordinate-systems.md
index 5cc16b1024..967e96438a 100644
--- a/src/99-appendices/08-coordinate-systems.md
+++ b/src/99-appendices/08-coordinate-systems.md
@@ -163,6 +163,7 @@ the units are assumed to be mm.
 | FS305                                               | FreeSurfer variant of the MNI305 space                                                                                                                                                                                                                                                                                                                           |
 | MNI152Lin                                           | Also known as ICBM (version with linear coregistration) [http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152Lin](http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152Lin)                                                                                                                                                                                       |
 | MNI152NLin6\[Sym&#124;Asym\]                        | Also known as ICBM 6th generation (non-linear coregistration). Used by SPM99 - SPM8 and FSL (MNI152NLin6Sym). [http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin6](http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin6)                                                                                                                             |
+| MNI152NLin6AsymConte69                              | Template based on MNI152NLin6Asym using Conte69 data. Built by Human Connectome Project. [https://github.com/Washington-University/HCPpipelines/tree/master/global/templates](https://github.com/Washington-University/HCPpipelines/tree/master/global/templates)                                                                                                |
 | MNI152NLin2009\[a-c\]\[Sym&#124;Asym\]              | Also known as ICBM (non-linear coregistration with 40 iterations, released in 2009). It comes in either three different flavours each in symmetric or asymmetric version. [http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin2009](http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin2009)                                                           |
 | MNIColin27                                          | Average of 27 T1 scans of a single subject [http://www.bic.mni.mcgill.ca/ServicesAtlases/Colin27Highres](http://www.bic.mni.mcgill.ca/ServicesAtlases/Colin27Highres)                                                                                                                                                                                            |
 | MNI305                                              | Also known as avg305.                                                                                                                                                                                                                                                                                                                                            |

From bec8c23e762e2e9bcb9f9dc8b4925f149565b76f Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Tue, 5 Mar 2019 19:33:53 -0800
Subject: [PATCH 049/191] added HCP spaces and introduced hybrid spaces

---
 src/99-appendices/08-coordinate-systems.md | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/src/99-appendices/08-coordinate-systems.md b/src/99-appendices/08-coordinate-systems.md
index 967e96438a..13e076dbf7 100644
--- a/src/99-appendices/08-coordinate-systems.md
+++ b/src/99-appendices/08-coordinate-systems.md
@@ -158,6 +158,8 @@ below, the origin is at the AC and the orientation of the axes is RAS. Unless
 specified explicitly in the sidecar file in the `XXCoordinateSystemUnits` field,
 the units are assumed to be mm.
 
+### Volume
+
 | Coordinate System                                   | Description                                                                                                                                                                                                                                                                                                                                                      |
 | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | FS305                                               | FreeSurfer variant of the MNI305 space                                                                                                                                                                                                                                                                                                                           |
@@ -174,9 +176,23 @@ the units are assumed to be mm.
 | ICBM452AirSpace                                     | Reference space defined by the "average of 452 T1-weighted MRIs of normal young adult brains" with "linear transforms of the subjects into the atlas space using a 12-parameter affine transformation" [http://www.loni.usc.edu/ICBM/Downloads/Downloads_452T1.shtml](http://www.loni.usc.edu/ICBM/Downloads/Downloads_452T1.shtml)                              |
 | ICBM452Warp5Space                                   | Reference space defined by the "average of 452 T1-weighted MRIs of normal young adult brains" "based on a 5th order polynomial transformation into the atlas space" [http://www.loni.usc.edu/ICBM/Downloads/Downloads_452T1.shtml](http://www.loni.usc.edu/ICBM/Downloads/Downloads_452T1.shtml)                                                                 |
 | IXI549Space                                         | Reference space defined by the average of the "549 (...) subjects from the IXI dataset" linearly transformed to ICBM MNI 452.Used by SPM12. [http://www.brain-development.org/](http://www.brain-development.org/)                                                                                                                                               |
-| fsnative                                            | Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image                                                                                                                                                                                                                                                                         |
-| fsaverage\[3&#124;4&#124;5&#124;6&#124;sym\]        | Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image, and registered to an fsaverage template                                                                                                                                                                                                                                |
-| fsLR\[164k&#124;32k\]                               | Images were sampled to the 164k or 32k fsaverage_LR surface reconstructed from the T1w image (high resolution space of the HCPPipelines)                                                                                                                                                                                                                         |
 | UNCInfant\[0&#124;1&#124;2\]V\[21&#124;22&#124;23\] | Infant Brain Atlases from Neonates to 1- and 2-year-olds. [https://www.nitrc.org/projects/pediatricatlas](https://www.nitrc.org/projects/pediatricatlas)                                                                                                                                                                                                         |
 
+### Surface
+
+| Coordinate System                            | Description                                                                                                                              |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| fsnative                                     | Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image                                                 |
+| fsaverage\[3&#124;4&#124;5&#124;6&#124;sym\] | Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image, and registered to an fsaverage template        |
+| fsLR\[164k&#124;59k&#124;32k\]               | Images were sampled to the 164k or 32k fsaverage_LR surface reconstructed from the T1w image (high resolution space of the HCPPipelines) |
+
+### Hybrid (Volume/Surface) aliases
+
+Hybrid spaces combining surface and volume data used with CIFTI files.
+
+| Coordinate System | Description                                                                                                                                                        |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| greyordinates91k  | Combination of `MNI152NLin6AsymConte69` subcortical volumetric space and `fsLR32k` surface space resulting in 91282 data points. Used in Human Connectom Project.  |
+| greyordinates170k | Combination of `MNI152NLin6AsymConte69` subcortical volumetric space and `fsLR59k` surface space resulting in 170494 data points. Used in Human Connectom Project. |
+
 ---

From a30ed5a9c8cf21e01c8ead07c1624d143f59470b Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Tue, 5 Mar 2019 22:43:56 -0800
Subject: [PATCH 050/191] shorten labels, add links

---
 src/99-appendices/08-coordinate-systems.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/99-appendices/08-coordinate-systems.md b/src/99-appendices/08-coordinate-systems.md
index 13e076dbf7..9d7c62ca79 100644
--- a/src/99-appendices/08-coordinate-systems.md
+++ b/src/99-appendices/08-coordinate-systems.md
@@ -190,9 +190,9 @@ the units are assumed to be mm.
 
 Hybrid spaces combining surface and volume data used with CIFTI files.
 
-| Coordinate System | Description                                                                                                                                                        |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| greyordinates91k  | Combination of `MNI152NLin6AsymConte69` subcortical volumetric space and `fsLR32k` surface space resulting in 91282 data points. Used in Human Connectom Project.  |
-| greyordinates170k | Combination of `MNI152NLin6AsymConte69` subcortical volumetric space and `fsLR59k` surface space resulting in 170494 data points. Used in Human Connectom Project. |
+| Coordinate System | Description                                                                                                                                                                                                                                                                                                                                                                                             |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| greyord91k        | Combination of `MNI152NLin6AsymConte69` subcortical volumetric space (with 2mm grid) and `fsLR32k` surface space resulting in 91282 data points. Used in Human Connectom Project. [https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/91282_Greyordinates](https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/91282_Greyordinates)      |
+| greyord170k       | Combination of `MNI152NLin6AsymConte69` subcortical volumetric space (with 1.6mm grid) and `fsLR59k` surface space resulting in 170494 data points. Used in Human Connectom Project. [https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/170494_Greyordinates](https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/170494_Greyordinates) |
 
 ---

From ea2bc965618f1d0f56c9c51657e5474f015d5cdc Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Thu, 7 Mar 2019 00:42:00 +1100
Subject: [PATCH 051/191] Various proposed changes to diffusion derivatives

---
 .../05-diffusion-derivatives.md               | 333 +++++++++---------
 src/99-appendices/01-contributors.md          |   1 +
 2 files changed, 171 insertions(+), 163 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 320fc49b89..ffece3f455 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -11,28 +11,28 @@ should be included in the pipeline documentation.
 <pipeline_name>/
     sub-<participant_label>/
         dwi/
-          <source_keywords>[_referencemap-<referencemap>][_desc-<label>]_dwi.nii[.gz]
-          <source_keywords>[_referencemap-<referencemap>][_desc-<label>]_dwi.bvals
-          <source_keywords>[_referencemap-<referencemap>][_desc-<label>]_dwi.bvecs
+          <source_keywords>[_referencemap-<referencemap>][_space-<space>][_desc-<label>]_dwi.nii[.gz]
+          <source_keywords>[_referencemap-<referencemap>][_space-<space>][_desc-<label>]_dwi.bvals
+          <source_keywords>[_referencemap-<referencemap>][_space-<space>][_desc-<label>]_dwi.bvecs
 ```
 
 The JSON sidecar file is REQUIRED (due to the REQUIRED `SkullStripped` field -
 see [Common Data Types](02-common-data-types.md)), and if present can be used to
 store information about what preprocessing options were used (for example
-whether motion compensation was performed, non-linear corrections were applied,
-whether eddy current correction was performed, denoising, or intensity
-normalization were applied, etc).
+whether denoising was performed, corrections applied for field inhomogeneity /
+gradient non-linearity / motion eddy currents, intensity normalization was
+performed, etc.).
 
 Additional reserved JSON metadata fields:
 
-| **Key name**           | **Description**                                                                                                          |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| MotionCorrection       | OPTONAL. Boolean. Motion correction                                                                                      |
-| EddyCurrentCorrection  | OPTONAL. Boolean. Eddy currents corrections                                                                              |
-| Denoising              | OPTIONAL. String. Denoising method                                                                                       |
-| IntensityNormalization | OPTIONAL. Boolean. Intensity normalization                                                                               |
-| NonLinearCorrections   | OPTIONAL. Boolean. non-linear corrections                                                                                |
-| GradientNonLinearities | OPTIONAL. Correction for non-linear gradients. String with allowed values: `geometry`, `gradients`, `geometry&gradients` |
+| **Key name**                   | **Description**                                                                                                              |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
+| Denoising                      | OPTIONAL. String. Denoising method                                                                                           |
+| MotionCorrection               | OPTIONAL. Boolean. Motion correction                                                                                         |
+| EddyCurrentCorrection          | OPTIONAL. Boolean. Eddy currents corrections                                                                                 |
+| IntensityNormalizationMethod   | OPTIONAL. String. Method (if any) used for intensity normalization                                                           |
+| FieldInhomogeneityCorrection   | OPTIONAL. Boolean. Correction for geometric distrotions arising from magnetic field inhomogeneity                            |
+| GradientNonLinearityCorrection | OPTIONAL. String. Correction for non-linear gradients; allowed values: `none`, `geometry`, `gradients`, `geometry&gradients` |
 
 ## Diffusion Models (and input parameters)
 
@@ -54,8 +54,8 @@ The following is a general example of naming convention:
 <pipeline_name>/
     sub-<participant_label>/
         dwi/
-            <source_keywords>[_referencemap-<referencemap>][_desc-<label>]_model-<label>_diffmodel.nii[.gz]
-            <source_keywords>[_referencemap-<referencemap>][_desc-<label>]_model-<label>_diffmodel.json
+            <source_keywords>[_referencemap-<referencemap>][_space-<space>][_desc-<label>]_model-<label>[_parameter-<parameter>]_diffmodel.nii[.gz]
+            <source_keywords>[_referencemap-<referencemap>][_space-<space>][_desc-<label>]_model-<label>_diffmodel.json
 ```
 
 The following models are codified and should be used in the `model-<label>`
@@ -63,141 +63,128 @@ field. If a new model is used, common sense should be used to derive a name
 following the BIDS standard, and should ideally be integrated in a follow-up
 version of the specification.
 
-| Model label | Citation                                                                                       | Description                                                                                                                                                                                                                                                                                                                                       |
+| Model label | Name & citation                                                                                | Description                                                                                                                                                                                                                                                                                                                                       |
 | ----------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `DTI`       | Diffusion tensor imaging (Basser et al. 1994)                                                  | 4D image with Dxx, Dxy, Dxz, Dyy, Dyz, Dzz; the 6 unique parameters of the diffusion tensor.                                                                                                                                                                                                                                                      |
 | `DKI`       | Diffusion kurtosis imaging (Jensen et al., 2005)                                               | 4D image with Dxx, Dxy, Dxz, Dyy, Dyz, Dzz, Wxxxx, Wyyy, Wzzzz, Wxxxy, Wxxxz, Wxyyy, Wyyyz, Wxzzz, Wyzzz, Wxxyy, Wxxzz, Wyyzz, Wxxyz, Wxyyz, Wxyzz; Where D is the diffusion tensor and W is the kurtosis tensor.                                                                                                                                 |
 | `WMTI`      | White matter tract integrity (Fieremans et al., 2011)                                          | 4D image with Dxx, Dxy, Dxz, Dyy, Dyz, Dzz, Wxxxx, Wyyy, Wzzzz, Wxxxy, Wxxxz, Wxyyy, Wyyyz, Wxzzz, Wyzzz, Wxxyy, Wxxzz, Wyyzz, Wxxyz, Wxyyz, Wxyzz, Dhxx, Dhxy, Dhxz, Dhyy, Dhyz, Dhzz, Drxx, Drxy, Drxz, Dryy, Dryz, Drzz, AWF; where D is the diffusion tensor, W is the kurtosis tensor, AWF is the additional axonal water fraction parameter |
-| `CSD`       | Constrained Spherical Deconvolution (Tournier et al. 2007; Descoteaux et al. 2009)             | 4D image with SHM coefficients (size and ordering, depends on the model order and basis set, specified in the sidecar)                                                                                                                                                                                                                            |
+| `CSD`       | Constrained Spherical Deconvolution (Tournier et al. 2007; Descoteaux et al. 2009)             | 4D image with spherical harmonic (SH) coefficients (number of volumes and their ordering depends on the model maximal degree and basis set, specified in the sidecar)                                                                                                                                                                                                                            |
 | `NODDI`     | Neurite Orientation Dispersion and Density Imaging (Zhang et al. 2012, Daducci et al., 2015)   | 4D image with ICVF, OD, ISOVF; where ICVF is the “intracellular volume fraction” (also known as NDI), OD is the “orientation dispersion” (the variance of the Bingham; also known as ODI) and ISOVF is the isotropic component volume fraction (also known as IVF).                                                                               |
 | `DSI`       | Diffusion Spectrum Imaging (Wedeen et al. 2008; Paquette et al 2017)                           | DSI is generally used mostly to compute the diffusion ODF (Orientation Distribution Function). No parameters are generally returned, but an ODF can be saved as a map.                                                                                                                                                                            |
-| `CSA`       | Constant solid angle (Aganj et al. 2010)                                                       | 4D image with SHM coefficients (size and ordering, depends on the model order and basis set, specified in the side-car)                                                                                                                                                                                                                           |
+| `CSA`       | Constant solid angle (Aganj et al. 2010)                                                       | 4D image with SH coefficients (number of volumes and their ordering depends on the model maximal degree and basis set, specified in the side-car)                                                                                                                                                                                                                           |
 | `SHORE`     | Simple Harmonic Oscillator based Reconstruction and Estimation. (Ozarslan et al. 2008)         | 4D image with basis coefficients depending on choice of basis.                                                                                                                                                                                                                                                                                    |
 | `MAPMRI`    | Mean Apparent Propagator MRI. (Ozarslan, 2013)                                                 | 4D image with basis coefficients depending on choice of basis.                                                                                                                                                                                                                                                                                    |
-| `FORECAST`  | Fiber ORientation Estimated using Continuous Axially Symmetric Tensors. (Zuchelli et al. 2017) | 4D image with SHM coefficients.                                                                                                                                                                                                                                                                                                                   |
+| `FORECAST`  | Fiber ORientation Estimated using Continuous Axially Symmetric Tensors. (Zuchelli et al. 2017) | 4D image with SH coefficients.                                                                                                                                                                                                                                                                                                                   |
 | `fwDTI`     | Free water DTI (Hoy et al. 2014)                                                               | 4D image with D_c_xx, D_c_xy, D_c_xz, D_c_yy, D_c_yz, D_c_zz, FWF; where D_c is the fw-corrected diffusion tensor in this voxel.                                                                                                                                                                                                                  |
 | `BedpostX`  | Ball-and-Stick model (Behrens et al. 2007; Jabdbi et al, MRM 2012)                             | 5D image (xyz, m, n) for m parameters and n MCMC samples (n=1 implies best-fit parameters). Parameters are f_i, th_i, ph_i (volume fraction, polar angle, azimuthal angle) for up to 3 fibres, d, d_std (for “multiexponential” model)                                                                                                            |
 
 The JSON sidecar contains the following key/value pairs common for all models:
 
-| **Key name** | **Description**                                                                                                                      |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
-| Model        | Model label - see table above                                                                                                        |
-| Shells       | OPTIONAL. Shells that were utilized to fit the model, as a list of b-values. If the key is not present, all shells were used.        |
-| Gradients    | OPTIONAL. Subset of gradients utilized to fit the model, as a list of three-elements lists. If not present, all gradients were used. | ModelDescription | OPTIONAL. Extended information to describe the model. |
-| ModelURL     | OPTIONAL. URL to the implementation of the specific model utilized.                                                                  |
-| Parameters   | OPTIONAL. A dictionary of model parameters (see below for keys specific to each model)                                               |
+| **Key name**     | **Description**                                                                                                                      |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| Shells           | OPTIONAL. Shells that were utilized to fit the model, as a list of b-values. If the key is not present, all shells were used.        |
+| Gradients        | OPTIONAL. Subset of gradients utilized to fit the model, as a list of three-elements lists. If not present, all gradients were used. |
+| ModelDescription | OPTIONAL. Extended information to describe the model.                                                                                |
+| ModelURL         | OPTIONAL. URL to the implementation of the specific model utilized.                                                                  |
+| Parameters       | OPTIONAL. A dictionary of model parameters (see below).                                                                              |
 
--   Model:
+Parameters that may be stored within the JSON sidecar "Parameters" field depend on the particular model used:
 
-    -   `DTI` :
+-   `DTI` :
 
-        -   `FitMethod` : {`WLS`,`OLS`,`NLLS`,`RESTORE`}
-        -   `RESTORE` : sigma
+    -   `FitMethod` : {`WLS`,`OLS`,`NLLS`,`RESTORE`}
+    -   `RESTORE` : sigma
 
-    -   `DKI` and `WMTI`:
+-   `DKI` and `WMTI`:
 
-        -   `FitMethod` : {`WLS`,`OLS`,`NLLS`}
+    -   `FitMethod` : {`WLS`,`OLS`,`NLLS`}
 
-    -   `CSD`:
+-   `CSD`:
 
-        -   `SphericalHarmonicOrder` : value
-        -   `ResponseFunctionOrder` : value
-        -   `ResponseFunction` : \[1:response_function_order_value,b0mean\]
-        -   `Basis` : {`MRtrix 0.2`,`MRtrix3`,`DESCOTEAUX`}
+    -   `Tissue` : string
+    -   `SphericalHarmonicDegree` : value
+    -   `ResponseFunctionDegree` : value
+    -   `ResponseFunction` : values
+        (1 row per unique *b*-value, with lower *b*-values listed first;
+        1 column per even harmonic degree starting from zero)
+    -   `SphericalHarmonicBasis` : {`MRtrix 0.2`,`MRtrix3`,`DESCOTEAUX`}
+    -   `NonNegativityConstraint` : {`soft`,`hard`,`none`}
 
-    -   `CSDM`:
+-   `NODDI`:
 
-        -   `SphericalHarmonicOrder` : \[values (1 x number of tissues)\]
+    -   `DPar` : value
+    -   `DIso` : value
+    -   `Lambda1` : value
+    -   `Lambda2` : value
 
-        -   `ResponseFunctionOrder` : \[values (1 x number of tissues)\]
+-   `DSI` :
 
-        -   `ResponseFunction` : \[values (1 x number of
-            tissues)\]\[1:response_function_order_value x number of tissues,
-            b0mean x number of tissues\]
+    -   `GridSize` : value
+    -   `RStart` : value
+    -   `RStep` : value
+    -   `REnd` : value
+    -   `FilterWidth` : value
 
-        -   `Basis` : {`MRtrix 0.2`,`MRtrix3`,`DESCOTEAUX`}
+-   `CSA` :
 
-    -   `NODDI`:
+    -   `SphericalHarmonicOrder` : value
+    -   `Smoothing` : value
+    -   `Basis` : value
 
-        -   `DPar` : value
-        -   `DIso` : value
-        -   `Lambda1` : value
-        -   `Lambda2` : value
+-   `SHORE` :
 
-    -   `DSI` :
+    -   `RadialOrder` : value
+    -   `Zeta` : value
+    -   `LambdaN` : value
+    -   `LambdaL` : value
+    -   `Tau` : value
+    -   `ConstrainE0` : value
+    -   `PositiveConstraint` : value
+    -   `PosGrid` : value
+    -   `PosRadius` : value
 
-        -   `GridSize` : value
-        -   `RStart` : value
-        -   `RStep` : value
-        -   `REnd` : value
-        -   `FilterWidth` : value
+-   `MAPMRI` :
 
-    -   `CSA` :
+    -   `RadialOrder` : value
+    -   `LaplacianRegularization` : bool
+    -   `LaplacianWeighting` : value
+    -   `PositivityConstraint` : bool
+    -   `Tau` : value
+    -   `ConstrainE0` : value
+    -   `PositiveConstraint` : value
+    -   `PosGrid` : value
+    -   `PosRadius` : value
+    -   `AnisotropicScaling` : bool
+    -   `EigenvalueThreshold` : value
+    -   `PosGrid` : value
+    -   `BvalThreshold` : value
+    -   `DTIScaleEstimation` : bool
+    -   `StaticDiffusivity` : value
 
-        -   `SphericalHarmonicOrder` : value
-        -   `Smoothing` : value
-        -   `Basis` : value
+-   `FORECAST` :
 
-    -   `SHORE` :
+    -   `Sphere` : value
+    -   `DecAlg` : value
+    -   `LambdaLb` : value
+    -   `SphericalHarmonicsOrder` : value
 
-        -   `RadialOrder` : value
-        -   `Zeta` : value
-        -   `LambdaN` : value
-        -   `LambdaL` : value
-        -   `Tau` : value
-        -   `ConstrainE0` : value
-        -   `PositiveConstraint` : value
-        -   `PosGrid` : value
-        -   `PosRadius` : value
+-   `fwDTI` :
 
-    -   `MAPMRI` :
+    -   `FitMethod` : {"WLS","NLLS"}
 
-        -   `RadialOrder` : value
-        -   `LaplacianRegularization` : bool
-        -   `LaplacianWeighting` : value
-        -   `PositivityConstraint` : bool
-        -   `Tau` : value
-        -   `ConstrainE0` : value
-        -   `PositiveConstraint` : value
-        -   `PosGrid` : value
-        -   `PosRadius` : value
-        -   `AnisotropicScaling` : bool
-        -   `EigenvalueThreshold` : value
-        -   `PosGrid` : value
-        -   `BvalThreshold` : value
-        -   `DTIScaleEstimation` : bool
-        -   `StaticDiffusivity` : value
+-   `BEDPOSTX` :
 
-    -   `FORECAST` :
-
-        -   `Sphere` : value
-        -   `DecAlg` : value
-        -   `LambdaLb` : value
-        -   `SphericalHarmonicsOrder` : value
-
-    -   `fwDTI` :
-
-        -   `FitMethod` : {"WLS","NLLS"}
-
-    -   `BEDPOSTX` :
-
-        -   `NFibers` : value
-
-        -   `Fudge` : value
-
-        -   `BurnIn` : value
-
-        -   `NJumps` : value
-
-        -   `SampleEvery` : value
-
-        -   `Model` : {`monoexponential`, `multiexponentialStick`,
-            `multiexponentialZeppelin`}
+    -   `NFibers` : value
+    -   `Fudge` : value
+    -   `BurnIn` : value
+    -   `NJumps` : value
+    -   `SampleEvery` : value
+    -   `Model` : {`monoexponential`,`multiexponentialStick`,
+        `multiexponentialZeppelin`}
 
 Examples:
 
-A 4D volume with floating point numbers
+A 4D volume with floating point numbers:
 
 ```Text
 my_diffusion_pipeline/
@@ -218,14 +205,14 @@ my_diffusion_pipeline/
     "Model": "DTI",
     "Parameters": {
         "FitMethod": "WLS"
-        }
+    }
 }
 ```
 
 ## Model-derived maps (output parameters)
 
 Models output maps of estimated parameters. Commonly one parameter is estimated
-per voxel, we call these maps of parameters. Two types of maps are described in
+per voxel; we call these maps of parameters. Two types of maps are described in
 this specification: scalar and vector maps. Scalar maps are saved as 3D
 .nii/nii.gz files. Vector maps are saved as 4D .nii/nii.gz files. Below the
 specification for the naming of the files and a the list of currently accepted
@@ -235,19 +222,19 @@ fields for the maps.
 <pipeline_name>/
     sub-<participant_label>/
         dwi/
-            <source_keywords>[_referencemap-<referencemap>space-<space>][_model-<label>][_desc-<label>]_<map_label>.nii[.gz]
+            <source_keywords>[_referencemap-<referencemap>][_space-<space>][_desc-<label>]_model-<label>_<parameter>.nii[.gz]
 ```
 
 ### Scalar maps
 
-These maps are saved 3D NIfTI files (x,y,z, 1).
+These maps are saved 3D NIfTI files (x,y,z). Some examples of such maps are as follows:
 
-| `<map_label>` value | Description                                                                                                                 | Possible Model sources                                                                                                       | Unit or scale                                                                                                                                                                        |
+| `<parameter>` value | Description                                                                                                                 | Possible Model sources                                                                                                       | Unit or scale                                                                                                                                                                        |
 | ------------------- | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | FA                  | Fractional Anisotropy                                                                                                       | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   | Unitless \[0-1\]                                                                                                                                                                     |
-| MD                  | Mean diffusivity (also called apparent diffusion coefficient, ADC)                                                          | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   | microns^2/ms (for example, for free water in body temperature, this should be 3)                                                                                                     |
-| AD                  | Axial Diffusivity (also called parallel diffusivity)                                                                        | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   | microns^2m/s (for example, for free water in body temperature, this should be 3)                                                                                                     |
-| RD                  | Radial Diffusivity (also called perpendicular diffusivity)                                                                  | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   | microns^2/ms (for example, for free water in body temperature, this should be 3)                                                                                                     |
+| MD                  | Mean diffusivity (also called apparent diffusion coefficient, ADC)                                                          | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   | microns^2/ms (for example, for free water in body temperature, this should be approximately 3)                                                                                                     |
+| AD                  | Axial Diffusivity (also called parallel diffusivity)                                                                        | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   | microns^2/ms (for example, for free water in body temperature, this should be approximately  3)                                                                                                     |
+| RD                  | Radial Diffusivity (also called perpendicular diffusivity)                                                                  | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   | microns^2/ms (for example, for free water in body temperature, this should be approximately 3)                                                                                                     |
 | MODE                | Mode of the tensor                                                                                                          | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   |                                                                                                                                                                                      |
 | LINEARITY           | Tensor linearity (Westin 1997)                                                                                              | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   |                                                                                                                                                                                      |
 | PLANARITY           | Tensor planarity (Westin 1997)                                                                                              | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   |                                                                                                                                                                                      |
@@ -259,37 +246,39 @@ These maps are saved 3D NIfTI files (x,y,z, 1).
 | DECFA               | Directionally-encoded color (DEC) FA                                                                                        | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   | 3 8-bit floating point numbers that encode x,y,z of the principal diffusion direction in the voxel. The norm of the vector is the FA in the voxel.Need to set the NiFTI dtype to RGB |
 | ODI                 | Orientation dispersion index                                                                                                | NODDI                                                                                                                        | Normalised to \[0,1\]                                                                                                                                                                |
 | ISOVF               | Isotropic volume fraction                                                                                                   | NODDI                                                                                                                        | microns^2/ms (for example, for free water in body temperature, this should be 3)                                                                                                     |
-| TDI                 | Track Density Imaging                                                                                                       |                                                                                                                              | Streamline visitation counts                                                                                                                                                         |
 | GFA                 | Generalized Fractional Anisotropy                                                                                           | CSA, CSD, SHORE, MAPMRI, Forecast (or any model that can be represented as an ODF)                                           | Proportion \[0 - 1\]                                                                                                                                                                 |
-| AFD                 | Apparent Fiber Density                                                                                                      |                                                                                                                              | positive, unitless                                                                                                                                                                   |
 | INDEX               | Scalar maps from bedpostx                                                                                                   | FSUM (sum of partial volume fractions of the sticks)F_i (volume fraction of stick i)D (diffusivity)DSTD (std of diffusivity) | FSUM \[0 - 1\]F_i \[0 - 1\]D and DSTD microns^2/ms (for example, for free water in body temperature, this should be 3)                                                               |
 | RTPP                | Return to the plane probability                                                                                             | MAPMRI                                                                                                                       | Probability \[0 - 1\]                                                                                                                                                                |
 | RTAP                | Return to axis probability                                                                                                  | MAPMRI                                                                                                                       | Probability \[0 - 1\]                                                                                                                                                                |
 
 ### Vector-valued maps
 
-These maps are saved 4D NIfTI files (x,y,z, n\*(xyz)).
-
-| `<map_label>` values | Description                                                                                                                                                                                                                                                                                                          |
-| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| fixel                | Fixel (Fiber bundle element) images. Different voxels can have different numbers of fixels, and therefore a sparse file format is required. This is not specific to Fibre Density derived via CSD. Several diffusion models provide fixel-specific measures (e.g. Ball and stick, CHARMED, CuspMFM, Myelin content). |
-| ODF                  | Orientation distribution function                                                                                                                                                                                                                                                                                    |
-| PDF                  | Diffusion propagator                                                                                                                                                                                                                                                                                                 |
-| FOD                  | Fiber orientation distribution (Sometimes known as fODF)                                                                                                                                                                                                                                                             |
-| EVECS                | Eigenvectors of a model that has eigenvectors (such as DTI)                                                                                                                                                                                                                                                          |
-| PEAKS                | Directions of ODF maxima on the sphere.                                                                                                                                                                                                                                                                              |
+These maps are saved 4D NIfTI files (x,y,z, 3\*n), where each triplet of volumes
+encodes both a direction in 3D space and some quantitiative value (these are
+sometimes referred to as "fixels"). The number of volumes in the image must be
+3 times the maximal number of fixels that can appear in any voxel in the image
+(since 3 volumes are required to represent the data for each individual fixel).
+For voxels that contain less than this number of fixels, the excess volumes
+should contain either zero-filling, or NaN values. Exactly what is encoded by
+the amplitude of each XYZ triplet depends on the underlying model properties
+that were used to derive the map, with some examples being:
+
+| `<map_label>` values | Description                                                 |
+| -------------------- | ----------------------------------------------------------- |
+| PDF                  | Diffusion propagator                                        |
+| EVECS                | Eigenvectors of a model that has eigenvectors (such as DTI) |
+| PEAKS                | Directions and amplitudes of ODF maxima on the sphere       |
 
 ## Describing tractography
 
 Tractography normally generates one of two primary file types: tractograms or
 NIfTi files containing maps. Tractograms are files containing a collection of
 streamlines, which are objects describing the path of idealized brain fiber
-fascicles (ensembles of neural fibers that travel together). Tractography maps
-contain visitation counts (i.e. 3D spatial histograms) of a collection of
-streamlines but do not contain the actual streamline objects. The main type of
-map represent the diffusion path probability, or how likely it is that diffusion
-between pairs of brain regions. Two tractogram file formats are supported,
-tractography maps should be saved as NIfTIs.
+fascicles (ensembles of neural fibers that travel together). Tractography
+visitation maps contain 3D spatial histograms of the number / fraction of
+streamlines intersecting each voxel, but do not contain the individual
+streamlines trajectories themselves. Two tractogram file formats are supported;
+tractography visitation maps should be saved as NIfTIs.
 
 ```Text
 <pipeline_name>/
@@ -313,69 +302,87 @@ kept, or `subsampled50` if only 50% of the streamlines were kept.
 ### File formats
 
 -   [.trk - Diffusion Toolkit (+TrackVis)](https://web.archive.org/web/20190103230122/http://www.trackvis.org/docs/?subsect=fileformat)
--   [.tck - MRTrix](https://web.archive.org/web/20190103230209/https://mrtrix.readthedocs.io/en/latest/getting_started/image_data.html)
+-   [.tck - MRtrix](https://web.archive.org/web/20190103230209/https://mrtrix.readthedocs.io/en/latest/getting_started/image_data.html)
 
 ### JSON Metadata
 
 We have two main classes of tractography algorithms: Global or Local
 tractography, each with various supported algorithms.
 
-| Class  | Algorithms | Reference                                                                                                                                                            |
-| ------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| LOCAL  | PROB       | Sherbondy, A.J., et al. (2008); Tournier J.D.et al. (2012); Behrens et al. (2007)                                                                                    |
-| LOCAL  | DET        | Conturo, T. et al. (1999); Mori, S. et al. (1999)                                                                                                                    |
-| LOCAL  | EUDX       | Garyfallidis et al. (2010); Mori, S. et al. (1999)                                                                                                                   |
-| LOCAL  | FACT       | Jiang, H. et al. (2005)                                                                                                                                              |
-| LOCAL  | STT        | Lazar, M. et al. (2003)                                                                                                                                              |
-| GLOBAL | UKF        | Malcolm J-G. et al. (2009)                                                                                                                                           |
-| GLOBAL | SpinGlass  | Fillard P. et al. (2009)                                                                                                                                             |
-| GLOBAL | ENS        | Takemura et al. (2016)                                                                                                                                               |
-| GLOBAL | Other      | Mangin, J.F. et al. (2013); Aganj, I. et al. (2011); Neher, P.F. et al. (2012); Jbabdi, S., et al. (2007); Sherbondy, A.J., et al. (2009); Reisert, M. et al. (2011) |
+| Class  | Algorithms | Reference                                                                                                                            |
+| ------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| LOCAL  | PROB       | Sherbondy, A.J., et al. (2008); Tournier J.D. et al. (2012); Behrens et al. (2007)                                                   |
+| LOCAL  | DET        | Conturo, T. et al. (1999); Mori, S. et al. (1999)                                                                                    |
+| LOCAL  | EUDX       | Garyfallidis et al. (2010); Mori, S. et al. (1999)                                                                                   |
+| LOCAL  | FACT       | Jiang, H. et al. (2005)                                                                                                              |
+| LOCAL  | STT        | Lazar, M. et al. (2003)                                                                                                              |
+| LOCAL  | NULL       | Morris et al. (2008)                                                                                                                 |
+| GLOBAL | UKF        | Malcolm J-G. et al. (2009)                                                                                                           |
+| GLOBAL | SpinGlass  | Fillard P. et al. (2009)                                                                                                             |
+| GLOBAL | ENS        | Takemura et al. (2016)                                                                                                               |
+| GLOBAL | Other      | Mangin, J.F. et al. (2013); Aganj, I. et al. (2011); Neher, P.F. et al. (2012); Jbabdi, S., et al. (2007); Reisert, M. et al. (2011) |
 
 The JSON sidecar contains the following key/value pairs:
 
-| **Key name**       | **Description**                                                                                                  |
-| ------------------ | ---------------------------------------------------------------------------------------------------------------- |
-| TractographyClass  | REQUIRED. Allowed values: `local`, `global"`                                                                     |
-| TractographyMethod | REQUIRED. Allowed values: `probabilistic`,`deterministic`,`eudx`,`fact`,`stt`,`other`, `UKF`,`SpinGlass`,`other` |
+| **Key name**       | **Description**                                                                                                      |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| TractographyClass  | REQUIRED. Allowed values: `local`, `global`                                                                          |
+| TractographyMethod | REQUIRED. Allowed values: `probabilistic`,`deterministic`,`eudx`,`fact`,`stt`,`null`,`ukf`,`spinglass`,`ens`,`other` |
+| Description        | OPTIONAL. string                                                                                                     |
 
 RECOMMENDED when TractographyMethod is `probabilistic`, `deterministic`, `eudx`,
-`fact`, `stt`, `other`:
+`fact`, `stt`, `null`:
 
 | **Key name**             | **Description**                                               |
 | ------------------------ | ------------------------------------------------------------- |
 | StepSizeUnits            | "mm","norm"                                                   |
 | StepSize                 | value                                                         |
 | AngleCurvature           | value                                                         |
+| RadiusCurvature          | value                                                         |
+| MinimumLength            | value                                                         |
+| MaximumLength            | value                                                         |
+| IntegrationOrder         | integer                                                       |
+| Unidirectional           | bool                                                          |
 | SeedingMethod            | "seedsPerVoxel", "globalSeedNumber", "totalStreamlinesNumber" |
-| SeedingNumberMethod      | integer for the number of seeds                               |
+| SeedingNumber            | integer                                                       |
 | TerminationCriterion     | "leaveMask", "reachingTissueType”                             |
-| TerminationCriterionTest | "binary","ACT","CMC"                                          |
+| TerminationCriterionTest | "binary", "ACT", "CMC"                                        |
 
 Example:
 
 ```Text
-sub01-dwi_desc-DET1_tractography.trk
-sub01-dwi_desc-DET1_tractography.json
+<pipeline_name>/
+    sub-<participant_label>/
+        dwi/
+             sub-01_desc-DET1_tractography.trk
+             sub-01_desc-DET1_tractography.json
 ```
 
 ```JSON
 {
     "TractographyClass": "local",
     "TractographyMethod": "deterministic",
-    "StepSize": 0.5
+    "Parameters": {
+        "StepSize": 0.5
+    }
 }
 ```
 
 ```Text
-sub01-dwi_subset-AFLeft_tractography.trk
-sub01-dwi_subset-short_fibers_tractography.json
+<pipeline_name>/
+    sub-<participant_label>/
+        dwi/
+            sub-01_subset-shortfibers_tractography.trk
+            sub-01_subset-shortfibers_tractography.json
 ```
 
 ```JSON
 {
     "TractographyClass": "global",
- 	"TractographyMethod": "UKF",
+    "TractographyMethod": "UKF",
     "Description": "UKF tracking where only short fibers were kept."
+    "Parameters": {
+        "MaximumLength": 50.0
+    }
 }
 ```
diff --git a/src/99-appendices/01-contributors.md b/src/99-appendices/01-contributors.md
index a530f8325a..b20af549f2 100644
--- a/src/99-appendices/01-contributors.md
+++ b/src/99-appendices/01-contributors.md
@@ -102,6 +102,7 @@ your name is not listed, please add it.
 -   Ariel Rokem 📖
 -   Gunnar Schaefer 📖
 -   Jan-Mathijs Schoffelen 📖
+-   Robert E. Smith 💻📖
 -   Vanessa Sochat 📖
 -   Francois Tadel 📖🔌💡
 -   Roberto Toro 🔧

From ecbbe14ecdf4e6ca64fd18725085dea2f38df8af Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Thu, 7 Mar 2019 00:58:33 +1100
Subject: [PATCH 052/191] Derivatives: Diffusion: Tractography: Split
 "Parameters" dictionary

---
 src/05-derivatives/05-diffusion-derivatives.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index ffece3f455..4a0b6bb5d0 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -329,8 +329,9 @@ The JSON sidecar contains the following key/value pairs:
 | TractographyClass  | REQUIRED. Allowed values: `local`, `global`                                                                          |
 | TractographyMethod | REQUIRED. Allowed values: `probabilistic`,`deterministic`,`eudx`,`fact`,`stt`,`null`,`ukf`,`spinglass`,`ens`,`other` |
 | Description        | OPTIONAL. string                                                                                                     |
+| Parameters         | OPTIONAL. A dictionary of model parameters (see below).                                                              |
 
-RECOMMENDED when TractographyMethod is `probabilistic`, `deterministic`, `eudx`,
+RECOMMENDED to appear within the "Parameters" field when TractographyMethod is `probabilistic`, `deterministic`, `eudx`,
 `fact`, `stt`, `null`:
 
 | **Key name**             | **Description**                                               |

From 797c9b6be095dc82a6282d4991e24bd0984ae9dd Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Wed, 6 Mar 2019 10:28:49 -0500
Subject: [PATCH 053/191] FIX: Link subsections in functional derivatives

---
 src/05-derivatives/04-functional-derivatives.md | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/src/05-derivatives/04-functional-derivatives.md b/src/05-derivatives/04-functional-derivatives.md
index 63045a8663..cba1958db5 100644
--- a/src/05-derivatives/04-functional-derivatives.md
+++ b/src/05-derivatives/04-functional-derivatives.md
@@ -117,7 +117,7 @@ applied to the original time series data:
 | `_centered`    | The time series has had its mean subtracted                                 |
 
 For example, `rot_z_shift_back_sq` means the square of the lagged version of the
-Z rotation (see Motion-related regressors).
+Z rotation (see [Motion-related regressors](#motion-related-regressors)).
 
 ### ROI-based time series extraction
 
@@ -173,8 +173,8 @@ atlases or segmentation algorithms:
 
 Column names are unique alphanumeric values that are defined in a relevant JSON
 sidecar file. A naming convention might be to concatenate the atlas, ROI index,
-summarization method (defined below) and transformations (see Time series
-transformations, above) using snake case. For example,
+summarization method (defined below) and transformations (see [Time series
+transformations](#time-series-transformations)) using snake case. For example,
 `harvard_oxford_cortical_4_PC` could indicate ROI 4 of the Harvard-Oxford
 cortical atlas, summarized by taking the first principal component.
 
@@ -247,9 +247,11 @@ following names and units:
 | `trans_x`, `trans_y`, `trans_z` | mm      | Translation parameters |
 | `rot_x`, `rot_y`, `rot_z`       | radians | Rotation parameters    |
 
-Transformations (see Transformations) of motion parameters may be included in
-the same file. For example, rot_z_shift_back_sq means square of the lagged
-version of Z rotation.
+Transformations (see [Time series
+transformations](#time-series-transformations)) of motion parameters may be
+included in the same file.
+For example, `rot_z_shift_back_sq` means square of the lagged version of Z
+rotation.
 
 The following columns indicate summarized motion, as defined in the
 corresponding references:

From a5ef0c19cbf313a87b6a6c3468243073e8ba9388 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Wed, 6 Mar 2019 12:01:45 -0800
Subject: [PATCH 054/191] MNIfsLR32k + clarifications

---
 src/99-appendices/08-coordinate-systems.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/src/99-appendices/08-coordinate-systems.md b/src/99-appendices/08-coordinate-systems.md
index 9d7c62ca79..b57c363a29 100644
--- a/src/99-appendices/08-coordinate-systems.md
+++ b/src/99-appendices/08-coordinate-systems.md
@@ -180,19 +180,19 @@ the units are assumed to be mm.
 
 ### Surface
 
-| Coordinate System                            | Description                                                                                                                              |
-| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| fsnative                                     | Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image                                                 |
-| fsaverage\[3&#124;4&#124;5&#124;6&#124;sym\] | Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image, and registered to an fsaverage template        |
-| fsLR\[164k&#124;59k&#124;32k\]               | Images were sampled to the 164k or 32k fsaverage_LR surface reconstructed from the T1w image (high resolution space of the HCPPipelines) |
+| Coordinate System                            | Description                                                                                                                                                                                                                                                                                                                 |
+| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| fsnative                                     | Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image                                                                                                                                                                                                                                    |
+| fsaverage\[3&#124;4&#124;5&#124;6&#124;sym\] | Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image, and registered to an fsaverage template                                                                                                                                                                                           |
+| fsLR\[164k&#124;59k&#124;32k&#124;4k\]       | Images were sampled to the 164k (used by HCP pipelines for 3T and 7T anatomical analysis), 59k (used by HCP pipelines for 7T MRI bold and DWI analysis), 32k (used by HCP pipelines for 3T MRI bold and DWI analysis), or 4k (used by HCP pipelines for MEG analysis) fsaverage_LR surface reconstructed from the T1w image |
 
 ### Hybrid (Volume/Surface) aliases
 
 Hybrid spaces combining surface and volume data used with CIFTI files.
 
-| Coordinate System | Description                                                                                                                                                                                                                                                                                                                                                                                             |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| greyord91k        | Combination of `MNI152NLin6AsymConte69` subcortical volumetric space (with 2mm grid) and `fsLR32k` surface space resulting in 91282 data points. Used in Human Connectom Project. [https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/91282_Greyordinates](https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/91282_Greyordinates)      |
-| greyord170k       | Combination of `MNI152NLin6AsymConte69` subcortical volumetric space (with 1.6mm grid) and `fsLR59k` surface space resulting in 170494 data points. Used in Human Connectom Project. [https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/170494_Greyordinates](https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/170494_Greyordinates) |
+| Coordinate System | Description                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| MNIfsLR32k        | Combination of `MNI152NLin6AsymConte69` subcortical volumetric space (with 2mm grid) and `fsLR32k` surface space resulting in 91282 data points per timepoint. Used in Human Connectom Project. [https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/91282_Greyordinates](https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/91282_Greyordinates)      |
+| MNIfsLR59k        | Combination of `MNI152NLin6AsymConte69` subcortical volumetric space (with 1.6mm grid) and `fsLR59k` surface space resulting in 170494 data points per timepoint. Used in Human Connectom Project. [https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/170494_Greyordinates](https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/170494_Greyordinates) |
 
 ---

From 7e4fa68e7aed6d8148cb8876d2d39813bb199659 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Wed, 6 Mar 2019 13:09:18 -0800
Subject: [PATCH 055/191] small fixes

---
 src/05-derivatives/01-introduction.md      | 2 +-
 src/05-derivatives/02-common-data-types.md | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index adaa7f1149..cab7ad4fbf 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -113,7 +113,7 @@ share the following (non-required) ones:
 | **Value name** | **Description**                                                                                                                         |
 | -------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
 | Device         | The coordinate system of the device used to acquire the data.                                                                           |
-| Aligned        | The coordinate system is specified by a target space (e.g., Talairach88, MNI305, etc.,.). See the Space keyword for details of targets. |
+| Aligned        | The coordinate system is specified by a target space (e.g., Talairach88, MNI305, etc...). See the Space keyword for details of targets. |
 | Custom         | A custom coordinate system that is not in alignment (dimensions, axis orientation, unit) with any device coordinate system.             |
 
 ### ReferenceMap key allowed values
diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index e1ecec90a4..cc92004c46 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -63,9 +63,9 @@ 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. 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. |
 
 ## Masks
 

From 394efeb9d02868ef25cf4ef677a36ad888a20aee Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Wed, 6 Mar 2019 13:27:19 -0800
Subject: [PATCH 056/191] remove transforms since they are not part of this PR

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

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index cc92004c46..4f81e653d1 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -137,8 +137,8 @@ Example:
 pipeline/
     sub-001/
         anat/
-            sub-001_space-ACPC_dseg.nii.gz
-            sub-001_space-ACPC_dseg.json
+            sub-001_space-orig_dseg.nii.gz
+            sub-001_space-orig_dseg.json
 ```
 
 A segmentation could be a binary mask that functions as a discrete `label` for a
@@ -149,7 +149,7 @@ corresponding structure. For example:
 pipeline/
     sub-001/
         anat/
-            sub-001_space-ACPC_label-GM_dseg.nii.gz
+            sub-001_space-orig_label-GM_dseg.nii.gz
 ```
 
 See "Anatomical labels" for reserved key values for `label`.
@@ -176,8 +176,8 @@ Example:
 pipeline/
     sub-001/
         anat/
-            sub-001_space-ACPC_label-BG_probseg.nii.gz
-            sub-001_space-ACPC_label-WM_probseg.nii.gz
+            sub-001_space-orig_label-BG_probseg.nii.gz
+            sub-001_space-orig_label-WM_probseg.nii.gz
 ```
 
 See "Anatomical labels" for reserved key values for `label`.
@@ -189,8 +189,8 @@ tissue class, must provide a label mapping in its JSON sidecar. For example:
 pipeline/
     sub-001/
 	    anat/
-		    sub-001_space-ACPC_probseg.nii.gz
-		    sub-001_space-ACPC_probseg.json
+		    sub-001_space-orig_probseg.nii.gz
+		    sub-001_space-orig_probseg.json
 ```
 
 The JSON sidecar must include the label-map key that specifies a tissue label
@@ -275,8 +275,8 @@ Example:
 pipeline/
     sub-001/
         anat/
-            sub-001_space-ACPC_dseg.nii.gz
-            sub-001_space-ACPC_dseg.tsv
+            sub-001_space-orig_dseg.nii.gz
+            sub-001_space-orig_dseg.tsv
 ```
 
 Definitions can also be specified with a top-level dseg.tsv, which propagates to
@@ -289,7 +289,7 @@ pipeline/
     dseg.tsv
     sub-001/
         anat/
-            sub-001_space-ACPC_dseg.nii.gz
+            sub-001_space-orig_dseg.nii.gz
 ```
 
 These tsv lookup tables should contain the following columns:

From 75400113faef71f6f80f3cec9dc5feeb754b7c77 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Wed, 6 Mar 2019 13:27:30 -0800
Subject: [PATCH 057/191] remove transforms since they are not part of this PR

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

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index cab7ad4fbf..a22dbed129 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -106,7 +106,6 @@ share the following (non-required) ones:
 | ReferenceMap         | REQUIRED when coordinate system is Aligned. Key indicates the reference atlas or map that the File is aligned to. See table below for list of common spaces.                                                                                                                                                                                          |
 | NonstandardReference | REQUIRED when a non standard template or space is used. (e.g., a custom template in MNI305 space). 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. If Space is a list, Space reference must also be a list.                                                                |
 | ReferenceIndex       | REQUIRED when an index into a 4D (ReferenceMap or NonstandardReference) file is used. Used to index into a 4D spatial-reference file.                                                                                                                                                                                                                 |
-| TransformFile        | OPTIONAL. A path to the file used to transform the source into this file.                                                                                                                                                                                                                                                                             |
 
 ### CoordinateSystem key allowed values
 
@@ -134,7 +133,6 @@ is:
 
 ```JSON
 {
-    "TransformFile": "/path/to/xfm",
     "ReferenceMap": "MNI305"
 }
 ```
@@ -144,7 +142,6 @@ used as standard space for the File. That can be written as follows:
 
 ```JSON
 {
-    "TransformFile": "/path/to/xfm",
     "NonstandardReference": "uri or path to file"
 }
 ```
@@ -154,7 +151,6 @@ possibility is enabled by using lists of spaces and references:
 
 ```JSON
 {
-    "TransformFile": "/path/to/xfm",
     "ReferenceMap": ["MNI305", "fsLR32k"]
 }
 ```
@@ -164,7 +160,6 @@ expressed as follows:
 
 ```JSON
 {
-    "TransformFile": "/path/to/xfm",
     "ReferenceMap": ["MNI152Lin", "fsLR164k"]
 }
 ```

From 8f9c92eec28c748180c9539a70948719fc5ee678 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Tue, 5 Mar 2019 09:15:08 -0500
Subject: [PATCH 058/191] ENH: Rename regressors.tsv to timeseries.tsv

Add sampling information to clarify interpretation and bring closer
into line with _physio.tsv/_stim.tsv.
---
 .../04-functional-derivatives.md              | 66 +++++++++++--------
 1 file changed, 39 insertions(+), 27 deletions(-)

diff --git a/src/05-derivatives/04-functional-derivatives.md b/src/05-derivatives/04-functional-derivatives.md
index cba1958db5..ec885a8153 100644
--- a/src/05-derivatives/04-functional-derivatives.md
+++ b/src/05-derivatives/04-functional-derivatives.md
@@ -47,27 +47,38 @@ The following metadata JSON fields are valid for derivative maps:
 | Threshold      | String describing threshold used for determining graph edges.             | `dcb`, `dcw`, `ecb`, `ecw` |
 | Method         | String describing method used to calculate measure.                       | `dcb`, `dcw`, `ecb`, `ecw` |
 
-## Time series and regressors
+## Time series
 
-For the purposes of this section, a time series or regressor is a numeric series
-of values corresponding to volumes in a BOLD series. Time series is specifically
-used to indicate an aggregate time series within an ROI, while regressor is used
-as a more general term indicating series that may be derived from other sources,
-such as head motion estimates or physiological recordings.
+A time series is an ordered series of numeric values in chronological order.
+For the purposes of this section, a "regressor" is a time series with one entry
+per volume in a BOLD series.
 
-Regressors will generally be stored as tables, with a row of column headers
-indicating the name of the regressor. In the case where every voxel has a
-regressor, then the data should be stored in a 4D NIfTI file.
+Time series will generally be stored as tables, with a row of column headers
+indicating the name of the series.
+In the case where every voxel has a time series, then the data should be stored
+in a 4D NIfTI file.
+
+All time series files MUST be accompanied by a data dictionary in JSON format,
+containing the following sampling information:
+
+| Field name | Definition |
+| ---------- | ---------- |
+| SamplingFrequency | REQUIRED. Sampling frequency (in Hz) of all columns in the file. Special value `"TR"` indicates one sample per volume of a corresponding BOLD series. |
+| StartTime | OPTIONAL. Time in seconds of the first sample, relative to the run start. (Default: 0s) |
 
-Tabular regressor files MUST be accompanied by a data dictionary in JSON format,
+The `"TR"` sampling frequency serves to indicate that no resampling is needed
+to use the series as a regressor for BOLD data, including BOLD series with
+non-uniform sampling, such as clustered sparse acquisition.
+
+Tabular time series files MUST be accompanied by additional metadata,
 consistent with the format described in
-[Common princioples](../02-common-principles.md).
+[Common princioples](../02-common-principles.md#tabular-files).
 
-Volumetric regressor files MAY be accompanied by a data dictionary in JSON
+Volumetric time series files MAY be accompanied by a data dictionary in JSON
 format, with OPTIONAL `LongName`, `Description`, `Levels`, `Units`, and
 `TermURL` fields.
 
-### General time series and regressors
+### General time series
 
 Template:
 
@@ -75,8 +86,8 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         func/
-	        <source_keywords>[_desc-<label>]_regressors.tsv
-	        <source_keywords>[_desc-<label>]_regressors.json
+	        <source_keywords>[_desc-<label>]_timeseries.tsv
+	        <source_keywords>[_desc-<label>]_timeseries.json
 ```
 
 for example:
@@ -84,14 +95,14 @@ for example:
 ```Text
 sub-001/
     func/
-        sub-001_task-rest_run-1_desc-confounds_regressors.tsv
-        sub-001_task-rest_run-1_desc-confounds_regressors.json
+        sub-001_task-rest_run-1_desc-confounds_timeseries.tsv
+        sub-001_task-rest_run-1_desc-confounds_timeseries.json
 ```
 
-Any time series or regressor with one value per BOLD volume may be stored in a
-regressors file. If a column is specified in another sub-section, then any
-additional required metadata MUST be stored in the JSON description of the
-column.
+Any time series with common timing information may be stored in a `timeseries`
+file.
+If a time series is specified in another sub-section, then any additional
+required metadata MUST be stored in the JSON description of the column.
 
 #### Column names
 
@@ -127,7 +138,7 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         func/
-            <source_keywords>[_atlas-<atlas_label>][_desc-<label>]_timeseries.<tsv|nii.gz>
+            <source_keywords>[_atlas-<atlas_label>][_desc-<label>]_timeseries.<tsv|nii[.gz]>
             <source_keywords>[_atlas-<atlas_label>][_desc-<label>]_timeseries.json
 ```
 
@@ -142,10 +153,10 @@ sub-001/
         sub-001_task-rest_run-1_desc-anaticor_timeseries.json
 ```
 
-Time series will generally be stored as tables, with a row of column headers
-indicating the name of the time series. In the case where every voxel has a time
-series (i.e., voxel-wise regressors, as in ANATICOR), then the time series
-should be saved as a NIfTI file.
+ROI-based time series will generally be stored as tables, with a row of column
+headers indicating the name of the time series.
+In the case where every voxel has a time series (i.e., voxel-wise regressors,
+as in ANATICOR), then the time series should be saved as a NIfTI file.
 
 #### Column metadata special fields
 
@@ -213,6 +224,7 @@ sub-001/
 
 ```JSON
 {
+    "SamplingFrequency": "TR",
     "white_matter_mean": {
         "ROI": "WhiteMatter"
     },
@@ -297,7 +309,7 @@ The following methods are defined as reserved words:
 ### Other time series and regressors
 
 Time series and regressors that are not otherwise specified should be placed in
-a regressors.tsv file (see General time series and regressors).
+a `_timeseries.tsv` file (see General time series and regressors).
 
 #### Column names
 

From a9fd0fe77a1a8ec393461ef1f612f9cd1d24f534 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Tue, 5 Mar 2019 09:52:31 -0500
Subject: [PATCH 059/191] Typo

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

diff --git a/src/05-derivatives/04-functional-derivatives.md b/src/05-derivatives/04-functional-derivatives.md
index ec885a8153..aabe0b13d1 100644
--- a/src/05-derivatives/04-functional-derivatives.md
+++ b/src/05-derivatives/04-functional-derivatives.md
@@ -72,7 +72,7 @@ non-uniform sampling, such as clustered sparse acquisition.
 
 Tabular time series files MUST be accompanied by additional metadata,
 consistent with the format described in
-[Common princioples](../02-common-principles.md#tabular-files).
+[Common principles](../02-common-principles.md#tabular-files).
 
 Volumetric time series files MAY be accompanied by a data dictionary in JSON
 format, with OPTIONAL `LongName`, `Description`, `Levels`, `Units`, and

From 2d386ffd5ed96cb144c07c8d1d40fbf7ed38ec1c Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Wed, 6 Mar 2019 09:20:44 -0500
Subject: [PATCH 060/191] ENH: Rework metadata description

---
 .../04-functional-derivatives.md              | 33 ++++++++++---------
 1 file changed, 18 insertions(+), 15 deletions(-)

diff --git a/src/05-derivatives/04-functional-derivatives.md b/src/05-derivatives/04-functional-derivatives.md
index aabe0b13d1..e5f367cebc 100644
--- a/src/05-derivatives/04-functional-derivatives.md
+++ b/src/05-derivatives/04-functional-derivatives.md
@@ -59,24 +59,27 @@ In the case where every voxel has a time series, then the data should be stored
 in a 4D NIfTI file.
 
 All time series files MUST be accompanied by a data dictionary in JSON format,
-containing the following sampling information:
-
-| Field name | Definition |
-| ---------- | ---------- |
-| SamplingFrequency | REQUIRED. Sampling frequency (in Hz) of all columns in the file. Special value `"TR"` indicates one sample per volume of a corresponding BOLD series. |
-| StartTime | OPTIONAL. Time in seconds of the first sample, relative to the run start. (Default: 0s) |
-
+consistent with the format described in
+[Common principles](../02-common-principles.md#tabular-files), which describes
+metadata for each column name.
+In the case of NIfTI time series files, the notion of column name does not
+apply, so column-level metadata may be applied to the entire file.
+In addition, the following fields apply to the entire file in all cases:
+
+| Field name        | Definition                                                                                                                                                   |
+| :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SamplingFrequency | REQUIRED. Sampling frequency (in Hz) of all columns in the file. Special value `"TR"` indicates one sample per volume of a corresponding BOLD series.        |
+| StartTime         | OPTIONAL. Start time in seconds in relation to the start of acquisition of the first volume in the corresponding imaging file (negative values are allowed). |
+
+Note that there are several differences with these fields in
+[Physiological and other continuous recordings](
+../04-modality-specific-files/06-physiological-and-other-continuous-recordings.md).
 The `"TR"` sampling frequency serves to indicate that no resampling is needed
 to use the series as a regressor for BOLD data, including BOLD series with
 non-uniform sampling, such as clustered sparse acquisition.
-
-Tabular time series files MUST be accompanied by additional metadata,
-consistent with the format described in
-[Common principles](../02-common-principles.md#tabular-files).
-
-Volumetric time series files MAY be accompanied by a data dictionary in JSON
-format, with OPTIONAL `LongName`, `Description`, `Levels`, `Units`, and
-`TermURL` fields.
+`StartTime` is assumed to be 0 and therefore not mandatory.
+Additionally, because time series TSV files have column headers, the `Columns`
+field is omitted.
 
 ### General time series
 

From c3c937743807deb850e965ea22052e7565df402a Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Wed, 6 Mar 2019 10:27:14 -0500
Subject: [PATCH 061/191] FIX: Subsection name, link

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

diff --git a/src/05-derivatives/04-functional-derivatives.md b/src/05-derivatives/04-functional-derivatives.md
index e5f367cebc..911f0fc28a 100644
--- a/src/05-derivatives/04-functional-derivatives.md
+++ b/src/05-derivatives/04-functional-derivatives.md
@@ -312,7 +312,7 @@ The following methods are defined as reserved words:
 ### Other time series and regressors
 
 Time series and regressors that are not otherwise specified should be placed in
-a `_timeseries.tsv` file (see General time series and regressors).
+a `_timeseries.tsv` file (see [General time series](#general-time-series)).
 
 #### Column names
 

From d33fbe986e683b4351cf49300bb107e413057fef Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Thu, 7 Mar 2019 08:53:41 -0500
Subject: [PATCH 062/191] RF: Remove "regressor" term

---
 src/05-derivatives/04-functional-derivatives.md | 15 ++++++---------
 1 file changed, 6 insertions(+), 9 deletions(-)

diff --git a/src/05-derivatives/04-functional-derivatives.md b/src/05-derivatives/04-functional-derivatives.md
index 911f0fc28a..392276dec9 100644
--- a/src/05-derivatives/04-functional-derivatives.md
+++ b/src/05-derivatives/04-functional-derivatives.md
@@ -50,9 +50,6 @@ The following metadata JSON fields are valid for derivative maps:
 ## Time series
 
 A time series is an ordered series of numeric values in chronological order.
-For the purposes of this section, a "regressor" is a time series with one entry
-per volume in a BOLD series.
-
 Time series will generally be stored as tables, with a row of column headers
 indicating the name of the series.
 In the case where every voxel has a time series, then the data should be stored
@@ -131,7 +128,7 @@ applied to the original time series data:
 | `_centered`    | The time series has had its mean subtracted                                 |
 
 For example, `rot_z_shift_back_sq` means the square of the lagged version of the
-Z rotation (see [Motion-related regressors](#motion-related-regressors)).
+Z rotation (see [Motion-related time series](#motion-related-time-series)).
 
 ### ROI-based time series extraction
 
@@ -240,7 +237,7 @@ sub-001/
 }
 ```
 
-### Motion-related regressors
+### Motion-related time series
 
 Template:
 
@@ -309,14 +306,14 @@ The following methods are defined as reserved words:
 | ---------------------- | -------------------------------------------------------- |
 | `non_steady_state_<x>` | Initial non-steady-state volumes. One column per volume. |
 
-### Other time series and regressors
+### Other time series
 
-Time series and regressors that are not otherwise specified should be placed in
-a `_timeseries.tsv` file (see [General time series](#general-time-series)).
+Time series that are not otherwise specified MUST be placed in a
+`_timeseries.tsv` file (see [General time series](#general-time-series)).
 
 #### Column names
 
-The following regressors are defined as reserved words:
+The following time series are defined as reserved words:
 
 | Column name    | Description                                           |
 | -------------- | ----------------------------------------------------- |

From 2ecdbde35947ec20d503cab7bbe8ddc6bef7300e Mon Sep 17 00:00:00 2001
From: Erin W Dickie <edickie@users.noreply.github.com>
Date: Thu, 7 Mar 2019 09:23:35 -0500
Subject: [PATCH 063/191] adding myself to contributers

---
 src/99-appendices/01-contributors.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/99-appendices/01-contributors.md b/src/99-appendices/01-contributors.md
index a530f8325a..abeb5ab30b 100644
--- a/src/99-appendices/01-contributors.md
+++ b/src/99-appendices/01-contributors.md
@@ -43,8 +43,9 @@ your name is not listed, please add it.
 -   Samir Das 📖
 -   Alejandro de la Vega 🐛💻⚠️
 -   Arnaud Delorme 📖💡
+-   Erin W. Dickie 📖🤔👀📢💬
 -   Eugene P. Duff 📖
--   Elizabeth DuPre 📖💡🔍🤔
+-   Elizabeth DuPre 📖💡🔍🤔💬
 -   Eric A. Earl 🤔
 -   Anders Eklund 📖📢💻
 -   Oscar Esteban 📖🔧🤔💬💻

From 79e3f8da9d40e4b6044f3ae0d64609d786a8117c Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Thu, 7 Mar 2019 09:33:53 -0500
Subject: [PATCH 064/191] STY: Slightly less repetitive wording

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

diff --git a/src/05-derivatives/04-functional-derivatives.md b/src/05-derivatives/04-functional-derivatives.md
index 392276dec9..46ef676d41 100644
--- a/src/05-derivatives/04-functional-derivatives.md
+++ b/src/05-derivatives/04-functional-derivatives.md
@@ -49,7 +49,7 @@ The following metadata JSON fields are valid for derivative maps:
 
 ## Time series
 
-A time series is an ordered series of numeric values in chronological order.
+A time series is a chronologically ordered series of numeric values.
 Time series will generally be stored as tables, with a row of column headers
 indicating the name of the series.
 In the case where every voxel has a time series, then the data should be stored

From 132cb3e0c4ab1e5a73b7e0aee335599fd6712392 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Thu, 7 Mar 2019 15:38:20 -0800
Subject: [PATCH 065/191] HCPMNI

---
 src/99-appendices/08-coordinate-systems.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/99-appendices/08-coordinate-systems.md b/src/99-appendices/08-coordinate-systems.md
index b57c363a29..50c741dc10 100644
--- a/src/99-appendices/08-coordinate-systems.md
+++ b/src/99-appendices/08-coordinate-systems.md
@@ -192,7 +192,7 @@ Hybrid spaces combining surface and volume data used with CIFTI files.
 
 | Coordinate System | Description                                                                                                                                                                                                                                                                                                                                                                                                           |
 | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| MNIfsLR32k        | Combination of `MNI152NLin6AsymConte69` subcortical volumetric space (with 2mm grid) and `fsLR32k` surface space resulting in 91282 data points per timepoint. Used in Human Connectom Project. [https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/91282_Greyordinates](https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/91282_Greyordinates)      |
-| MNIfsLR59k        | Combination of `MNI152NLin6AsymConte69` subcortical volumetric space (with 1.6mm grid) and `fsLR59k` surface space resulting in 170494 data points per timepoint. Used in Human Connectom Project. [https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/170494_Greyordinates](https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/170494_Greyordinates) |
+| HCPMNIfsLR32k        | Combination of `MNI152NLin6AsymConte69` subcortical volumetric space (with 2mm grid) and `fsLR32k` surface space resulting in 91282 data points per timepoint. Used in Human Connectom Project. [https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/91282_Greyordinates](https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/91282_Greyordinates)      |
+| HCPMNIfsLR59k        | Combination of `MNI152NLin6AsymConte69` subcortical volumetric space (with 1.6mm grid) and `fsLR59k` surface space resulting in 170494 data points per timepoint. Used in Human Connectom Project. [https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/170494_Greyordinates](https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/170494_Greyordinates) |
 
 ---

From 4aab67ed32294470da3ecb6d30c617114ec480cb Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Thu, 7 Mar 2019 15:46:35 -0800
Subject: [PATCH 066/191] fix syntax

---
 src/05-derivatives/04-functional-derivatives.md | 3 +--
 src/99-appendices/08-coordinate-systems.md      | 4 ++--
 2 files changed, 3 insertions(+), 4 deletions(-)

diff --git a/src/05-derivatives/04-functional-derivatives.md b/src/05-derivatives/04-functional-derivatives.md
index 46ef676d41..4807d38475 100644
--- a/src/05-derivatives/04-functional-derivatives.md
+++ b/src/05-derivatives/04-functional-derivatives.md
@@ -69,8 +69,7 @@ In addition, the following fields apply to the entire file in all cases:
 | StartTime         | OPTIONAL. Start time in seconds in relation to the start of acquisition of the first volume in the corresponding imaging file (negative values are allowed). |
 
 Note that there are several differences with these fields in
-[Physiological and other continuous recordings](
-../04-modality-specific-files/06-physiological-and-other-continuous-recordings.md).
+[Physiological and other continuous recordings](../04-modality-specific-files/06-physiological-and-other-continuous-recordings.md).
 The `"TR"` sampling frequency serves to indicate that no resampling is needed
 to use the series as a regressor for BOLD data, including BOLD series with
 non-uniform sampling, such as clustered sparse acquisition.
diff --git a/src/99-appendices/08-coordinate-systems.md b/src/99-appendices/08-coordinate-systems.md
index 50c741dc10..50395a2bc9 100644
--- a/src/99-appendices/08-coordinate-systems.md
+++ b/src/99-appendices/08-coordinate-systems.md
@@ -192,7 +192,7 @@ Hybrid spaces combining surface and volume data used with CIFTI files.
 
 | Coordinate System | Description                                                                                                                                                                                                                                                                                                                                                                                                           |
 | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| HCPMNIfsLR32k        | Combination of `MNI152NLin6AsymConte69` subcortical volumetric space (with 2mm grid) and `fsLR32k` surface space resulting in 91282 data points per timepoint. Used in Human Connectom Project. [https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/91282_Greyordinates](https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/91282_Greyordinates)      |
-| HCPMNIfsLR59k        | Combination of `MNI152NLin6AsymConte69` subcortical volumetric space (with 1.6mm grid) and `fsLR59k` surface space resulting in 170494 data points per timepoint. Used in Human Connectom Project. [https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/170494_Greyordinates](https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/170494_Greyordinates) |
+| HCPMNIfsLR32k     | Combination of `MNI152NLin6AsymConte69` subcortical volumetric space (with 2mm grid) and `fsLR32k` surface space resulting in 91282 data points per timepoint. Used in Human Connectom Project. [https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/91282_Greyordinates](https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/91282_Greyordinates)      |
+| HCPMNIfsLR59k     | Combination of `MNI152NLin6AsymConte69` subcortical volumetric space (with 1.6mm grid) and `fsLR59k` surface space resulting in 170494 data points per timepoint. Used in Human Connectom Project. [https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/170494_Greyordinates](https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/170494_Greyordinates) |
 
 ---

From dcc56429d41c0bd92645798218ba5bc4b7bfee60 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Thu, 7 Mar 2019 16:01:55 -0800
Subject: [PATCH 067/191] fix syntax (for realz now)

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

diff --git a/src/05-derivatives/04-functional-derivatives.md b/src/05-derivatives/04-functional-derivatives.md
index 4807d38475..089f6feeb3 100644
--- a/src/05-derivatives/04-functional-derivatives.md
+++ b/src/05-derivatives/04-functional-derivatives.md
@@ -69,7 +69,7 @@ In addition, the following fields apply to the entire file in all cases:
 | StartTime         | OPTIONAL. Start time in seconds in relation to the start of acquisition of the first volume in the corresponding imaging file (negative values are allowed). |
 
 Note that there are several differences with these fields in
-[Physiological and other continuous recordings](../04-modality-specific-files/06-physiological-and-other-continuous-recordings.md).
+[Physiological and other continuous recordings](../04-modality-specific-files/06-physiological-and-other-continous-recordings.md).
 The `"TR"` sampling frequency serves to indicate that no resampling is needed
 to use the series as a regressor for BOLD data, including BOLD series with
 non-uniform sampling, such as clustered sparse acquisition.

From b2c7eeb17ba53a35277389a453afd6edd50af150 Mon Sep 17 00:00:00 2001
From: Erin W Dickie <edickie@users.noreply.github.com>
Date: Thu, 7 Mar 2019 20:56:14 -0500
Subject: [PATCH 068/191] adding very inflated surfaces

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

diff --git a/src/05-derivatives/03-structural-derivatives.md b/src/05-derivatives/03-structural-derivatives.md
index 534942984e..35f58ef2b7 100644
--- a/src/05-derivatives/03-structural-derivatives.md
+++ b/src/05-derivatives/03-structural-derivatives.md
@@ -33,6 +33,7 @@ The supported surface types (`<surftype>` suffix) are:
 | pial         | The gray matter / pial matter border                                 |
 | midthickness | The midpoints between wm and pial surfaces                           |
 | inflated     | An inflation of the midthickness surface (useful for visualization)  |
+| vinflated    | A very-inflated midthicknesss surface (also for visualization)       |
 | sphere       | The sphere (used for registration - see transforms for nomenclature) |
 | flat         | The flattened surface (used for visualization)                       |
 

From bd00db2d2647954806c1d961e8cc40fe95bdd163 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Fri, 8 Mar 2019 12:08:48 -0800
Subject: [PATCH 069/191] Update src/05-derivatives/05-diffusion-derivatives.md

Co-Authored-By: chrisfilo <krzysztof.gorgolewski@gmail.com>
---
 src/05-derivatives/05-diffusion-derivatives.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 525f6113b2..78d050a68e 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -3,7 +3,7 @@
 ## Preprocessed diffusion weighted images
 
 Multiple different versions of preprocessing can be stored for the same source
-data. To distinguish them from each other, the `desc` fileneame keyword can be
+data. To distinguish them from each other, the `desc` filename keyword can be
 used. Details of preprocessing performed for each variation of the processing
 should be included in the pipeline documentation.
 

From bb67fd7286b99ae63f5af47e930569c44b9e5619 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Fri, 15 Mar 2019 11:01:26 -0700
Subject: [PATCH 070/191] [INFRA] Adding instructions for naming PRs

---
 CONTRIBUTING.md          | 16 ++++++++++++++++
 pull_request_template.md | 17 +++++++++++++++++
 2 files changed, 33 insertions(+)
 create mode 100644 pull_request_template.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b3ccb3db16..6732f9f22b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -95,6 +95,22 @@ Try to keep the changes focused. If you submit a large amount of work in all in
 
 #### 4. Submit a [pull request](https://help.github.com/articles/about-pull-requests/)
 
+Please keep the title of your pull request short but informative - it will 
+appear in the changelog.
+
+Use one of the following prefixes in the title of your pull request:
+  - `[ENH]` - enhancement of the specification that adds a new feature or 
+    support for a new data type
+  - `[FIX]` - fix of a typo or language clarification
+  - `[INFRA]` - changes to the infrastructure automating the specification 
+    release (for example building HTML docs etc.)
+  - `[MISC]` - everything else including changes to the file listing 
+    contributors
+
+If you are opening a pull request to obtain early feedback, but the changes 
+are not ready to be merged (a.k.a. Work in Progress pull request) please 
+use [draft pull request](https://github.blog/2019-02-14-introducing-draft-pull-requests/).
+
 A member of the BIDS Specification team will review your changes to confirm that they can be merged into the main codebase.
 
 A [review](https://help.github.com/articles/about-pull-request-reviews/) will probably consist of a few questions to help clarify the work you've done. Keep an eye on your github notifications and be prepared to join in that conversation.
diff --git a/pull_request_template.md b/pull_request_template.md
new file mode 100644
index 0000000000..82f0ea4863
--- /dev/null
+++ b/pull_request_template.md
@@ -0,0 +1,17 @@
+--- PLEASE READ AND DELETE THE TEXT BELOW BEFORE OPENING THE PULL REQUEST ---
+
+- Please keep the title of your pull request short but informative - it will 
+  appear in the changelog
+- Use one of the following prefixes in the title of your pull request:
+  - `[ENH]` - enhancement of the specification that adds a new feature or 
+    support for a new data type
+  - `[FIX]` - fix of a typo or language clarification
+  - `[INFRA]` - changes to the infrastructure automating the specification 
+    release (for example building HTML docs etc.)
+  - `[MISC]` - everything else including changes to the file listing 
+    contributors
+- If you are opening a pull request to obtain early feedback, but the changes 
+  are not ready to be merged (a.k.a. Work in Progress pull request) please 
+  use [draft pull request](https://github.blog/2019-02-14-introducing-draft-pull-requests/)
+
+--- PLEASE READ AND DELETE THE TEXT ABOVE BEFORE OPENING THE PULL REQUEST ---
\ No newline at end of file

From 4e08507ac8f3821a5c6cb851c188d4d6944ac7ac Mon Sep 17 00:00:00 2001
From: Satrajit Ghosh <satra@mit.edu>
Date: Fri, 15 Mar 2019 17:14:09 -0400
Subject: [PATCH 071/191] REF: initial rewriting of coordinate system keys

---
 src/05-derivatives/01-introduction.md | 23 +++++++++++------------
 1 file changed, 11 insertions(+), 12 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index a22dbed129..5a05066f22 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -103,27 +103,25 @@ share the following (non-required) ones:
 | 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.                                                                                                                                                                                                                |
 | CoordinateSystem     | REQUIRED if no implicit coordinate system. Key indicates the coordinate system associated with the File. The coordinate system can be implicit to the File, for instance when data are images stored in NIfTI format. Can be a list. See Table below for list of allowed systems.                                                                     |
-| ReferenceMap         | REQUIRED when coordinate system is Aligned. Key indicates the reference atlas or map that the File is aligned to. See table below for list of common spaces.                                                                                                                                                                                          |
-| NonstandardReference | REQUIRED when a non standard template or space is used. (e.g., a custom template in MNI305 space). 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. If Space is a list, Space reference must also be a list.                                                                |
+| ReferenceMap         | 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.                                                                                                                                                                      |
 | ReferenceIndex       | REQUIRED when an index into a 4D (ReferenceMap or NonstandardReference) file is used. Used to index into a 4D spatial-reference file.                                                                                                                                                                                                                 |
 
 ### CoordinateSystem key allowed values
 
+In addition to values defined in
+[Appendix VII Table "Template based Coordinate Systems"](../99-appendices/08-coordinate-systems.md).
+
 | **Value name** | **Description**                                                                                                                         |
 | -------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| Device         | The coordinate system of the device used to acquire the data.                                                                           |
-| Aligned        | The coordinate system is specified by a target space (e.g., Talairach88, MNI305, etc...). See the Space keyword for details of targets. |
+| Unknown        | The coordinate system is unknown.                                                                                                       |
 | Custom         | A custom coordinate system that is not in alignment (dimensions, axis orientation, unit) with any device coordinate system.             |
 
 ### ReferenceMap key allowed values
 
-In addition to values defined in
-[Appendix VII Table "Template based Coordinate Systems"](../99-appendices/08-coordinate-systems.md).
-
 | **Value name** | **Description**                                                                                                                                  |
 | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
 | orig           | A (potentially unique) per-image space. Useful for describing the source of transforms from an input image to a target space.                    |
-| custom         | This can be used to point to the non-standard space of a file. This should be used only if the reference file is not in any of the other spaces. |
+| uri or path    | This can be used to point to a specific file.                                                                                                    |
 
 ### Example sidecar files
 
@@ -133,7 +131,7 @@ is:
 
 ```JSON
 {
-    "ReferenceMap": "MNI305"
+    "CoordinateSystem": "MNI305"
 }
 ```
 
@@ -142,7 +140,8 @@ used as standard space for the File. That can be written as follows:
 
 ```JSON
 {
-    "NonstandardReference": "uri or path to file"
+    "CoordinateSystem": "MNI305"
+    "ReferenceMap": "uri or path to file"
 }
 ```
 
@@ -151,7 +150,7 @@ possibility is enabled by using lists of spaces and references:
 
 ```JSON
 {
-    "ReferenceMap": ["MNI305", "fsLR32k"]
+    "CoordinateSystem": ["MNI305", "fsLR32k"]
 }
 ```
 
@@ -160,7 +159,7 @@ expressed as follows:
 
 ```JSON
 {
-    "ReferenceMap": ["MNI152Lin", "fsLR164k"]
+    "CoordinateSystem": ["MNI152Lin", "fsLR164k"]
 }
 ```
 

From e7aae1587bc93f9870f89246e7249735b7137161 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Fri, 15 Mar 2019 17:58:32 -0400
Subject: [PATCH 072/191] Update src/05-derivatives/01-introduction.md

Co-Authored-By: satra <satrajit.ghosh@gmail.com>
---
 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 5a05066f22..7c7db124ee 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -140,7 +140,7 @@ used as standard space for the File. That can be written as follows:
 
 ```JSON
 {
-    "CoordinateSystem": "MNI305"
+    "CoordinateSystem": "MNI305",
     "ReferenceMap": "uri or path to file"
 }
 ```

From 32183c28ca96eca36a4b74beb3468b765ea019fc Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Sat, 16 Mar 2019 22:08:02 +1100
Subject: [PATCH 073/191] Further widespread changes to diffusion derivatives

Following on from ea2bc965.
- Fix grammattical error in description of DWI JSON.
- Modify description of recommended NODDI model output.
- For "fwDTI" model, separate tensor coefficients and free water fraction data into two separate NIfTI images.
- For DTI model, include iterative weighted least squares as an option, and separate RESTORE (outlier rejection) as being a separate parameter rather than a method of fitting.
- For CSD model, offer two mechanisms for specifying the response function; also remove MRtrix 0.2 SH basis, and remove "none" from NonNegativityConstraint (as without a non-negativity constraint, it would not be CSD).
- Provide additional examples for DWI model outputs.
- Remove NODDI parameters from "model-derived maps", as these are re-classified as fundamental model output parameters.
- Remove DECFA from "model-derived maps", and instead define "directionally-encoded colour maps" as a different form of model-derived map, since any scalar map can be augmented with DEC.
- Add "Count" as a compulsory parameter for tractography output.
- For tractography output, provide three distinct dictionaries within the JSON: "Constraints" (ROIs and anatomical tissue constraints), "Parameters" (for parameters specific to the streamlines tractography algorithm), and "Seeding" (since determining streamline seeds is in fact independent of the particular tractography algorithm and parameters). Field "TerminationCriterion" was removed in this process as it is common for there to be more than one mechanism by which streamlines are terminated. Possibilities for streamline seeding have been more broadly generalised as part of this process.
---
 .../05-diffusion-derivatives.md               | 181 +++++++++++++-----
 1 file changed, 129 insertions(+), 52 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index e4ccc70487..12b2e6d541 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -14,13 +14,14 @@ should be included in the pipeline documentation.
             <source_keywords>[_space-<space>][_desc-<label>]_dwi.nii[.gz]
             <source_keywords>[_space-<space>][_desc-<label>]_dwi.bvals
             <source_keywords>[_space-<space>][_desc-<label>]_dwi.bvecs
+            <source_keywords>[_space-<space>][_desc-<label>]_dwi.json
 ```
 
 The JSON sidecar file is REQUIRED (due to the REQUIRED `SkullStripped` field -
 see [Common Data Types](02-common-data-types.md)), and if present can be used to
 store information about what preprocessing options were used (for example
 whether denoising was performed, corrections applied for field inhomogeneity /
-gradient non-linearity / motion eddy currents, intensity normalization was
+gradient non-linearity / subject motion / eddy currents, intensity normalization was
 performed, etc.).
 
 Additional reserved JSON metadata fields:
@@ -63,20 +64,20 @@ field. If a new model is used, common sense should be used to derive a name
 following the BIDS standard, and should ideally be integrated in a follow-up
 version of the specification.
 
-| Model label | Name & citation                                                                                | Description                                                                                                                                                                                                                                                                                                                                       |
-| ----------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `DTI`       | Diffusion tensor imaging (Basser et al. 1994)                                                  | 4D image with Dxx, Dxy, Dxz, Dyy, Dyz, Dzz; the 6 unique parameters of the diffusion tensor.                                                                                                                                                                                                                                                      |
-| `DKI`       | Diffusion kurtosis imaging (Jensen et al., 2005)                                               | 4D image with Dxx, Dxy, Dxz, Dyy, Dyz, Dzz, Wxxxx, Wyyy, Wzzzz, Wxxxy, Wxxxz, Wxyyy, Wyyyz, Wxzzz, Wyzzz, Wxxyy, Wxxzz, Wyyzz, Wxxyz, Wxyyz, Wxyzz; Where D is the diffusion tensor and W is the kurtosis tensor.                                                                                                                                 |
-| `WMTI`      | White matter tract integrity (Fieremans et al., 2011)                                          | 4D image with Dxx, Dxy, Dxz, Dyy, Dyz, Dzz, Wxxxx, Wyyy, Wzzzz, Wxxxy, Wxxxz, Wxyyy, Wyyyz, Wxzzz, Wyzzz, Wxxyy, Wxxzz, Wyyzz, Wxxyz, Wxyyz, Wxyzz, Dhxx, Dhxy, Dhxz, Dhyy, Dhyz, Dhzz, Drxx, Drxy, Drxz, Dryy, Dryz, Drzz, AWF; where D is the diffusion tensor, W is the kurtosis tensor, AWF is the additional axonal water fraction parameter |
-| `CSD`       | Constrained Spherical Deconvolution (Tournier et al. 2007; Descoteaux et al. 2009)             | 4D image with spherical harmonic (SH) coefficients (number of volumes and their ordering depends on the model maximal degree and basis set, specified in the sidecar)                                                                                                                                                                                                                            |
-| `NODDI`     | Neurite Orientation Dispersion and Density Imaging (Zhang et al. 2012, Daducci et al., 2015)   | 4D image with ICVF, OD, ISOVF; where ICVF is the “intracellular volume fraction” (also known as NDI), OD is the “orientation dispersion” (the variance of the Bingham; also known as ODI) and ISOVF is the isotropic component volume fraction (also known as IVF).                                                                               |
-| `DSI`       | Diffusion Spectrum Imaging (Wedeen et al. 2008; Paquette et al 2017)                           | DSI is generally used mostly to compute the diffusion ODF (Orientation Distribution Function). No parameters are generally returned, but an ODF can be saved as a map.                                                                                                                                                                            |
-| `CSA`       | Constant solid angle (Aganj et al. 2010)                                                       | 4D image with SH coefficients (number of volumes and their ordering depends on the model maximal degree and basis set, specified in the side-car)                                                                                                                                                                                                                           |
-| `SHORE`     | Simple Harmonic Oscillator based Reconstruction and Estimation. (Ozarslan et al. 2008)         | 4D image with basis coefficients depending on choice of basis.                                                                                                                                                                                                                                                                                    |
-| `MAPMRI`    | Mean Apparent Propagator MRI. (Ozarslan, 2013)                                                 | 4D image with basis coefficients depending on choice of basis.                                                                                                                                                                                                                                                                                    |
-| `FORECAST`  | Fiber ORientation Estimated using Continuous Axially Symmetric Tensors. (Zuchelli et al. 2017) | 4D image with SH coefficients.                                                                                                                                                                                                                                                                                                                   |
-| `fwDTI`     | Free water DTI (Hoy et al. 2014)                                                               | 4D image with D_c_xx, D_c_xy, D_c_xz, D_c_yy, D_c_yz, D_c_zz, FWF; where D_c is the fw-corrected diffusion tensor in this voxel.                                                                                                                                                                                                                  |
-| `BedpostX`  | Ball-and-Stick model (Behrens et al. 2007; Jabdbi et al, MRM 2012)                             | 5D image (xyz, m, n) for m parameters and n MCMC samples (n=1 implies best-fit parameters). Parameters are f_i, th_i, ph_i (volume fraction, polar angle, azimuthal angle) for up to 3 fibres, d, d_std (for “multiexponential” model)                                                                                                            |
+| Model label | Name & citation                                                                                | Description                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ----------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DTI`       | Diffusion tensor imaging (Basser et al. 1994)                                                  | 4D image with Dxx, Dxy, Dxz, Dyy, Dyz, Dzz; the 6 unique parameters of the diffusion tensor.                                                                                                                                                                                                                                                                                                                                           |
+| `DKI`       | Diffusion kurtosis imaging (Jensen et al., 2005)                                               | 4D image with Dxx, Dxy, Dxz, Dyy, Dyz, Dzz, Wxxxx, Wyyy, Wzzzz, Wxxxy, Wxxxz, Wxyyy, Wyyyz, Wxzzz, Wyzzz, Wxxyy, Wxxzz, Wyyzz, Wxxyz, Wxyyz, Wxyzz; Where D is the diffusion tensor and W is the kurtosis tensor.                                                                                                                                                                                                                      |
+| `WMTI`      | White matter tract integrity (Fieremans et al., 2011)                                          | 4D image with Dxx, Dxy, Dxz, Dyy, Dyz, Dzz, Wxxxx, Wyyy, Wzzzz, Wxxxy, Wxxxz, Wxyyy, Wyyyz, Wxzzz, Wyzzz, Wxxyy, Wxxzz, Wyyzz, Wxxyz, Wxyyz, Wxyzz, Dhxx, Dhxy, Dhxz, Dhyy, Dhyz, Dhzz, Drxx, Drxy, Drxz, Dryy, Dryz, Drzz, AWF; where D is the diffusion tensor, W is the kurtosis tensor, AWF is the additional axonal water fraction parameter                                                                                      |
+| `CSD`       | Constrained Spherical Deconvolution (Tournier et al. 2007; Descoteaux et al. 2009)             | 4D image with spherical harmonic (SH) coefficients (number of volumes and their ordering depends on the model maximal degree and basis set, specified in the sidecar)                                                                                                                                                                                                                                                                  |
+| `NODDI`     | Neurite Orientation Dispersion and Density Imaging (Zhang et al. 2012, Daducci et al., 2015)   | Three 3D images, with <parameter> equal to {`ICVF`,`OD`,`ISOVF`}: ICVF is the “intracellular volume fraction” (also known as NDI); OD is the “orientation dispersion” (the variance of the Bingham; also known as ODI); ISOVF is the isotropic component volume fraction (also known as IVF). Additionally a vector-valued map with the parameter name "`direction`" may provide the XYZ direction of the estimated fibre orientation. |
+| `DSI`       | Diffusion Spectrum Imaging (Wedeen et al. 2008; Paquette et al 2017)                           | DSI is generally used mostly to compute the diffusion ODF (Orientation Distribution Function). No parameters are generally returned, but an ODF can be saved as a map.                                                                                                                                                                                                                                                                 |
+| `CSA`       | Constant solid angle (Aganj et al. 2010)                                                       | 4D image with SH coefficients (number of volumes and their ordering depends on the model maximal degree and basis set, specified in the side-car)                                                                                                                                                                                                                                                                                      |
+| `SHORE`     | Simple Harmonic Oscillator based Reconstruction and Estimation. (Ozarslan et al. 2008)         | 4D image with basis coefficients depending on choice of basis.                                                                                                                                                                                                                                                                                                                                                                         |
+| `MAPMRI`    | Mean Apparent Propagator MRI. (Ozarslan, 2013)                                                 | 4D image with basis coefficients depending on choice of basis.                                                                                                                                                                                                                                                                                                                                                                         |
+| `FORECAST`  | Fiber ORientation Estimated using Continuous Axially Symmetric Tensors. (Zuchelli et al. 2017) | 4D image with SH coefficients.                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `fwDTI`     | Free water DTI (Hoy et al. 2014)                                                               | One 4D image with parameter name "`tensor`", containing 6 volumes in the order D_c_xx, D_c_xy, D_c_xz, D_c_yy, D_c_yz, D_c_zz, where D_c is the fw-corrected diffusion tensor in each voxel; one 3D image with parameter name "`FWF`" corresponding to the free water fraction in each voxel. .                                                                                                                                        |
+| `BedpostX`  | Ball-and-Stick model (Behrens et al. 2007; Jabdbi et al, MRM 2012)                             | 5D image (xyz, m, n) for m parameters and n MCMC samples (n=1 implies best-fit parameters). Parameters are f_i, th_i, ph_i (volume fraction, polar angle, azimuthal angle) for up to 3 fibres, d, d_std (for “multiexponential” model)                                                                                                                                                                                                 |
 
 The JSON sidecar contains the following key/value pairs common for all models:
 
@@ -92,23 +93,25 @@ Parameters that may be stored within the JSON sidecar "Parameters" field depend
 
 -   `DTI` :
 
-    -   `FitMethod` : {`WLS`,`OLS`,`NLLS`,`RESTORE`}
-    -   `RESTORE` : sigma
+    -   `FitMethod` : {`WLS`,`IWLS`,`OLS`,`NLLS`}
+    -   `OutlierRejection`: boolean
+    -   `RESTORESigma` : value
 
 -   `DKI` and `WMTI`:
 
-    -   `FitMethod` : {`WLS`,`OLS`,`NLLS`}
+    -   `FitMethod` : {`WLS`,`IWLS`,`OLS`,`NLLS`}
 
 -   `CSD`:
 
     -   `Tissue` : string
     -   `SphericalHarmonicDegree` : value
-    -   `ResponseFunctionDegree` : value
-    -   `ResponseFunction` : values
-        (1 row per unique *b*-value, with lower *b*-values listed first;
+    -   `ResponseFunctionZSH` : values
+        (1 row per unique *b*-value as listed in "`Shells`";
         1 column per even harmonic degree starting from zero)
-    -   `SphericalHarmonicBasis` : {`MRtrix 0.2`,`MRtrix3`,`DESCOTEAUX`}
-    -   `NonNegativityConstraint` : {`soft`,`hard`,`none`}
+    -   `ResponseFunctionTensor` : values
+        (vector of 4 values: three tensor eigenvalues, then reference b=0 intensity)
+    -   `SphericalHarmonicBasis` : {`MRtrix3`,`DESCOTEAUX`}
+    -   `NonNegativityConstraint` : {`soft`,`hard`}
 
 -   `NODDI`:
 
@@ -184,31 +187,71 @@ Parameters that may be stored within the JSON sidecar "Parameters" field depend
 
 Examples:
 
-A 4D volume with floating point numbers:
+A Diffusion Tensor fit:
 
 ```Text
 my_diffusion_pipeline/
     sub-01/
         dwi/
             sub-01_space-T1w_desc-WLS_model-DTI_diffmodel.nii.gz
+            sub-01_space-T1w_desc-WLS_model-DTI_diffmodel.json
+```
+
+Contents of JSON file:
+
+```JSON
+{
+    "Parameters": {
+        "FitMethod": "WLS"
+    }
+}
 ```
 
+A multi-shell, multi-tissue Constrained Spherical Deconvolution fit:
+
 ```Text
 my_diffusion_pipeline/
     sub-01/
         dwi/
-            sub-01_space-T1w_desc-WLS_model-DTI_diffmodel.json
+            sub-01_model-CSD_desc-WM_diffmodel.nii.gz
+            sub-01_model-CSD_desc-WM_diffmodel.json
+            sub-01_model-CSD_desc-GM_diffmodel.nii.gz
+            sub-01_model-CSD_desc-GM_diffmodel.json
+            sub-01_model-CSD_desc-CSF_diffmodel.nii.gz
+            sub-01_model-CSD_desc-CSF_diffmodel.json
 ```
 
+Contents of JSON file (using "`_tissue-WM`" as example):
+
 ```JSON
 {
-    "Model": "DTI",
+    "Shells": [ 0, 1000, 2000, 3000 ],
     "Parameters": {
-        "FitMethod": "WLS"
+        "Tissue": "White matter",
+        "SphericalHarmonicDegree": 8,
+        "ResponseFunctionZSH": [ [ 15335 0 0 0 0 0 ],
+                                 [ 7688 -2766 597 -82 10 -5 ],
+                                 [ 5258 -2592 1024 -270 48 -11 ],
+                                 [ 4226 -2193 1124 -436 119 -19 ] ]
+        "SphericalHarmonicBasis": "MRtrix3",
+        "NonNegativityConstraint": "hard"
     }
 }
 ```
 
+A NODDI fit:
+
+```Text
+my_diffusion_pipeline/
+    sub-01/
+        dwi/
+            sub-01_model-NODDI_parameter-ICVF_diffmodel.nii.gz
+            sub-01_model-NODDI_parameter-OD_diffmodel.nii.gz
+            sub-01_model-NODDI_parameter-ISOVF_diffmodel.nii.gz
+            sub-01_model-NODDI_parameter-direction_diffmodel.nii.gz
+            sub-01_model-NODDI_diffmodel.json
+```
+
 ## Model-derived maps (output parameters)
 
 Models output maps of estimated parameters. Commonly one parameter is estimated
@@ -222,7 +265,7 @@ fields for the maps.
 <pipeline_name>/
     sub-<participant_label>/
         dwi/
-            <source_keywords>[_space-<space>][_desc-<label>]_model-<label>_<parameter>.nii[.gz]
+            <source_keywords>[_space-<space>]_model-<label>[_desc-<label>]_<parameter>.nii[.gz]
 ```
 
 ### Scalar maps
@@ -242,15 +285,30 @@ These maps are saved 3D NIfTI files (x,y,z). Some examples of such maps are as f
 | MK                  | Mean kurtosis                                                                                                               | DKI, WMTI                                                                                                                    | Unitless                                                                                                                                                                             |
 | RK                  | Radial kurtosis                                                                                                             | DKI, WMTI                                                                                                                    | Unitless                                                                                                                                                                             |
 | AK                  | Axial kurtosis                                                                                                              | DKI, WMTI                                                                                                                    | Unitless                                                                                                                                                                             |
-| ICVF                | Intracellular volume fraction. This can be calculated from different models, so can have slightly different interpretation. | WMTI (AWF), NODDI                                                                                                            | Proportion \[0-1\]                                                                                                                                                                   |
-| DECFA               | Directionally-encoded color (DEC) FA                                                                                        | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   | 3 8-bit floating point numbers that encode x,y,z of the principal diffusion direction in the voxel. The norm of the vector is the FA in the voxel.Need to set the NiFTI dtype to RGB |
-| ODI                 | Orientation dispersion index                                                                                                | NODDI                                                                                                                        | Normalised to \[0,1\]                                                                                                                                                                |
-| ISOVF               | Isotropic volume fraction                                                                                                   | NODDI                                                                                                                        | microns^2/ms (for example, for free water in body temperature, this should be 3)                                                                                                     |
 | GFA                 | Generalized Fractional Anisotropy                                                                                           | CSA, CSD, SHORE, MAPMRI, Forecast (or any model that can be represented as an ODF)                                           | Proportion \[0 - 1\]                                                                                                                                                                 |
 | INDEX               | Scalar maps from bedpostx                                                                                                   | FSUM (sum of partial volume fractions of the sticks)F_i (volume fraction of stick i)D (diffusivity)DSTD (std of diffusivity) | FSUM \[0 - 1\]F_i \[0 - 1\]D and DSTD microns^2/ms (for example, for free water in body temperature, this should be 3)                                                               |
 | RTPP                | Return to the plane probability                                                                                             | MAPMRI                                                                                                                       | Probability \[0 - 1\]                                                                                                                                                                |
 | RTAP                | Return to axis probability                                                                                                  | MAPMRI                                                                                                                       | Probability \[0 - 1\]                                                                                                                                                                |
 
+### Directionally-encoded colour (DEC) maps
+
+These maps are saved as 4D NIfTI files with 3 volumes (x,y,z,{RGB}), where the
+three values in each voxel correspond to red, green and blue components indicating
+directionality of the underlying model (each of which must be a non-negative value),
+and the norm of the vector encodes any scalar parameter from the diffusion model.
+Images encoded in this way should include the field "`_desc-DEC`" in order to
+distinguish them from vector-valued maps (see below).
+
+A common example is DEC FA maps, where the fractional anisotropy from the diffusion
+tensor model is coloured according to the direction of the principal eigenvector:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        dwi/
+            <source_keywords>_model-DTI_desc-DEC_FA.nii[.gz]
+```
+
 ### Vector-valued maps
 
 These maps are saved 4D NIfTI files (x,y,z, 3\*n), where each triplet of volumes
@@ -328,26 +386,45 @@ The JSON sidecar contains the following key/value pairs:
 | ------------------ | -------------------------------------------------------------------------------------------------------------------- |
 | TractographyClass  | REQUIRED. Allowed values: `local`, `global`                                                                          |
 | TractographyMethod | REQUIRED. Allowed values: `probabilistic`,`deterministic`,`eudx`,`fact`,`stt`,`null`,`ukf`,`spinglass`,`ens`,`other` |
+| Count              | REQUIRED. integer                                                                                                    |
 | Description        | OPTIONAL. string                                                                                                     |
+| Constraints        | OPTIONAL. A dictionary containing various ways in which the tractography outcome is constrained (see below).         |
 | Parameters         | OPTIONAL. A dictionary of model parameters (see below).                                                              |
-
-RECOMMENDED to appear within the "Parameters" field when TractographyMethod is `probabilistic`, `deterministic`, `eudx`,
-`fact`, `stt`, `null`:
-
-| **Key name**             | **Description**                                               |
-| ------------------------ | ------------------------------------------------------------- |
-| StepSizeUnits            | "mm","norm"                                                   |
-| StepSize                 | value                                                         |
-| AngleCurvature           | value                                                         |
-| RadiusCurvature          | value                                                         |
-| MinimumLength            | value                                                         |
-| MaximumLength            | value                                                         |
-| IntegrationOrder         | integer                                                       |
-| Unidirectional           | bool                                                          |
-| SeedingMethod            | "seedsPerVoxel", "globalSeedNumber", "totalStreamlinesNumber" |
-| SeedingNumber            | integer                                                       |
-| TerminationCriterion     | "leaveMask", "reachingTissueType”                             |
-| TerminationCriterionTest | "binary", "ACT", "CMC"                                        |
+| Seeding            | OPTIONAL. A dictionary describing how streamlines were initialised (see below).                                      |
+
+RECOMMENDED to appear within the "`Constraints`" field when "`TractographyClass`" is "`local`":
+
+| **Key name**      | **Description**                                                                             |
+| ----------------- | ------------------------------------------------------------------------------------------- |
+| AnatomicalType    | {`ACT`,`CMC`}                                                                               |
+| AnatomicalImage   | string (name of anatomical tissue segmentation image)                                       |
+| Include           | list of names of inclusion ROIs (streamlines must intersect all)                            |
+| OrderedInclude    | list of names of ordered inclusion ROIs (streamlines must intersect all in order specified) |
+| Exclude           | list of names of exclusion ROIs (streamlines must not intersect any)                        |
+| Mask              | list of names of mask ROIs (streamlines must exist within)                                  |
+
+RECOMMENDED to appear within the "`Parameters`" field when "`TractographyClass`" is "`local`":
+
+| **Key name**      | **Description**                                    |
+| ----------------- | -------------------------------------------------- |
+| Units             | "mm","norm" (applies to all within "`Parameters`") |
+| StepSize          | value                                              |
+| AngleCurvature    | value (maximum angle per step)                     |
+| RadiusCurvature   | value (minimal radius of curvature)                |
+| MinimumLength     | value                                              |
+| MaximumLength     | value                                              |
+| IntegrationOrder  | integer                                            |
+| Unidirectional    | bool                                               |
+
+RECOMMENDED to appear within the "Seeding" field when `TractographyClass` is `local`:
+
+| **Key name** | **Description**                                                                                                          |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------ |
+| SourceType   | {`sphere`,`voxels`,`surface`,`odf`}                                                                                      |
+| Location     | values: If "`SourceType`" is "`sphere`", provide a 4-vector containin the XYZ location and radius in mm of the sphere    |
+| Name         | string: If "`SourceType`" is not "`sphere`", give the filename from which seeds were derived                             |
+| CountType    | {`global`,`local`} (i.e. does Count reflect a count per voxel / vertex, or a single count for the entire reconstruction) |
+| Count        | integer                                                                                                                  |
 
 Example:
 
@@ -355,8 +432,8 @@ Example:
 <pipeline_name>/
     sub-<participant_label>/
         dwi/
-             sub-01_desc-DET1_tractography.trk
-             sub-01_desc-DET1_tractography.json
+            sub-01_desc-DET_tractography.trk
+            sub-01_desc-DET_tractography.json
 ```
 
 ```JSON

From 18dc84fceb14df0ba1e4482e0fcc1261e03544eb Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Sat, 16 Mar 2019 22:24:19 +1100
Subject: [PATCH 074/191] Resolve build issues in diffusion derivatives

---
 .../05-diffusion-derivatives.md               | 42 ++++++++++---------
 1 file changed, 23 insertions(+), 19 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 12b2e6d541..80ecaac94e 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -104,13 +104,18 @@ Parameters that may be stored within the JSON sidecar "Parameters" field depend
 -   `CSD`:
 
     -   `Tissue` : string
+    
     -   `SphericalHarmonicDegree` : value
+    
     -   `ResponseFunctionZSH` : values
         (1 row per unique *b*-value as listed in "`Shells`";
         1 column per even harmonic degree starting from zero)
+        
     -   `ResponseFunctionTensor` : values
         (vector of 4 values: three tensor eigenvalues, then reference b=0 intensity)
+        
     -   `SphericalHarmonicBasis` : {`MRtrix3`,`DESCOTEAUX`}
+    
     -   `NonNegativityConstraint` : {`soft`,`hard`}
 
 -   `NODDI`:
@@ -182,8 +187,7 @@ Parameters that may be stored within the JSON sidecar "Parameters" field depend
     -   `BurnIn` : value
     -   `NJumps` : value
     -   `SampleEvery` : value
-    -   `Model` : {`monoexponential`,`multiexponentialStick`,
-        `multiexponentialZeppelin`}
+    -   `Model` : {`monoexponential`,`multiexponentialStick`,`multiexponentialZeppelin`}
 
 Examples:
 
@@ -272,23 +276,23 @@ fields for the maps.
 
 These maps are saved 3D NIfTI files (x,y,z). Some examples of such maps are as follows:
 
-| `<parameter>` value | Description                                                                                                                 | Possible Model sources                                                                                                       | Unit or scale                                                                                                                                                                        |
-| ------------------- | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| FA                  | Fractional Anisotropy                                                                                                       | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   | Unitless \[0-1\]                                                                                                                                                                     |
-| MD                  | Mean diffusivity (also called apparent diffusion coefficient, ADC)                                                          | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   | microns^2/ms (for example, for free water in body temperature, this should be approximately 3)                                                                                                     |
-| AD                  | Axial Diffusivity (also called parallel diffusivity)                                                                        | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   | microns^2/ms (for example, for free water in body temperature, this should be approximately  3)                                                                                                     |
-| RD                  | Radial Diffusivity (also called perpendicular diffusivity)                                                                  | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   | microns^2/ms (for example, for free water in body temperature, this should be approximately 3)                                                                                                     |
-| MODE                | Mode of the tensor                                                                                                          | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   |                                                                                                                                                                                      |
-| LINEARITY           | Tensor linearity (Westin 1997)                                                                                              | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   |                                                                                                                                                                                      |
-| PLANARITY           | Tensor planarity (Westin 1997)                                                                                              | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   |                                                                                                                                                                                      |
-| SPHERICITY          | Tensor sphericity (Westin 1997)                                                                                             | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   |                                                                                                                                                                                      |
-| MK                  | Mean kurtosis                                                                                                               | DKI, WMTI                                                                                                                    | Unitless                                                                                                                                                                             |
-| RK                  | Radial kurtosis                                                                                                             | DKI, WMTI                                                                                                                    | Unitless                                                                                                                                                                             |
-| AK                  | Axial kurtosis                                                                                                              | DKI, WMTI                                                                                                                    | Unitless                                                                                                                                                                             |
-| GFA                 | Generalized Fractional Anisotropy                                                                                           | CSA, CSD, SHORE, MAPMRI, Forecast (or any model that can be represented as an ODF)                                           | Proportion \[0 - 1\]                                                                                                                                                                 |
-| INDEX               | Scalar maps from bedpostx                                                                                                   | FSUM (sum of partial volume fractions of the sticks)F_i (volume fraction of stick i)D (diffusivity)DSTD (std of diffusivity) | FSUM \[0 - 1\]F_i \[0 - 1\]D and DSTD microns^2/ms (for example, for free water in body temperature, this should be 3)                                                               |
-| RTPP                | Return to the plane probability                                                                                             | MAPMRI                                                                                                                       | Probability \[0 - 1\]                                                                                                                                                                |
-| RTAP                | Return to axis probability                                                                                                  | MAPMRI                                                                                                                       | Probability \[0 - 1\]                                                                                                                                                                |
+| `<parameter>` value | Description                                                        | Possible Model sources                                                                                                       | Unit or scale                                                                                                          |
+| ------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| FA                  | Fractional Anisotropy                                              | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   | Unitless \[0-1\]                                                                                                       |
+| MD                  | Mean diffusivity (also called apparent diffusion coefficient, ADC) | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   | microns^2/ms (for example, for free water in body temperature, this should be approximately 3)                         |
+| AD                  | Axial Diffusivity (also called parallel diffusivity)               | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   | microns^2/ms (for example, for free water in body temperature, this should be approximately 3)                         |
+| RD                  | Radial Diffusivity (also called perpendicular diffusivity)         | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   | microns^2/ms (for example, for free water in body temperature, this should be approximately 3)                         |
+| MODE                | Mode of the tensor                                                 | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   |                                                                                                                        |
+| LINEARITY           | Tensor linearity (Westin 1997)                                     | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   |                                                                                                                        |
+| PLANARITY           | Tensor planarity (Westin 1997)                                     | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   |                                                                                                                        |
+| SPHERICITY          | Tensor sphericity (Westin 1997)                                    | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   |                                                                                                                        |
+| MK                  | Mean kurtosis                                                      | DKI, WMTI                                                                                                                    | Unitless                                                                                                               |
+| RK                  | Radial kurtosis                                                    | DKI, WMTI                                                                                                                    | Unitless                                                                                                               |
+| AK                  | Axial kurtosis                                                     | DKI, WMTI                                                                                                                    | Unitless                                                                                                               |
+| GFA                 | Generalized Fractional Anisotropy                                  | CSA, CSD, SHORE, MAPMRI, Forecast (or any model that can be represented as an ODF)                                           | Proportion \[0 - 1\]                                                                                                   |
+| INDEX               | Scalar maps from bedpostx                                          | FSUM (sum of partial volume fractions of the sticks)F_i (volume fraction of stick i)D (diffusivity)DSTD (std of diffusivity) | FSUM \[0 - 1\]F_i \[0 - 1\]D and DSTD microns^2/ms (for example, for free water in body temperature, this should be 3) |
+| RTPP                | Return to the plane probability                                    | MAPMRI                                                                                                                       | Probability \[0 - 1\]                                                                                                  |
+| RTAP                | Return to axis probability                                         | MAPMRI                                                                                                                       | Probability \[0 - 1\]                                                                                                  |
 
 ### Directionally-encoded colour (DEC) maps
 

From fe074879e8b6273b8e51ff6e1759f9d15815c81a Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Sat, 16 Mar 2019 22:49:39 +1100
Subject: [PATCH 075/191] Further resolution of build issues in diffusion
 derivatives
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Follows from –18dc84fc.
---
 src/05-derivatives/05-diffusion-derivatives.md | 12 ++----------
 1 file changed, 2 insertions(+), 10 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 80ecaac94e..172f5d4cfc 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -104,18 +104,10 @@ Parameters that may be stored within the JSON sidecar "Parameters" field depend
 -   `CSD`:
 
     -   `Tissue` : string
-    
     -   `SphericalHarmonicDegree` : value
-    
-    -   `ResponseFunctionZSH` : values
-        (1 row per unique *b*-value as listed in "`Shells`";
-        1 column per even harmonic degree starting from zero)
-        
-    -   `ResponseFunctionTensor` : values
-        (vector of 4 values: three tensor eigenvalues, then reference b=0 intensity)
-        
+    -   `ResponseFunctionZSH` : values (1 row per unique *b*-value as listed in "`Shells`"; 1 column per even harmonic degree starting from zero)
+    -   `ResponseFunctionTensor` : values (vector of 4 values: three tensor eigenvalues, then reference b=0 intensity)
     -   `SphericalHarmonicBasis` : {`MRtrix3`,`DESCOTEAUX`}
-    
     -   `NonNegativityConstraint` : {`soft`,`hard`}
 
 -   `NODDI`:

From c42c4bbb9a84886740e8c2583575ae68363c2d15 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Sat, 16 Mar 2019 09:48:51 -0700
Subject: [PATCH 076/191] fixes

---
 src/05-derivatives/01-introduction.md | 46 +++++++++++++--------------
 1 file changed, 23 insertions(+), 23 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 7c7db124ee..f4590e10ba 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -32,10 +32,10 @@ Derivatives can be stored/distributed in two ways:
     dataset. This way of specifying derivatives is particularly useful when the
     source dataset is provided with read-only access, and for publishing
     derivatives as independent bodies of work, or for describing derivatives
-    that were created from more than one source dataset. It is consistent with 
-    BIDS principles for the `sourcedata/` subdirectory to be used to include or 
-    reference the source dataset(s) as it existed when the derivatives were 
-    generated. Likewise, any code used to generate the derivatives from the 
+    that were created from more than one source dataset. It is consistent with
+    BIDS principles for the `sourcedata/` subdirectory to be used to include or
+    reference the source dataset(s) as it existed when the derivatives were
+    generated. Likewise, any code used to generate the derivatives from the
     source data may be included in the `code/` subdirectory.
 
 The rest of the Derivatives specification assumes Case 1, but Case 2 applies
@@ -97,31 +97,31 @@ derivative includes REQUIRED metadata fields in which case a JSON file is also
 REQUIRED. Each derivative type defines their own set of fields, but all of them
 share the following (non-required) ones:
 
-| **Key name**         | **Description**                                                                                                                                                                                                                                                                                                                                       |
-| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 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.                                                                                                                                                                                                                |
-| CoordinateSystem     | REQUIRED if no implicit coordinate system. Key indicates the coordinate system associated with the File. The coordinate system can be implicit to the File, for instance when data are images stored in NIfTI format. Can be a list. See Table below for list of allowed systems.                                                                     |
-| ReferenceMap         | 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.                                                                                                                                                                      |
-| ReferenceIndex       | REQUIRED when an index into a 4D (ReferenceMap or NonstandardReference) file is used. Used to index into a 4D spatial-reference file.                                                                                                                                                                                                                 |
+| **Key name**     | **Description**                                                                                                                                                                                                                                                                                                                                       |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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.                                                                                                                                                                                                                |
+| CoordinateSystem | REQUIRED if no implicit coordinate system. Key indicates the coordinate system associated with the File. The coordinate system can be implicit to the File, for instance when data are images stored in NIfTI format. Can be a list. See Table below for list of allowed systems.                                                                     |
+| ReferenceMap     | 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.                                                                                                                                                                           |
+| ReferenceIndex   | REQUIRED when an index into a 4D (ReferenceMap or NonstandardReference) file is used. Used to index into a 4D spatial-reference file.                                                                                                                                                                                                                 |
 
 ### CoordinateSystem key allowed values
 
 In addition to values defined in
 [Appendix VII Table "Template based Coordinate Systems"](../99-appendices/08-coordinate-systems.md).
 
-| **Value name** | **Description**                                                                                                                         |
-| -------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| Unknown        | The coordinate system is unknown.                                                                                                       |
-| Custom         | A custom coordinate system that is not in alignment (dimensions, axis orientation, unit) with any device coordinate system.             |
+| **Value name** | **Description**                                                                                                             |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| Unknown        | The coordinate system is unknown.                                                                                           |
+| Custom         | A custom coordinate system that is not in alignment (dimensions, axis orientation, unit) with any device coordinate system. |
 
 ### ReferenceMap key allowed values
 
-| **Value name** | **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.                                                                                                    |
+| **Value name** | **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.                                                                                 |
 
 ### Example sidecar files
 
@@ -195,9 +195,9 @@ expressed as follows:
 -   When the derivatives chain involves outputs derived from a single raw input,
     `source_keywords` MUST be the entire source filename, with the ommission of
     the source suffix and extension. One exception to this rule is filename
-    keywords that are no longer relevant. Depending on the nature of the 
-    derivative file, the suffix can either be the same as the source file if 
-    that suffix is still appropriate, or a new appropriate value selected from 
+    keywords that are no longer relevant. Depending on the nature of the
+    derivative file, the suffix can either be the same as the source file if
+    that suffix is still appropriate, or a new appropriate value selected from
     the controlled list.
 
 -   There is no prohibition against identical filenames in different derived

From abf6e8f751954e8b62fe8a23253e97c411f24439 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Sat, 16 Mar 2019 11:06:41 -0700
Subject: [PATCH 077/191] [ENH] CoordinateSystem clarifications and examples

---
 src/05-derivatives/01-introduction.md      | 14 +++++++-------
 src/99-appendices/08-coordinate-systems.md |  3 ++-
 2 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index f4590e10ba..922e5bdb4b 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -103,18 +103,18 @@ share the following (non-required) ones:
 | 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.                                                                                                                                                                                                                |
 | CoordinateSystem | REQUIRED if no implicit coordinate system. Key indicates the coordinate system associated with the File. The coordinate system can be implicit to the File, for instance when data are images stored in NIfTI format. Can be a list. See Table below for list of allowed systems.                                                                     |
-| ReferenceMap     | 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.                                                                                                                                                                           |
+| ReferenceMap     | 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.                                                                                       |
 | ReferenceIndex   | REQUIRED when an index into a 4D (ReferenceMap or NonstandardReference) file is used. Used to index into a 4D spatial-reference file.                                                                                                                                                                                                                 |
 
 ### CoordinateSystem key allowed values
 
-In addition to values defined in
-[Appendix VII Table "Template based Coordinate Systems"](../99-appendices/08-coordinate-systems.md).
+Allowed values for this field depend on the file format.
 
-| **Value name** | **Description**                                                                                                             |
-| -------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| Unknown        | The coordinate system is unknown.                                                                                           |
-| Custom         | A custom coordinate system that is not in alignment (dimensions, axis orientation, unit) with any device coordinate system. |
+| File format                  | Description             | Allowed `CoordinateSystem` values                                                                                                                                                           |
+| ---------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| NIfTI (`.nii` and `.nii.gz`) | Volume data             | Coordinate systems listed in [Template Based Coordinate Systems: Volume](../99-appendices/08-coordinate-systems.md#volume). If `anat` is used then setting `ReferenceMap` is REQUIRED       |
+| GIFTI (`.gii`)               | Surface data            | Coordinate systems listed in [Template Based Coordinate Systems: Surface](../99-appendices/08-coordinate-systems.md#surface). If `fsnative` is used then setting `ReferenceMap` is REQUIRED |
+| CIFTI (`.nii`)               | Volume and surface data | Coordinate systems listed in [Template Based Coordinate Systems: Hybrid (Volume/Surface) aliases](../99-appendices/08-coordinate-systems.md#hybrid-volumesurface-aliases)                   |
 
 ### ReferenceMap key allowed values
 
diff --git a/src/99-appendices/08-coordinate-systems.md b/src/99-appendices/08-coordinate-systems.md
index 50395a2bc9..e6b7525d88 100644
--- a/src/99-appendices/08-coordinate-systems.md
+++ b/src/99-appendices/08-coordinate-systems.md
@@ -162,6 +162,7 @@ the units are assumed to be mm.
 
 | Coordinate System                                   | Description                                                                                                                                                                                                                                                                                                                                                      |
 | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| anat                                                | Participant specific anatomical space (for example derived from T1w and/or T2w images). This coordinate system require specifying an additional participant specific file to be fully defined.                                                                                                                                                                   |
 | FS305                                               | FreeSurfer variant of the MNI305 space                                                                                                                                                                                                                                                                                                                           |
 | MNI152Lin                                           | Also known as ICBM (version with linear coregistration) [http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152Lin](http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152Lin)                                                                                                                                                                                       |
 | MNI152NLin6\[Sym&#124;Asym\]                        | Also known as ICBM 6th generation (non-linear coregistration). Used by SPM99 - SPM8 and FSL (MNI152NLin6Sym). [http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin6](http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin6)                                                                                                                             |
@@ -182,7 +183,7 @@ the units are assumed to be mm.
 
 | Coordinate System                            | Description                                                                                                                                                                                                                                                                                                                 |
 | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| fsnative                                     | Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image                                                                                                                                                                                                                                    |
+| fsnative                                     | Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image. This coordinate system require specifying additional participant specific files to be fully defined.                                                                                                                              |
 | fsaverage\[3&#124;4&#124;5&#124;6&#124;sym\] | Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image, and registered to an fsaverage template                                                                                                                                                                                           |
 | fsLR\[164k&#124;59k&#124;32k&#124;4k\]       | Images were sampled to the 164k (used by HCP pipelines for 3T and 7T anatomical analysis), 59k (used by HCP pipelines for 7T MRI bold and DWI analysis), 32k (used by HCP pipelines for 3T MRI bold and DWI analysis), or 4k (used by HCP pipelines for MEG analysis) fsaverage_LR surface reconstructed from the T1w image |
 

From 617e00a8a52229b931cbc55ca1b16aa5865b152e Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Sat, 16 Mar 2019 11:14:26 -0700
Subject: [PATCH 078/191] [ENH] CoordinateSystem clarifications and examples

---
 src/05-derivatives/01-introduction.md | 60 ++++++++++++++++++++-------
 1 file changed, 46 insertions(+), 14 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 922e5bdb4b..a010f70eaf 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -123,11 +123,14 @@ Allowed values for this field depend on the file format.
 | 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.                                                                                 |
 
-### Example sidecar files
+### Examples
 
-For a NIFTI file (Single coordinate system), one could have registered the File
-on to the standard MNI305 template. The way to write the metadata of such File
-is:
+Preprocessed `bold` NIfTI file in `MNI305` coordinate space
+
+```Text
+sub-01/func/sub-01_task-rest_space-MNI305_bold.nii.gz
+sub-01/func/sub-01_task-rest_space-MNI305_bold.json
+```
 
 ```JSON
 {
@@ -135,31 +138,60 @@ is:
 }
 ```
 
-However, it could also be the case that a nonstandard derivative of MNI305 was
-used as standard space for the File. That can be written as follows:
+Preprocessed `bold` NIfTI file in `anat` coordinate space. Please mind that in
+this case `ReferenceMap` key is REQUIRED.
+
+```Text
+sub-01/func/sub-01_task-rest_space-anat_bold.nii.gz
+sub-01/func/sub-01_task-rest_space-anat_bold.json
+```
+
+```JSON
+{
+    "CoordinateSystem": "anat",
+    "ReferenceMap": "/sub-01/anat/sub-01_desc-combined_T1w.nii.gz"
+}
+```
+
+Participant cortical thickness GIFTI file in `fsaverage5` coordinate space.
+
+```Text
+sub-01/anat/sub-01_hemi-L_space-fsaverage5_thickness.shape.gii
+sub-01/anat/sub-01_hemi-R_space-fsaverage5_thickness.shape.gii
+sub-01/anat/sub-01_space-fsaverage5_thickness.json
+```
 
 ```JSON
 {
-    "CoordinateSystem": "MNI305",
-    "ReferenceMap": "uri or path to file"
+    "CoordinateSystem": "fsaverage5"
 }
 ```
 
-Some derivatives such as CIFTI Files allow for multiple coordinate systems. Such
-possibility is enabled by using lists of spaces and references:
+Participant cortical thickness GIFTI file in `fsnative` coordinate space. Please
+mind that in this case `ReferenceMap` key is REQUIRED.
+
+```Text
+sub-01/anat/sub-01_hemi-L_space-fsnative_thickness.shape.gii
+sub-01/anat/sub-01_hemi-L_space-fsnative_thickness.json
+```
 
 ```JSON
 {
-    "CoordinateSystem": ["MNI305", "fsLR32k"]
+    "CoordinateSystem": "fsnative",
+    "ReferenceMap": "/sub-01/anat/sub-01_hemi-L_pial.surf.gii"
 }
 ```
 
-Differing references of the same spaces with respect to the above example can be
-expressed as follows:
+Preprocessed `bold` CIFTI file in `HCPMNIfsLR32k` coordinate space
+
+```Text
+sub-01/func/sub-01_task-rest_space-HCPMNIfsLR32k_bold.nii
+sub-01/func/sub-01_task-rest_space-HCPMNIfsLR32k_bold.json
+```
 
 ```JSON
 {
-    "CoordinateSystem": ["MNI152Lin", "fsLR164k"]
+    "CoordinateSystem": "HCPMNIfsLR32k"
 }
 ```
 

From c7c135ec4bdfb0a576b99626137560aa67f0f639 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Sun, 17 Mar 2019 09:16:04 -0700
Subject: [PATCH 079/191] address Satra's comments

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

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index a010f70eaf..9297e86f15 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -88,6 +88,31 @@ Example:
 }
 ```
 
+## Coordinate systems
+
+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 on the file format:
+
+| File format                  | Description             | Allowed `CoordinateSystem` values                                                                                                                                                           |
+| ---------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| NIfTI (`.nii` and `.nii.gz`) | Volume data             | Coordinate systems listed in [Template Based Coordinate Systems: Volume](../99-appendices/08-coordinate-systems.md#volume). If `anat` is used then setting `ReferenceMap` is REQUIRED       |
+| GIFTI (`.gii`)               | Surface data            | Coordinate systems listed in [Template Based Coordinate Systems: Surface](../99-appendices/08-coordinate-systems.md#surface). If `fsnative` is used then setting `ReferenceMap` is REQUIRED |
+| CIFTI (`.nii`)               | Volume and surface data | Coordinate systems listed in [Template Based Coordinate Systems: Hybrid (Volume/Surface) aliases](../99-appendices/08-coordinate-systems.md#hybrid-volumesurface-aliases)                   |
+
+Examples:
+
+```Text
+sub-01/func/sub-01_task-rest_space-MNI305_bold.nii.gz
+sub-01/func/sub-01_task-rest_space-anat_bold.nii.gz
+sub-01/anat/sub-01_hemi-L_space-fsaverage5_thickness.shape.gii
+sub-01/anat/sub-01_hemi-R_space-fsaverage5_thickness.shape.gii
+sub-01/anat/sub-01_hemi-L_space-fsnative_thickness.shape.gii
+sub-01/anat/sub-01_hemi-R_space-fsnative_thickness.shape.gii
+sub-01/func/sub-01_task-rest_space-HCPMNIfsLR32k_bold.nii
+```
+
 ## Common file level metadata fields
 
 Each derivative file SHOULD be described by a JSON file provided as a sidecar or
@@ -97,24 +122,13 @@ derivative includes REQUIRED metadata fields in which case a JSON file is also
 REQUIRED. Each derivative type defines their own set of fields, but all of them
 share the following (non-required) ones:
 
-| **Key name**     | **Description**                                                                                                                                                                                                                                                                                                                                       |
-| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 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.                                                                                                                                                                                                                |
-| CoordinateSystem | REQUIRED if no implicit coordinate system. Key indicates the coordinate system associated with the File. The coordinate system can be implicit to the File, for instance when data are images stored in NIfTI format. Can be a list. See Table below for list of allowed systems.                                                                     |
-| ReferenceMap     | 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.                                                                                       |
-| ReferenceIndex   | REQUIRED when an index into a 4D (ReferenceMap or NonstandardReference) file is used. Used to index into a 4D spatial-reference file.                                                                                                                                                                                                                 |
-
-### CoordinateSystem key allowed values
-
-Allowed values for this field depend on the file format.
-
-| File format                  | Description             | Allowed `CoordinateSystem` values                                                                                                                                                           |
-| ---------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| NIfTI (`.nii` and `.nii.gz`) | Volume data             | Coordinate systems listed in [Template Based Coordinate Systems: Volume](../99-appendices/08-coordinate-systems.md#volume). If `anat` is used then setting `ReferenceMap` is REQUIRED       |
-| GIFTI (`.gii`)               | Surface data            | Coordinate systems listed in [Template Based Coordinate Systems: Surface](../99-appendices/08-coordinate-systems.md#surface). If `fsnative` is used then setting `ReferenceMap` is REQUIRED |
-| CIFTI (`.nii`)               | Volume and surface data | Coordinate systems listed in [Template Based Coordinate Systems: Hybrid (Volume/Surface) aliases](../99-appendices/08-coordinate-systems.md#hybrid-volumesurface-aliases)                   |
+| **Key name**   | **Description**                                                                                                                                                                                                                                                                                                                                       |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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.                                                                                                                                                                                                                |  |
+| ReferenceMap   | 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.                                                                                       |
+| ReferenceIndex | REQUIRED when an index into a 4D (ReferenceMap or NonstandardReference) file is used. Used to index into a 4D spatial-reference file.                                                                                                                                                                                                                 |
 
 ### ReferenceMap key allowed values
 
@@ -125,19 +139,6 @@ Allowed values for this field depend on the file format.
 
 ### Examples
 
-Preprocessed `bold` NIfTI file in `MNI305` coordinate space
-
-```Text
-sub-01/func/sub-01_task-rest_space-MNI305_bold.nii.gz
-sub-01/func/sub-01_task-rest_space-MNI305_bold.json
-```
-
-```JSON
-{
-    "CoordinateSystem": "MNI305"
-}
-```
-
 Preprocessed `bold` NIfTI file in `anat` coordinate space. Please mind that in
 this case `ReferenceMap` key is REQUIRED.
 
@@ -148,25 +149,10 @@ sub-01/func/sub-01_task-rest_space-anat_bold.json
 
 ```JSON
 {
-    "CoordinateSystem": "anat",
     "ReferenceMap": "/sub-01/anat/sub-01_desc-combined_T1w.nii.gz"
 }
 ```
 
-Participant cortical thickness GIFTI file in `fsaverage5` coordinate space.
-
-```Text
-sub-01/anat/sub-01_hemi-L_space-fsaverage5_thickness.shape.gii
-sub-01/anat/sub-01_hemi-R_space-fsaverage5_thickness.shape.gii
-sub-01/anat/sub-01_space-fsaverage5_thickness.json
-```
-
-```JSON
-{
-    "CoordinateSystem": "fsaverage5"
-}
-```
-
 Participant cortical thickness GIFTI file in `fsnative` coordinate space. Please
 mind that in this case `ReferenceMap` key is REQUIRED.
 
@@ -182,19 +168,6 @@ sub-01/anat/sub-01_hemi-L_space-fsnative_thickness.json
 }
 ```
 
-Preprocessed `bold` CIFTI file in `HCPMNIfsLR32k` coordinate space
-
-```Text
-sub-01/func/sub-01_task-rest_space-HCPMNIfsLR32k_bold.nii
-sub-01/func/sub-01_task-rest_space-HCPMNIfsLR32k_bold.json
-```
-
-```JSON
-{
-    "CoordinateSystem": "HCPMNIfsLR32k"
-}
-```
-
 ## Metadata conventions
 
 -   Unless specified otherwise, individual sidecar JSON files and all metadata

From 1c7d9dfb6883d01bf7d4024d385f5ee213bc24d6 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Sun, 17 Mar 2019 11:14:54 -0700
Subject: [PATCH 080/191] address Satra's comments

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

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 9297e86f15..96a4d06324 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -163,7 +163,6 @@ sub-01/anat/sub-01_hemi-L_space-fsnative_thickness.json
 
 ```JSON
 {
-    "CoordinateSystem": "fsnative",
     "ReferenceMap": "/sub-01/anat/sub-01_hemi-L_pial.surf.gii"
 }
 ```

From dc4b48a6eeb634cb23b78d4e44523d4b875c543f Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Wed, 20 Mar 2019 10:03:25 -0700
Subject: [PATCH 081/191] fix a link typo

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

diff --git a/src/05-derivatives/04-functional-derivatives.md b/src/05-derivatives/04-functional-derivatives.md
index 089f6feeb3..4807d38475 100644
--- a/src/05-derivatives/04-functional-derivatives.md
+++ b/src/05-derivatives/04-functional-derivatives.md
@@ -69,7 +69,7 @@ In addition, the following fields apply to the entire file in all cases:
 | StartTime         | OPTIONAL. Start time in seconds in relation to the start of acquisition of the first volume in the corresponding imaging file (negative values are allowed). |
 
 Note that there are several differences with these fields in
-[Physiological and other continuous recordings](../04-modality-specific-files/06-physiological-and-other-continous-recordings.md).
+[Physiological and other continuous recordings](../04-modality-specific-files/06-physiological-and-other-continuous-recordings.md).
 The `"TR"` sampling frequency serves to indicate that no resampling is needed
 to use the series as a regressor for BOLD data, including BOLD series with
 non-uniform sampling, such as clustered sparse acquisition.

From 900a2b0dd12268e406a62c4cb5917f736cff70c1 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Wed, 20 Mar 2019 10:20:20 -0700
Subject: [PATCH 082/191] removal of the Definition section in Coordinate
 Spaces appendix

---
 src/99-appendices/08-coordinate-systems.md | 42 ----------------------
 1 file changed, 42 deletions(-)

diff --git a/src/99-appendices/08-coordinate-systems.md b/src/99-appendices/08-coordinate-systems.md
index 50395a2bc9..a183804879 100644
--- a/src/99-appendices/08-coordinate-systems.md
+++ b/src/99-appendices/08-coordinate-systems.md
@@ -1,47 +1,5 @@
 # Appendix VIII: Preferred Names of Coordinate Systems
 
-## Definitions
-
-### Coordinate System
-
-A coordinate system specifies the information necessary to interpret the
-coordinates associated with the data. A coordinate system can be described by
-its topology (cartesian, spherical, polar, etc.,.), dimensionality, and units of
-measurement along each dimension. Every device that makes spatial measurements
-or has sensors described in a space has a coordinate system (e.g., an MR
-scanner, an MEG scanner, an EEG cap, Polhemus digitizer). The data output by
-most of these devices describe the number of dimensions, the units along each
-dimension, and in some cases the details of origin (for example, time).
-
-### Space, atlas and map
-
-A space/atlas/map is embedded in a coordinate system to ascribe meaning to the
-coordinates. For instance, Scanner, Talairach88, MNI, FS are different
-coordinate systems, while the Talairach atlas, MNI152, and fsaverage ascribe
-meaning to the coordinates in terms of brain anatomy. As an example to
-distinguish coordinate systems and spaces/atlas/maps, a 4D fMRI timeseries
-acquired without motion correction has individual time points all in the same
-coordinate system, but the atlas/map is different (due to motion) in different
-time points.
-
-### Landmarks
-
-Landmarks are properties of the object being measured and can exist in any
-coordinate system in which the object is placed/measured. They can be relevant
-points of the imaged object's structure (i.e. anatomical landmarks) such as the
-anterior commissure in a brain. They can also be fiducials that generate a
-localizable signal that are placed in the intended position before scanning
-(i.e. markers). Positions of landmarks are identified via manual or automated
-algorithms that detect these fiducials in (e.g., MR) or from (e.g., MEG) the
-acquired data or via explicit encoding of position (e.g., EEG sensors,
-headshape/coil digitization).
-
-These landmarks can be coordinates in a file or voxel/pixel intensity relations
-in image files.This information (coordinates or intensity relations)
-representing landmarks of the same or similar object (e.g., a template brain) in
-different coordinate systems can be used to transform the object between
-coordinate systems.
-
 ## Introduction
 
 To interpret a coordinate (x, y, z), it is required that you know relative to

From b0d15ddb26afb80eacbdc77eef59201cdd0b6814 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Wed, 20 Mar 2019 15:10:02 -0700
Subject: [PATCH 083/191] Update src/99-appendices/08-coordinate-systems.md

Co-Authored-By: chrisfilo <krzysztof.gorgolewski@gmail.com>
---
 src/99-appendices/08-coordinate-systems.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/99-appendices/08-coordinate-systems.md b/src/99-appendices/08-coordinate-systems.md
index e6b7525d88..220b27a04b 100644
--- a/src/99-appendices/08-coordinate-systems.md
+++ b/src/99-appendices/08-coordinate-systems.md
@@ -162,7 +162,7 @@ the units are assumed to be mm.
 
 | Coordinate System                                   | Description                                                                                                                                                                                                                                                                                                                                                      |
 | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| anat                                                | Participant specific anatomical space (for example derived from T1w and/or T2w images). This coordinate system require specifying an additional participant specific file to be fully defined.                                                                                                                                                                   |
+| anat                                                | Participant specific anatomical space (for example derived from T1w and/or T2w images). This coordinate system requires specifying an additional, participant-specific file to be fully defined.                                                                                                                                                                   |
 | FS305                                               | FreeSurfer variant of the MNI305 space                                                                                                                                                                                                                                                                                                                           |
 | MNI152Lin                                           | Also known as ICBM (version with linear coregistration) [http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152Lin](http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152Lin)                                                                                                                                                                                       |
 | MNI152NLin6\[Sym&#124;Asym\]                        | Also known as ICBM 6th generation (non-linear coregistration). Used by SPM99 - SPM8 and FSL (MNI152NLin6Sym). [http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin6](http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin6)                                                                                                                             |

From 08f6e8a27a963d9f042459d11d9ba96e85de015b Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Wed, 20 Mar 2019 15:10:17 -0700
Subject: [PATCH 084/191] Update src/99-appendices/08-coordinate-systems.md

Co-Authored-By: chrisfilo <krzysztof.gorgolewski@gmail.com>
---
 src/99-appendices/08-coordinate-systems.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/99-appendices/08-coordinate-systems.md b/src/99-appendices/08-coordinate-systems.md
index 220b27a04b..946d3f0dbb 100644
--- a/src/99-appendices/08-coordinate-systems.md
+++ b/src/99-appendices/08-coordinate-systems.md
@@ -183,7 +183,7 @@ the units are assumed to be mm.
 
 | Coordinate System                            | Description                                                                                                                                                                                                                                                                                                                 |
 | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| fsnative                                     | Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image. This coordinate system require specifying additional participant specific files to be fully defined.                                                                                                                              |
+| fsnative                                     | Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image. This coordinate system requires specifying additional, participant-specific files to be fully defined.                                                                                                                              |
 | fsaverage\[3&#124;4&#124;5&#124;6&#124;sym\] | Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image, and registered to an fsaverage template                                                                                                                                                                                           |
 | fsLR\[164k&#124;59k&#124;32k&#124;4k\]       | Images were sampled to the 164k (used by HCP pipelines for 3T and 7T anatomical analysis), 59k (used by HCP pipelines for 7T MRI bold and DWI analysis), 32k (used by HCP pipelines for 3T MRI bold and DWI analysis), or 4k (used by HCP pipelines for MEG analysis) fsaverage_LR surface reconstructed from the T1w image |
 

From 999723a26f4a5c354a871570db50361c9d2be53a Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Wed, 20 Mar 2019 15:42:26 -0700
Subject: [PATCH 085/191] fixes

---
 src/05-derivatives/01-introduction.md      | 2 +-
 src/99-appendices/08-coordinate-systems.md | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 96a4d06324..8e63d8c16f 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -126,7 +126,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.                                                                                                                                                                                                                |  |
+| 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.                                                                                                                                                                                                                |
 | ReferenceMap   | 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.                                                                                       |
 | ReferenceIndex | REQUIRED when an index into a 4D (ReferenceMap or NonstandardReference) file is used. Used to index into a 4D spatial-reference file.                                                                                                                                                                                                                 |
 
diff --git a/src/99-appendices/08-coordinate-systems.md b/src/99-appendices/08-coordinate-systems.md
index eded071a86..153b714298 100644
--- a/src/99-appendices/08-coordinate-systems.md
+++ b/src/99-appendices/08-coordinate-systems.md
@@ -120,7 +120,7 @@ the units are assumed to be mm.
 
 | Coordinate System                                   | Description                                                                                                                                                                                                                                                                                                                                                      |
 | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| anat                                                | Participant specific anatomical space (for example derived from T1w and/or T2w images). This coordinate system requires specifying an additional, participant-specific file to be fully defined.                                                                                                                                                                   |
+| anat                                                | Participant specific anatomical space (for example derived from T1w and/or T2w images). This coordinate system requires specifying an additional, participant-specific file to be fully defined.                                                                                                                                                                 |
 | FS305                                               | FreeSurfer variant of the MNI305 space                                                                                                                                                                                                                                                                                                                           |
 | MNI152Lin                                           | Also known as ICBM (version with linear coregistration) [http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152Lin](http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152Lin)                                                                                                                                                                                       |
 | MNI152NLin6\[Sym&#124;Asym\]                        | Also known as ICBM 6th generation (non-linear coregistration). Used by SPM99 - SPM8 and FSL (MNI152NLin6Sym). [http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin6](http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin6)                                                                                                                             |
@@ -141,7 +141,7 @@ the units are assumed to be mm.
 
 | Coordinate System                            | Description                                                                                                                                                                                                                                                                                                                 |
 | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| fsnative                                     | Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image. This coordinate system requires specifying additional, participant-specific files to be fully defined.                                                                                                                              |
+| fsnative                                     | Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image. This coordinate system requires specifying additional, participant-specific files to be fully defined.                                                                                                                            |
 | fsaverage\[3&#124;4&#124;5&#124;6&#124;sym\] | Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image, and registered to an fsaverage template                                                                                                                                                                                           |
 | fsLR\[164k&#124;59k&#124;32k&#124;4k\]       | Images were sampled to the 164k (used by HCP pipelines for 3T and 7T anatomical analysis), 59k (used by HCP pipelines for 7T MRI bold and DWI analysis), 32k (used by HCP pipelines for 3T MRI bold and DWI analysis), or 4k (used by HCP pipelines for MEG analysis) fsaverage_LR surface reconstructed from the T1w image |
 

From efd026d0b55322901d4a78eebd73143ad20f96bf Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Thu, 21 Mar 2019 16:16:46 -0700
Subject: [PATCH 086/191] adding desc to structural derivatives

---
 src/05-derivatives/03-structural-derivatives.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/05-derivatives/03-structural-derivatives.md b/src/05-derivatives/03-structural-derivatives.md
index 35f58ef2b7..c2ca59af55 100644
--- a/src/05-derivatives/03-structural-derivatives.md
+++ b/src/05-derivatives/03-structural-derivatives.md
@@ -11,7 +11,7 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         anat/
-            <source_keywords>_hemi-{L|R}[_space-<space>]_<surftype>.surf.gii
+            <source_keywords>_hemi-{L|R}[_space-<space>][_desc-<label>]_<surftype>.surf.gii
 ```
 
 Example:
@@ -51,7 +51,7 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         anat/
-            <source_keywords>[_hemi-{L|R}][_space-<space>]_<suffix>.{shape.gii|dscalar.nii}
+            <source_keywords>[_hemi-{L|R}][_space-<space>][_desc-<label>]_<suffix>.{shape.gii|dscalar.nii}
 ```
 
 The REQUIRED extension for scalar GIFTI files is `.shape.gii`. The `hemi` key is

From b97c7f0dc0a51c9e097e810ff477f659c92ffca4 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Thu, 21 Mar 2019 17:01:36 -0700
Subject: [PATCH 087/191] anat->native + cleanup

---
 src/05-derivatives/01-introduction.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 8e63d8c16f..ffef8e904d 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -97,7 +97,7 @@ keyword depend on the file format:
 
 | File format                  | Description             | Allowed `CoordinateSystem` values                                                                                                                                                           |
 | ---------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| NIfTI (`.nii` and `.nii.gz`) | Volume data             | Coordinate systems listed in [Template Based Coordinate Systems: Volume](../99-appendices/08-coordinate-systems.md#volume). If `anat` is used then setting `ReferenceMap` is REQUIRED       |
+| NIfTI (`.nii` and `.nii.gz`) | Volume data             | Coordinate systems listed in [Template Based Coordinate Systems: Volume](../99-appendices/08-coordinate-systems.md#volume). If `native` is used then setting `ReferenceMap` is REQUIRED       |
 | GIFTI (`.gii`)               | Surface data            | Coordinate systems listed in [Template Based Coordinate Systems: Surface](../99-appendices/08-coordinate-systems.md#surface). If `fsnative` is used then setting `ReferenceMap` is REQUIRED |
 | CIFTI (`.nii`)               | Volume and surface data | Coordinate systems listed in [Template Based Coordinate Systems: Hybrid (Volume/Surface) aliases](../99-appendices/08-coordinate-systems.md#hybrid-volumesurface-aliases)                   |
 
@@ -105,7 +105,7 @@ Examples:
 
 ```Text
 sub-01/func/sub-01_task-rest_space-MNI305_bold.nii.gz
-sub-01/func/sub-01_task-rest_space-anat_bold.nii.gz
+sub-01/func/sub-01_task-rest_space-native_bold.nii.gz
 sub-01/anat/sub-01_hemi-L_space-fsaverage5_thickness.shape.gii
 sub-01/anat/sub-01_hemi-R_space-fsaverage5_thickness.shape.gii
 sub-01/anat/sub-01_hemi-L_space-fsnative_thickness.shape.gii
@@ -143,8 +143,8 @@ Preprocessed `bold` NIfTI file in `anat` coordinate space. Please mind that in
 this case `ReferenceMap` key is REQUIRED.
 
 ```Text
-sub-01/func/sub-01_task-rest_space-anat_bold.nii.gz
-sub-01/func/sub-01_task-rest_space-anat_bold.json
+sub-01/func/sub-01_task-rest_space-native_bold.nii.gz
+sub-01/func/sub-01_task-rest_space-native_bold.json
 ```
 
 ```JSON

From 7f8fb994c13d0fe66c42446836c9a0da40cad627 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Thu, 21 Mar 2019 17:03:10 -0700
Subject: [PATCH 088/191] cleaning leftover anat's

---
 src/05-derivatives/01-introduction.md      | 2 +-
 src/99-appendices/08-coordinate-systems.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index ffef8e904d..ac51ad1743 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -139,7 +139,7 @@ share the following (non-required) ones:
 
 ### Examples
 
-Preprocessed `bold` NIfTI file in `anat` coordinate space. Please mind that in
+Preprocessed `bold` NIfTI file in `native` coordinate space. Please mind that in
 this case `ReferenceMap` key is REQUIRED.
 
 ```Text
diff --git a/src/99-appendices/08-coordinate-systems.md b/src/99-appendices/08-coordinate-systems.md
index 153b714298..679e0e7b4b 100644
--- a/src/99-appendices/08-coordinate-systems.md
+++ b/src/99-appendices/08-coordinate-systems.md
@@ -120,7 +120,7 @@ the units are assumed to be mm.
 
 | Coordinate System                                   | Description                                                                                                                                                                                                                                                                                                                                                      |
 | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| anat                                                | Participant specific anatomical space (for example derived from T1w and/or T2w images). This coordinate system requires specifying an additional, participant-specific file to be fully defined.                                                                                                                                                                 |
+| native                                              | Participant specific anatomical space (for example derived from T1w and/or T2w images). This coordinate system requires specifying an additional, participant-specific file to be fully defined.                                                                                                                                                                 |
 | FS305                                               | FreeSurfer variant of the MNI305 space                                                                                                                                                                                                                                                                                                                           |
 | MNI152Lin                                           | Also known as ICBM (version with linear coregistration) [http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152Lin](http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152Lin)                                                                                                                                                                                       |
 | MNI152NLin6\[Sym&#124;Asym\]                        | Also known as ICBM 6th generation (non-linear coregistration). Used by SPM99 - SPM8 and FSL (MNI152NLin6Sym). [http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin6](http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin6)                                                                                                                             |

From 26653c914e9d78df9a85e352c3a61d182f14e0e8 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Thu, 21 Mar 2019 17:06:55 -0700
Subject: [PATCH 089/191] fix syntax

---
 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 ac51ad1743..c802fb694a 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -97,7 +97,7 @@ keyword depend on the file format:
 
 | File format                  | Description             | Allowed `CoordinateSystem` values                                                                                                                                                           |
 | ---------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| NIfTI (`.nii` and `.nii.gz`) | Volume data             | Coordinate systems listed in [Template Based Coordinate Systems: Volume](../99-appendices/08-coordinate-systems.md#volume). If `native` is used then setting `ReferenceMap` is REQUIRED       |
+| NIfTI (`.nii` and `.nii.gz`) | Volume data             | Coordinate systems listed in [Template Based Coordinate Systems: Volume](../99-appendices/08-coordinate-systems.md#volume). If `native` is used then setting `ReferenceMap` is REQUIRED     |
 | GIFTI (`.gii`)               | Surface data            | Coordinate systems listed in [Template Based Coordinate Systems: Surface](../99-appendices/08-coordinate-systems.md#surface). If `fsnative` is used then setting `ReferenceMap` is REQUIRED |
 | CIFTI (`.nii`)               | Volume and surface data | Coordinate systems listed in [Template Based Coordinate Systems: Hybrid (Volume/Surface) aliases](../99-appendices/08-coordinate-systems.md#hybrid-volumesurface-aliases)                   |
 

From 3878971f18f4f6871c5e1e33464364903b4bbbcc Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Thu, 21 Mar 2019 19:08:22 -0700
Subject: [PATCH 090/191] clarify links between raw and derived datasets

---
 src/02-common-principles.md | 65 +++++++++++++++++++------------------
 1 file changed, 34 insertions(+), 31 deletions(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index 3dfc31a501..a6c3c7e9b6 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -75,39 +75,32 @@ spec.
 
 ## Source vs. raw vs. derived data
 
-BIDS in its current form is designed to harmonize and describe raw (unprocessed
+BIDS originally was designed to harmonize and describe raw (unprocessed
 or minimally processed due to file format conversion) data. During analysis such
 data will be transformed and partial as well as final results will be saved.
 Derivatives of the raw data (other than products of DICOM to NIfTI conversion)
 MUST be kept separate from the raw data. This way one can protect the raw data
 from accidental changes by file permissions. In addition it is easy to
-distinguish partial results from the raw data and share the latter. Similar
-rules apply to source data which is defined as data before harmonization and/or
-file format conversion (for example E-Prime event logs or DICOM files).
-
-This specification currently does not go into details of recommending a
-particular naming scheme for including different types of source data (raw event
-logs, parameter files, etc. before conversion to BIDS) and data derivatives
-(correlation maps, brain masks, contrasts maps, etc.). However, in the case that
-these data are to be included:
-
-1.  These data MUST be kept in separate `sourcedata` and `derivatives` folders
-    each with a similar folder structure as presented below for the BIDS-managed
-    data. For example:
-    `derivatives/fmriprep/sub-01/ses-pre/sub-01_ses-pre_mask.nii.gz` or
+distinguish partial results from the raw data and share the latter. You can read
+more about organizing derivatives [here](05-derivatives/01-introduction.md).
+
+Similar rules apply to source data which is defined as data before 
+harmonization and/or file format conversion (for example E-Prime event logs or 
+DICOM files). This specification currently does not go into details of 
+recommending a particular naming scheme for including different types of 
+source data (raw event logs, parameter files, etc. before conversion to BIDS). 
+However, in the case that these data are to be included:
+
+1.  These data MUST be kept in separate `sourcedata` folder with a similar 
+    folder structure as presented below for the BIDS-managed data. For example:
     `sourcedata/sub-01/ses-pre/func/sub-01_ses-pre_task-rest_bold.dicom.tgz` or
     `sourcedata/sub-01/ses-pre/func/MyEvent.sce`.
 
-1.  A README file SHOULD be found at the root of the `sourcedata` or the
-    `derivatives` folder (or both). This file should describe the nature of the
-    raw data or the derived data. In the case of the existence of a
-    `derivatives` folder, we RECOMMEND including details about the software
-    stack and settings used to generate the results. Inclusion of non-imaging
-    objects that improve reproducibility are encouraged (scripts, settings
-    files, etc.).
-
-1.  We RECOMMEND including the PDF print-out with the actual sequence parameters
-    generated by the scanner in the `sourcedata` folder.
+1.  A README file SHOULD be found at the root of the `sourcedata` folder 
+    (or both). This file should describe the nature of the
+    raw data or the derived data. We RECOMMEND including the PDF print-out with 
+    the actual sequence parameters generated by the scanner in the `sourcedata` 
+    folder.
 
 Alternatively one can organize their data in the following way
 
@@ -122,15 +115,25 @@ my_dataset/
     sub-02/
     ...
   derivatives/
+    pipeline_1/
+    pipeline_2/
     ...
 ```
 
-In this example **only the `rawdata` subfolder needs to be BIDS compliant** 
-dataset. This specification does not prescribe anything about the contents of 
-`sourcedata` and `derivatives` folders in the above example - nor does it 
-prescribe the `sourcedata`, `derivatives`, or `rawdata` folder names. The above 
-example is just a convention that can be useful for organizing raw, source, and 
-derived data while maintaining BIDS compliancy of the raw data folder.
+In this example ** only `rawdata` subfolder and all subfolders of `derivatives` 
+need to be BIDS compliant** datasets. This specification does not prescribe 
+anything about the contents of `sourcedata` folders in the above example - nor 
+does it prescribe the `sourcedata`, `derivatives`, or `rawdata` folder names. 
+The above example is just a convention that can be useful for organizing raw, 
+source, and derived data while maintaining BIDS compliancy of the raw data 
+folder. When using this convention it is RECOMMENDED to set the `SourceDatasets`
+field in `dataset_description.json` of each subfolder of `derivatives` to:
+
+```JSON
+{
+  "SourceDatasets": [ {"URL": "file://../../rawdata/"} ]
+}
+```
 
 ## The Inheritance Principle
 

From fd1fb89e100ae34a600b0ad390aa6593df22581d Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Thu, 21 Mar 2019 19:22:30 -0700
Subject: [PATCH 091/191] fixes

---
 src/02-common-principles.md | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index a6c3c7e9b6..59e43923c7 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -120,8 +120,8 @@ my_dataset/
     ...
 ```
 
-In this example ** only `rawdata` subfolder and all subfolders of `derivatives` 
-need to be BIDS compliant** datasets. This specification does not prescribe 
+In this example **only `rawdata` subfolder and all subfolders of `derivatives`**
+**need to be BIDS compliant** datasets. This specification does not prescribe 
 anything about the contents of `sourcedata` folders in the above example - nor 
 does it prescribe the `sourcedata`, `derivatives`, or `rawdata` folder names. 
 The above example is just a convention that can be useful for organizing raw, 
@@ -135,6 +135,9 @@ field in `dataset_description.json` of each subfolder of `derivatives` to:
 }
 ```
 
+See [Derived dataset and pipeline description](05-derivatives/01-introduction.md#Derived-dataset-and-pipeline-description)
+for more information.
+
 ## The Inheritance Principle
 
 Any metadata file (`.json`, `.bvec`, `.tsv`, etc.) may be defined at any

From 93b2e1737d93db580ac0f3927a8ecf347eaccb73 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Sun, 24 Mar 2019 16:26:49 -0700
Subject: [PATCH 092/191] native -> individual

---
 src/05-derivatives/01-introduction.md      | 32 +++++++++++-----------
 src/99-appendices/08-coordinate-systems.md |  4 +--
 2 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index c802fb694a..ab652e31f9 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -95,21 +95,21 @@ 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 on the file format:
 
-| File format                  | Description             | Allowed `CoordinateSystem` values                                                                                                                                                           |
-| ---------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| NIfTI (`.nii` and `.nii.gz`) | Volume data             | Coordinate systems listed in [Template Based Coordinate Systems: Volume](../99-appendices/08-coordinate-systems.md#volume). If `native` is used then setting `ReferenceMap` is REQUIRED     |
-| GIFTI (`.gii`)               | Surface data            | Coordinate systems listed in [Template Based Coordinate Systems: Surface](../99-appendices/08-coordinate-systems.md#surface). If `fsnative` is used then setting `ReferenceMap` is REQUIRED |
-| CIFTI (`.nii`)               | Volume and surface data | Coordinate systems listed in [Template Based Coordinate Systems: Hybrid (Volume/Surface) aliases](../99-appendices/08-coordinate-systems.md#hybrid-volumesurface-aliases)                   |
+| File format                  | Description             | Allowed `CoordinateSystem` values                                                                                                                                                             |
+| ---------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| NIfTI (`.nii` and `.nii.gz`) | Volume data             | Coordinate systems listed in [Template Based Coordinate Systems: Volume](../99-appendices/08-coordinate-systems.md#volume). If `individual` is used then setting `ReferenceMap` is REQUIRED   |
+| GIFTI (`.gii`)               | Surface data            | Coordinate systems listed in [Template Based Coordinate Systems: Surface](../99-appendices/08-coordinate-systems.md#surface). If `individual` is used then setting `ReferenceMap` is REQUIRED |
+| CIFTI (`.nii`)               | Volume and surface data | Coordinate systems listed in [Template Based Coordinate Systems: Hybrid (Volume/Surface) aliases](../99-appendices/08-coordinate-systems.md#hybrid-volumesurface-aliases)                     |
 
 Examples:
 
 ```Text
 sub-01/func/sub-01_task-rest_space-MNI305_bold.nii.gz
-sub-01/func/sub-01_task-rest_space-native_bold.nii.gz
+sub-01/func/sub-01_task-rest_space-individual_bold.nii.gz
 sub-01/anat/sub-01_hemi-L_space-fsaverage5_thickness.shape.gii
 sub-01/anat/sub-01_hemi-R_space-fsaverage5_thickness.shape.gii
-sub-01/anat/sub-01_hemi-L_space-fsnative_thickness.shape.gii
-sub-01/anat/sub-01_hemi-R_space-fsnative_thickness.shape.gii
+sub-01/anat/sub-01_hemi-L_space-individual_thickness.shape.gii
+sub-01/anat/sub-01_hemi-R_space-individual_thickness.shape.gii
 sub-01/func/sub-01_task-rest_space-HCPMNIfsLR32k_bold.nii
 ```
 
@@ -139,12 +139,12 @@ share the following (non-required) ones:
 
 ### Examples
 
-Preprocessed `bold` NIfTI file in `native` coordinate space. Please mind that in
-this case `ReferenceMap` key is REQUIRED.
+Preprocessed `bold` NIfTI file in `individual` coordinate space. Please mind
+that in this case `ReferenceMap` key is REQUIRED.
 
 ```Text
-sub-01/func/sub-01_task-rest_space-native_bold.nii.gz
-sub-01/func/sub-01_task-rest_space-native_bold.json
+sub-01/func/sub-01_task-rest_space-individual_bold.nii.gz
+sub-01/func/sub-01_task-rest_space-individual_bold.json
 ```
 
 ```JSON
@@ -153,12 +153,12 @@ sub-01/func/sub-01_task-rest_space-native_bold.json
 }
 ```
 
-Participant cortical thickness GIFTI file in `fsnative` coordinate space. Please
-mind that in this case `ReferenceMap` key is REQUIRED.
+Participant cortical thickness GIFTI file in `individual` coordinate space.
+Please mind that in this case `ReferenceMap` key is REQUIRED.
 
 ```Text
-sub-01/anat/sub-01_hemi-L_space-fsnative_thickness.shape.gii
-sub-01/anat/sub-01_hemi-L_space-fsnative_thickness.json
+sub-01/anat/sub-01_hemi-L_space-individual_thickness.shape.gii
+sub-01/anat/sub-01_hemi-L_space-individual_thickness.json
 ```
 
 ```JSON
diff --git a/src/99-appendices/08-coordinate-systems.md b/src/99-appendices/08-coordinate-systems.md
index 679e0e7b4b..5d632fc5e0 100644
--- a/src/99-appendices/08-coordinate-systems.md
+++ b/src/99-appendices/08-coordinate-systems.md
@@ -120,7 +120,7 @@ the units are assumed to be mm.
 
 | Coordinate System                                   | Description                                                                                                                                                                                                                                                                                                                                                      |
 | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| native                                              | Participant specific anatomical space (for example derived from T1w and/or T2w images). This coordinate system requires specifying an additional, participant-specific file to be fully defined.                                                                                                                                                                 |
+| individual                                          | Participant specific anatomical space (for example derived from T1w and/or T2w images). This coordinate system requires specifying an additional, participant-specific file to be fully defined.                                                                                                                                                                 |
 | FS305                                               | FreeSurfer variant of the MNI305 space                                                                                                                                                                                                                                                                                                                           |
 | MNI152Lin                                           | Also known as ICBM (version with linear coregistration) [http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152Lin](http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152Lin)                                                                                                                                                                                       |
 | MNI152NLin6\[Sym&#124;Asym\]                        | Also known as ICBM 6th generation (non-linear coregistration). Used by SPM99 - SPM8 and FSL (MNI152NLin6Sym). [http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin6](http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin6)                                                                                                                             |
@@ -141,7 +141,7 @@ the units are assumed to be mm.
 
 | Coordinate System                            | Description                                                                                                                                                                                                                                                                                                                 |
 | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| fsnative                                     | Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image. This coordinate system requires specifying additional, participant-specific files to be fully defined.                                                                                                                            |
+| individual                                   | Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image. This coordinate system requires specifying additional, participant-specific files to be fully defined.                                                                                                                            |
 | fsaverage\[3&#124;4&#124;5&#124;6&#124;sym\] | Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image, and registered to an fsaverage template                                                                                                                                                                                           |
 | fsLR\[164k&#124;59k&#124;32k&#124;4k\]       | Images were sampled to the 164k (used by HCP pipelines for 3T and 7T anatomical analysis), 59k (used by HCP pipelines for 7T MRI bold and DWI analysis), 32k (used by HCP pipelines for 3T MRI bold and DWI analysis), or 4k (used by HCP pipelines for MEG analysis) fsaverage_LR surface reconstructed from the T1w image |
 

From bbb27a462fe6cbdfcebc217424a04f58c54b3c52 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Sun, 24 Mar 2019 16:34:05 -0700
Subject: [PATCH 093/191] bringing back custom space

---
 src/05-derivatives/01-introduction.md      | 10 +++++-----
 src/99-appendices/08-coordinate-systems.md |  9 +++++++--
 2 files changed, 12 insertions(+), 7 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index ab652e31f9..61cf7572b2 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -95,11 +95,11 @@ 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 on the file format:
 
-| File format                  | Description             | Allowed `CoordinateSystem` values                                                                                                                                                             |
-| ---------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| NIfTI (`.nii` and `.nii.gz`) | Volume data             | Coordinate systems listed in [Template Based Coordinate Systems: Volume](../99-appendices/08-coordinate-systems.md#volume). If `individual` is used then setting `ReferenceMap` is REQUIRED   |
-| GIFTI (`.gii`)               | Surface data            | Coordinate systems listed in [Template Based Coordinate Systems: Surface](../99-appendices/08-coordinate-systems.md#surface). If `individual` is used then setting `ReferenceMap` is REQUIRED |
-| CIFTI (`.nii`)               | Volume and surface data | Coordinate systems listed in [Template Based Coordinate Systems: Hybrid (Volume/Surface) aliases](../99-appendices/08-coordinate-systems.md#hybrid-volumesurface-aliases)                     |
+| File format                  | Description             | Allowed `CoordinateSystem` values                                                                                                                                                                         |
+| ---------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| NIfTI (`.nii` and `.nii.gz`) | Volume data             | Coordinate systems listed in [Template Based Coordinate Systems: Volume](../99-appendices/08-coordinate-systems.md#volume). If `individual` or `custom` is used then setting `ReferenceMap` is REQUIRED   |
+| GIFTI (`.gii`)               | Surface data            | Coordinate systems listed in [Template Based Coordinate Systems: Surface](../99-appendices/08-coordinate-systems.md#surface). If `individual` or `custom` is used then setting `ReferenceMap` is REQUIRED |
+| CIFTI (`.nii`)               | Volume and surface data | Coordinate systems listed in [Template Based Coordinate Systems: Hybrid (Volume/Surface) aliases](../99-appendices/08-coordinate-systems.md#hybrid-volumesurface-aliases)                                 |
 
 Examples:
 
diff --git a/src/99-appendices/08-coordinate-systems.md b/src/99-appendices/08-coordinate-systems.md
index 5d632fc5e0..246f60d830 100644
--- a/src/99-appendices/08-coordinate-systems.md
+++ b/src/99-appendices/08-coordinate-systems.md
@@ -116,11 +116,17 @@ below, the origin is at the AC and the orientation of the axes is RAS. Unless
 specified explicitly in the sidecar file in the `XXCoordinateSystemUnits` field,
 the units are assumed to be mm.
 
+### Common for Surface and Volume
+
+| Coordinate System | Description                                                                                                                                                                                                                                                           |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| individual        | Participant specific anatomical space (for example derived from T1w and/or T2w images). This coordinate system requires specifying an additional, participant-specific file to be fully defined. In context of surfaces this space has been refered to as `fsnative`. |
+| custom            | Custom space defined using a group/study-specific template. This coordinate system requires specifying an additional file to be fully defined.                                                                                                                        |
+
 ### Volume
 
 | Coordinate System                                   | Description                                                                                                                                                                                                                                                                                                                                                      |
 | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| individual                                          | Participant specific anatomical space (for example derived from T1w and/or T2w images). This coordinate system requires specifying an additional, participant-specific file to be fully defined.                                                                                                                                                                 |
 | FS305                                               | FreeSurfer variant of the MNI305 space                                                                                                                                                                                                                                                                                                                           |
 | MNI152Lin                                           | Also known as ICBM (version with linear coregistration) [http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152Lin](http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152Lin)                                                                                                                                                                                       |
 | MNI152NLin6\[Sym&#124;Asym\]                        | Also known as ICBM 6th generation (non-linear coregistration). Used by SPM99 - SPM8 and FSL (MNI152NLin6Sym). [http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin6](http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin6)                                                                                                                             |
@@ -141,7 +147,6 @@ the units are assumed to be mm.
 
 | Coordinate System                            | Description                                                                                                                                                                                                                                                                                                                 |
 | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| individual                                   | Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image. This coordinate system requires specifying additional, participant-specific files to be fully defined.                                                                                                                            |
 | fsaverage\[3&#124;4&#124;5&#124;6&#124;sym\] | Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image, and registered to an fsaverage template                                                                                                                                                                                           |
 | fsLR\[164k&#124;59k&#124;32k&#124;4k\]       | Images were sampled to the 164k (used by HCP pipelines for 3T and 7T anatomical analysis), 59k (used by HCP pipelines for 7T MRI bold and DWI analysis), 32k (used by HCP pipelines for 3T MRI bold and DWI analysis), or 4k (used by HCP pipelines for MEG analysis) fsaverage_LR surface reconstructed from the T1w image |
 

From ccc33be00b3e6975ea31a1b90b9fa90f5f052e62 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Sun, 24 Mar 2019 16:46:19 -0700
Subject: [PATCH 094/191] add volspace for meshes

---
 src/05-derivatives/03-structural-derivatives.md | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/src/05-derivatives/03-structural-derivatives.md b/src/05-derivatives/03-structural-derivatives.md
index c2ca59af55..a4ba033f8f 100644
--- a/src/05-derivatives/03-structural-derivatives.md
+++ b/src/05-derivatives/03-structural-derivatives.md
@@ -11,7 +11,7 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         anat/
-            <source_keywords>_hemi-{L|R}[_space-<space>][_desc-<label>]_<surftype>.surf.gii
+            <source_keywords>_hemi-{L|R}[_space-<surfspace>][_volspace-<volspace>][_desc-<label>]_<surftype>.surf.gii
 ```
 
 Example:
@@ -37,8 +37,15 @@ The supported surface types (`<surftype>` suffix) are:
 | sphere       | The sphere (used for registration - see transforms for nomenclature) |
 | flat         | The flattened surface (used for visualization)                       |
 
-Note: reconstructed cortical surfaces are unique in that they contain both
-2-dimensional and 3-dimensional elements of "space".
+`space` filename keyword is restricted to
+[Surface Coordinate Spaces](../99-appendices/08-coordinate-spaces.md#Surface)
+and `volspace` corresponds to the 3D coordinate space described in
+[Volume Coordinate Spaces](../99-appendices/08-coordinate-spaces.md#Volume). In
+contrast to other derivatives the sidecar metadata field `ReferenceMap` (see
+[Introduction](01-introduction.md#Common-file-level-metadata-fields)) is not
+required for any space, but is recommended when `volspace` is set to
+`individual`. In such case it should point to the volume defining the 3D
+coordinate system with witch the surface mesh is aligned with.
 
 ## Surface-Mapped Anatomical Scalar Derivatives
 

From 319b5806026d782096c0225c49bb0f2599686480 Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Sun, 24 Mar 2019 16:55:51 -0700
Subject: [PATCH 095/191] fixes

---
 src/05-derivatives/02-common-data-types.md      | 3 +--
 src/05-derivatives/03-structural-derivatives.md | 4 ++--
 2 files changed, 3 insertions(+), 4 deletions(-)

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index 4f81e653d1..88f3e01d29 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -23,8 +23,7 @@ data types in the specification. Examples:
 -   Motion-corrected DWI files.
 
 The `space` keyword is recomended to distinguish files with different underlying
-coordinate systems or registered to different reference maps. Its values are
-restricted to the same vocabulary as `ReferenceMap` JSON field (see below). The
+coordinate systems or registered to different reference maps. The
 `desc` keyword is a general purpose field with freeform values. To distinguish
 between multiple different versions of processing for the same input data the
 `desc` keyword should be used. Note that even though `space` and `desc` are
diff --git a/src/05-derivatives/03-structural-derivatives.md b/src/05-derivatives/03-structural-derivatives.md
index a4ba033f8f..df1863c964 100644
--- a/src/05-derivatives/03-structural-derivatives.md
+++ b/src/05-derivatives/03-structural-derivatives.md
@@ -38,9 +38,9 @@ The supported surface types (`<surftype>` suffix) are:
 | flat         | The flattened surface (used for visualization)                       |
 
 `space` filename keyword is restricted to
-[Surface Coordinate Spaces](../99-appendices/08-coordinate-spaces.md#Surface)
+[Surface Coordinate Spaces](../99-appendices/08-coordinate-systems.md#Surface)
 and `volspace` corresponds to the 3D coordinate space described in
-[Volume Coordinate Spaces](../99-appendices/08-coordinate-spaces.md#Volume). In
+[Volume Coordinate Spaces](../99-appendices/08-coordinate-systems.md#Volume). In
 contrast to other derivatives the sidecar metadata field `ReferenceMap` (see
 [Introduction](01-introduction.md#Common-file-level-metadata-fields)) is not
 required for any space, but is recommended when `volspace` is set to

From fcb7967ff19d50dd4dc1a39320885e660d392c3e Mon Sep 17 00:00:00 2001
From: Chris Gorgolewski <krzysztof.gorgolewski@gmail.com>
Date: Fri, 29 Mar 2019 18:05:48 -0700
Subject: [PATCH 096/191] ReferenceMap -> SpatialReference

---
 src/05-derivatives/01-introduction.md         | 34 +++++++++----------
 .../03-structural-derivatives.md              |  2 +-
 2 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 61cf7572b2..d3e3b6d0e0 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -95,11 +95,11 @@ 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 on the file format:
 
-| File format                  | Description             | Allowed `CoordinateSystem` values                                                                                                                                                                         |
-| ---------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| NIfTI (`.nii` and `.nii.gz`) | Volume data             | Coordinate systems listed in [Template Based Coordinate Systems: Volume](../99-appendices/08-coordinate-systems.md#volume). If `individual` or `custom` is used then setting `ReferenceMap` is REQUIRED   |
-| GIFTI (`.gii`)               | Surface data            | Coordinate systems listed in [Template Based Coordinate Systems: Surface](../99-appendices/08-coordinate-systems.md#surface). If `individual` or `custom` is used then setting `ReferenceMap` is REQUIRED |
-| CIFTI (`.nii`)               | Volume and surface data | Coordinate systems listed in [Template Based Coordinate Systems: Hybrid (Volume/Surface) aliases](../99-appendices/08-coordinate-systems.md#hybrid-volumesurface-aliases)                                 |
+| File format                  | Description             | Allowed `CoordinateSystem` values                                                                                                                                                                             |
+| ---------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| NIfTI (`.nii` and `.nii.gz`) | Volume data             | Coordinate systems listed in [Template Based Coordinate Systems: Volume](../99-appendices/08-coordinate-systems.md#volume). If `individual` or `custom` is used then setting `SpatialReference` is REQUIRED   |
+| GIFTI (`.gii`)               | Surface data            | Coordinate systems listed in [Template Based Coordinate Systems: Surface](../99-appendices/08-coordinate-systems.md#surface). If `individual` or `custom` is used then setting `SpatialReference` is REQUIRED |
+| CIFTI (`.nii`)               | Volume and surface data | Coordinate systems listed in [Template Based Coordinate Systems: Hybrid (Volume/Surface) aliases](../99-appendices/08-coordinate-systems.md#hybrid-volumesurface-aliases)                                     |
 
 Examples:
 
@@ -122,15 +122,15 @@ derivative includes REQUIRED metadata fields in which case a JSON file is also
 REQUIRED. Each derivative type defines their own set of fields, but all of them
 share the following (non-required) ones:
 
-| **Key name**   | **Description**                                                                                                                                                                                                                                                                                                                                       |
-| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 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.                                                                                                                                                                                                                |
-| ReferenceMap   | 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.                                                                                       |
-| ReferenceIndex | REQUIRED when an index into a 4D (ReferenceMap or NonstandardReference) file is used. Used to index into a 4D spatial-reference file.                                                                                                                                                                                                                 |
+| **Key name**     | **Description**                                                                                                                                                                                                                                                                                                                                       |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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.                                                                                                                                                                                                                |
+| 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.                                                                                       |
+| ReferenceIndex   | REQUIRED when an index into a 4D (SpatialReference) file is used. Used to index into a 4D spatial-reference file.                                                                                                                                                                                                                                     |
 
-### ReferenceMap key allowed values
+### SpatialReference key allowed values
 
 | **Value name** | **Description**                                                                                                               |
 | -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
@@ -140,7 +140,7 @@ share the following (non-required) ones:
 ### Examples
 
 Preprocessed `bold` NIfTI file in `individual` coordinate space. Please mind
-that in this case `ReferenceMap` key is REQUIRED.
+that in this case `SpatialReference` key is REQUIRED.
 
 ```Text
 sub-01/func/sub-01_task-rest_space-individual_bold.nii.gz
@@ -149,12 +149,12 @@ sub-01/func/sub-01_task-rest_space-individual_bold.json
 
 ```JSON
 {
-    "ReferenceMap": "/sub-01/anat/sub-01_desc-combined_T1w.nii.gz"
+    "SpatialReference": "/sub-01/anat/sub-01_desc-combined_T1w.nii.gz"
 }
 ```
 
 Participant cortical thickness GIFTI file in `individual` coordinate space.
-Please mind that in this case `ReferenceMap` key is REQUIRED.
+Please mind that in this case `SpatialReference` key is REQUIRED.
 
 ```Text
 sub-01/anat/sub-01_hemi-L_space-individual_thickness.shape.gii
@@ -163,7 +163,7 @@ sub-01/anat/sub-01_hemi-L_space-individual_thickness.json
 
 ```JSON
 {
-    "ReferenceMap": "/sub-01/anat/sub-01_hemi-L_pial.surf.gii"
+    "SpatialReference": "/sub-01/anat/sub-01_hemi-L_pial.surf.gii"
 }
 ```
 
diff --git a/src/05-derivatives/03-structural-derivatives.md b/src/05-derivatives/03-structural-derivatives.md
index df1863c964..e35d9797fe 100644
--- a/src/05-derivatives/03-structural-derivatives.md
+++ b/src/05-derivatives/03-structural-derivatives.md
@@ -41,7 +41,7 @@ The supported surface types (`<surftype>` suffix) are:
 [Surface Coordinate Spaces](../99-appendices/08-coordinate-systems.md#Surface)
 and `volspace` corresponds to the 3D coordinate space described in
 [Volume Coordinate Spaces](../99-appendices/08-coordinate-systems.md#Volume). In
-contrast to other derivatives the sidecar metadata field `ReferenceMap` (see
+contrast to other derivatives the sidecar metadata field `SpatialReference` (see
 [Introduction](01-introduction.md#Common-file-level-metadata-fields)) is not
 required for any space, but is recommended when `volspace` is set to
 `individual`. In such case it should point to the volume defining the 3D

From 74ff6d0f3d67cf1935c819be8794e690576a41db Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Wed, 24 Apr 2019 13:52:54 +1000
Subject: [PATCH 097/191] Diffusion derivatives: Further fixes for #205

- Minor spelling & grammar fixes.
- In "scalar maps" section, expand out the different parameters to be derived from the ball-and-stick(s) model.
- Provide more accurate link to MRtrix3 tracks file format.
---
 .../05-diffusion-derivatives.md               | 47 ++++++++++---------
 1 file changed, 26 insertions(+), 21 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 172f5d4cfc..000791346e 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -32,7 +32,7 @@ Additional reserved JSON metadata fields:
 | MotionCorrection               | OPTIONAL. Boolean. Motion correction                                                                                         |
 | EddyCurrentCorrection          | OPTIONAL. Boolean. Eddy currents corrections                                                                                 |
 | IntensityNormalizationMethod   | OPTIONAL. String. Method (if any) used for intensity normalization                                                           |
-| FieldInhomogeneityCorrection   | OPTIONAL. Boolean. Correction for geometric distrotions arising from magnetic field inhomogeneity                            |
+| FieldInhomogeneityCorrection   | OPTIONAL. Boolean. Correction for geometric distortions arising from magnetic field inhomogeneity                            |
 | GradientNonLinearityCorrection | OPTIONAL. String. Correction for non-linear gradients; allowed values: `none`, `geometry`, `gradients`, `geometry&gradients` |
 
 ## Diffusion Models (and input parameters)
@@ -71,7 +71,7 @@ version of the specification.
 | `WMTI`      | White matter tract integrity (Fieremans et al., 2011)                                          | 4D image with Dxx, Dxy, Dxz, Dyy, Dyz, Dzz, Wxxxx, Wyyy, Wzzzz, Wxxxy, Wxxxz, Wxyyy, Wyyyz, Wxzzz, Wyzzz, Wxxyy, Wxxzz, Wyyzz, Wxxyz, Wxyyz, Wxyzz, Dhxx, Dhxy, Dhxz, Dhyy, Dhyz, Dhzz, Drxx, Drxy, Drxz, Dryy, Dryz, Drzz, AWF; where D is the diffusion tensor, W is the kurtosis tensor, AWF is the additional axonal water fraction parameter                                                                                      |
 | `CSD`       | Constrained Spherical Deconvolution (Tournier et al. 2007; Descoteaux et al. 2009)             | 4D image with spherical harmonic (SH) coefficients (number of volumes and their ordering depends on the model maximal degree and basis set, specified in the sidecar)                                                                                                                                                                                                                                                                  |
 | `NODDI`     | Neurite Orientation Dispersion and Density Imaging (Zhang et al. 2012, Daducci et al., 2015)   | Three 3D images, with <parameter> equal to {`ICVF`,`OD`,`ISOVF`}: ICVF is the “intracellular volume fraction” (also known as NDI); OD is the “orientation dispersion” (the variance of the Bingham; also known as ODI); ISOVF is the isotropic component volume fraction (also known as IVF). Additionally a vector-valued map with the parameter name "`direction`" may provide the XYZ direction of the estimated fibre orientation. |
-| `DSI`       | Diffusion Spectrum Imaging (Wedeen et al. 2008; Paquette et al 2017)                           | DSI is generally used mostly to compute the diffusion ODF (Orientation Distribution Function). No parameters are generally returned, but an ODF can be saved as a map.                                                                                                                                                                                                                                                                 |
+| `DSI`       | Diffusion Spectrum Imaging (Wedeen et al. 2008; Paquette et al 2017)                           | DSI is generally used to compute the diffusion ODF (Orientation Distribution Function). No parameters are generally returned, but an ODF can be saved as a map.                                                                                                                                                                                                                                                                        |
 | `CSA`       | Constant solid angle (Aganj et al. 2010)                                                       | 4D image with SH coefficients (number of volumes and their ordering depends on the model maximal degree and basis set, specified in the side-car)                                                                                                                                                                                                                                                                                      |
 | `SHORE`     | Simple Harmonic Oscillator based Reconstruction and Estimation. (Ozarslan et al. 2008)         | 4D image with basis coefficients depending on choice of basis.                                                                                                                                                                                                                                                                                                                                                                         |
 | `MAPMRI`    | Mean Apparent Propagator MRI. (Ozarslan, 2013)                                                 | 4D image with basis coefficients depending on choice of basis.                                                                                                                                                                                                                                                                                                                                                                         |
@@ -268,23 +268,28 @@ fields for the maps.
 
 These maps are saved 3D NIfTI files (x,y,z). Some examples of such maps are as follows:
 
-| `<parameter>` value | Description                                                        | Possible Model sources                                                                                                       | Unit or scale                                                                                                          |
-| ------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| FA                  | Fractional Anisotropy                                              | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   | Unitless \[0-1\]                                                                                                       |
-| MD                  | Mean diffusivity (also called apparent diffusion coefficient, ADC) | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   | microns^2/ms (for example, for free water in body temperature, this should be approximately 3)                         |
-| AD                  | Axial Diffusivity (also called parallel diffusivity)               | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   | microns^2/ms (for example, for free water in body temperature, this should be approximately 3)                         |
-| RD                  | Radial Diffusivity (also called perpendicular diffusivity)         | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   | microns^2/ms (for example, for free water in body temperature, this should be approximately 3)                         |
-| MODE                | Mode of the tensor                                                 | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   |                                                                                                                        |
-| LINEARITY           | Tensor linearity (Westin 1997)                                     | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   |                                                                                                                        |
-| PLANARITY           | Tensor planarity (Westin 1997)                                     | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   |                                                                                                                        |
-| SPHERICITY          | Tensor sphericity (Westin 1997)                                    | DTI, DKI, WMTI (D, Dh, Dr)                                                                                                   |                                                                                                                        |
-| MK                  | Mean kurtosis                                                      | DKI, WMTI                                                                                                                    | Unitless                                                                                                               |
-| RK                  | Radial kurtosis                                                    | DKI, WMTI                                                                                                                    | Unitless                                                                                                               |
-| AK                  | Axial kurtosis                                                     | DKI, WMTI                                                                                                                    | Unitless                                                                                                               |
-| GFA                 | Generalized Fractional Anisotropy                                  | CSA, CSD, SHORE, MAPMRI, Forecast (or any model that can be represented as an ODF)                                           | Proportion \[0 - 1\]                                                                                                   |
-| INDEX               | Scalar maps from bedpostx                                          | FSUM (sum of partial volume fractions of the sticks)F_i (volume fraction of stick i)D (diffusivity)DSTD (std of diffusivity) | FSUM \[0 - 1\]F_i \[0 - 1\]D and DSTD microns^2/ms (for example, for free water in body temperature, this should be 3) |
-| RTPP                | Return to the plane probability                                    | MAPMRI                                                                                                                       | Probability \[0 - 1\]                                                                                                  |
-| RTAP                | Return to axis probability                                         | MAPMRI                                                                                                                       | Probability \[0 - 1\]                                                                                                  |
+| `<parameter>` value | Description                                                        | Possible Model sources                                                             | Unit or scale           |
+| ------------------- | ------------------------------------------------------------------ | -----------------------------------------------------------------------------------| ----------------------- |
+| FA                  | Fractional Anisotropy                                              | DTI, DKI, WMTI (D, Dh, Dr)                                                         | Unitless \[0-1\]        |
+| MD                  | Mean diffusivity (also called apparent diffusion coefficient, ADC) | DTI, DKI, WMTI (D, Dh, Dr)                                                         | microns^2/ms ^1         |
+| AD                  | Axial Diffusivity (also called parallel diffusivity)               | DTI, DKI, WMTI (D, Dh, Dr)                                                         | microns^2/ms ^1         |
+| RD                  | Radial Diffusivity (also called perpendicular diffusivity)         | DTI, DKI, WMTI (D, Dh, Dr)                                                         | microns^2/ms ^1         |
+| MODE                | Mode of the tensor                                                 | DTI, DKI, WMTI (D, Dh, Dr)                                                         |                         |
+| LINEARITY           | Tensor linearity (Westin 1997)                                     | DTI, DKI, WMTI (D, Dh, Dr)                                                         |                         |
+| PLANARITY           | Tensor planarity (Westin 1997)                                     | DTI, DKI, WMTI (D, Dh, Dr)                                                         |                         |
+| SPHERICITY          | Tensor sphericity (Westin 1997)                                    | DTI, DKI, WMTI (D, Dh, Dr)                                                         |                         |
+| MK                  | Mean kurtosis                                                      | DKI, WMTI                                                                          | Unitless                |
+| RK                  | Radial kurtosis                                                    | DKI, WMTI                                                                          | Unitless                |
+| AK                  | Axial kurtosis                                                     | DKI, WMTI                                                                          | Unitless                |
+| GFA                 | Generalized Fractional Anisotropy                                  | CSA, CSD, SHORE, MAPMRI, Forecast (or any model that can be represented as an ODF) | Proportion \[0-1\]      |
+| FSUM                | Sum of partial volume fractions of stick components                | Ball-and-stick(s)                                                                  | Volume fraction \[0-1\] |
+| Fi                  | Volume fraction of stick i                                         | Ball-and-stick(s)                                                                  | Volume fraction \[0-1\] |
+| D                   | Diffusivity                                                        | Ball-and-stick(s)                                                                  | microns^2/ms ^1         |
+| DSTD                | Standard deviation of diffusivity                                  | Ball-and-stick(s)                                                                  | microns^2/ms            |
+| RTPP                | Return to the plane probability                                    | MAPMRI                                                                             | Probability \[0-1\]     |
+| RTAP                | Return to axis probability                                         | MAPMRI                                                                             | Probability \[0-1\]     |
+
+^1 For example, for free water in body temperature, the diffusivity in units of microns^2/ms should be approximately 3.0.
 
 ### Directionally-encoded colour (DEC) maps
 
@@ -307,7 +312,7 @@ tensor model is coloured according to the direction of the principal eigenvector
 
 ### Vector-valued maps
 
-These maps are saved 4D NIfTI files (x,y,z, 3\*n), where each triplet of volumes
+These maps are saved as 4D NIfTI files (x,y,z, 3\*n), where each triplet of volumes
 encodes both a direction in 3D space and some quantitiative value (these are
 sometimes referred to as "fixels"). The number of volumes in the image must be
 3 times the maximal number of fixels that can appear in any voxel in the image
@@ -356,7 +361,7 @@ kept, or `subsampled50` if only 50% of the streamlines were kept.
 ### File formats
 
 -   [.trk - Diffusion Toolkit (+TrackVis)](https://web.archive.org/web/20190103230122/http://www.trackvis.org/docs/?subsect=fileformat)
--   [.tck - MRtrix](https://web.archive.org/web/20190103230209/https://mrtrix.readthedocs.io/en/latest/getting_started/image_data.html)
+-   [.tck - MRtrix](https://web.archive.org/web/20190103230209/https://mrtrix.readthedocs.io/en/latest/getting_started/image_data.html#tracks-file-format-tck)
 
 ### JSON Metadata
 

From 1d0613e920db31cb184cb512398d627c7cd1560e Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Wed, 24 Apr 2019 14:06:49 +1000
Subject: [PATCH 098/191] Diffusion derivatives: Formatting

- Fix use of superscripts in "Scalar maps" table.
- For "Units" field in tractography JSON file, list possible values in the same format as that used elsewhere in the document.
---
 .../05-diffusion-derivatives.md               | 64 +++++++++----------
 1 file changed, 32 insertions(+), 32 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 000791346e..a985cb95da 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -268,28 +268,28 @@ fields for the maps.
 
 These maps are saved 3D NIfTI files (x,y,z). Some examples of such maps are as follows:
 
-| `<parameter>` value | Description                                                        | Possible Model sources                                                             | Unit or scale           |
-| ------------------- | ------------------------------------------------------------------ | -----------------------------------------------------------------------------------| ----------------------- |
-| FA                  | Fractional Anisotropy                                              | DTI, DKI, WMTI (D, Dh, Dr)                                                         | Unitless \[0-1\]        |
-| MD                  | Mean diffusivity (also called apparent diffusion coefficient, ADC) | DTI, DKI, WMTI (D, Dh, Dr)                                                         | microns^2/ms ^1         |
-| AD                  | Axial Diffusivity (also called parallel diffusivity)               | DTI, DKI, WMTI (D, Dh, Dr)                                                         | microns^2/ms ^1         |
-| RD                  | Radial Diffusivity (also called perpendicular diffusivity)         | DTI, DKI, WMTI (D, Dh, Dr)                                                         | microns^2/ms ^1         |
-| MODE                | Mode of the tensor                                                 | DTI, DKI, WMTI (D, Dh, Dr)                                                         |                         |
-| LINEARITY           | Tensor linearity (Westin 1997)                                     | DTI, DKI, WMTI (D, Dh, Dr)                                                         |                         |
-| PLANARITY           | Tensor planarity (Westin 1997)                                     | DTI, DKI, WMTI (D, Dh, Dr)                                                         |                         |
-| SPHERICITY          | Tensor sphericity (Westin 1997)                                    | DTI, DKI, WMTI (D, Dh, Dr)                                                         |                         |
-| MK                  | Mean kurtosis                                                      | DKI, WMTI                                                                          | Unitless                |
-| RK                  | Radial kurtosis                                                    | DKI, WMTI                                                                          | Unitless                |
-| AK                  | Axial kurtosis                                                     | DKI, WMTI                                                                          | Unitless                |
-| GFA                 | Generalized Fractional Anisotropy                                  | CSA, CSD, SHORE, MAPMRI, Forecast (or any model that can be represented as an ODF) | Proportion \[0-1\]      |
-| FSUM                | Sum of partial volume fractions of stick components                | Ball-and-stick(s)                                                                  | Volume fraction \[0-1\] |
-| Fi                  | Volume fraction of stick i                                         | Ball-and-stick(s)                                                                  | Volume fraction \[0-1\] |
-| D                   | Diffusivity                                                        | Ball-and-stick(s)                                                                  | microns^2/ms ^1         |
-| DSTD                | Standard deviation of diffusivity                                  | Ball-and-stick(s)                                                                  | microns^2/ms            |
-| RTPP                | Return to the plane probability                                    | MAPMRI                                                                             | Probability \[0-1\]     |
-| RTAP                | Return to axis probability                                         | MAPMRI                                                                             | Probability \[0-1\]     |
-
-^1 For example, for free water in body temperature, the diffusivity in units of microns^2/ms should be approximately 3.0.
+| `<parameter>` value | Description                                                        | Possible Model sources                                                             | Unit or scale                       |
+| ------------------- | ------------------------------------------------------------------ | -----------------------------------------------------------------------------------| ----------------------------------- |
+| FA                  | Fractional Anisotropy                                              | DTI, DKI, WMTI (D, Dh, Dr)                                                         | Unitless \[0-1\]                    |
+| MD                  | Mean diffusivity (also called apparent diffusion coefficient, ADC) | DTI, DKI, WMTI (D, Dh, Dr)                                                         | microns<sup>2<\sup>/ms <sup>1<\sup> |
+| AD                  | Axial Diffusivity (also called parallel diffusivity)               | DTI, DKI, WMTI (D, Dh, Dr)                                                         | microns<sup>2<\sup>/ms <sup>1<\sup> |
+| RD                  | Radial Diffusivity (also called perpendicular diffusivity)         | DTI, DKI, WMTI (D, Dh, Dr)                                                         | microns<sup>2<\sup>/ms <sup>1<\sup> |
+| MODE                | Mode of the tensor                                                 | DTI, DKI, WMTI (D, Dh, Dr)                                                         |                                     |
+| LINEARITY           | Tensor linearity (Westin 1997)                                     | DTI, DKI, WMTI (D, Dh, Dr)                                                         |                                     |
+| PLANARITY           | Tensor planarity (Westin 1997)                                     | DTI, DKI, WMTI (D, Dh, Dr)                                                         |                                     |
+| SPHERICITY          | Tensor sphericity (Westin 1997)                                    | DTI, DKI, WMTI (D, Dh, Dr)                                                         |                                     |
+| MK                  | Mean kurtosis                                                      | DKI, WMTI                                                                          | Unitless                            |
+| RK                  | Radial kurtosis                                                    | DKI, WMTI                                                                          | Unitless                            |
+| AK                  | Axial kurtosis                                                     | DKI, WMTI                                                                          | Unitless                            |
+| GFA                 | Generalized Fractional Anisotropy                                  | CSA, CSD, SHORE, MAPMRI, Forecast (or any model that can be represented as an ODF) | Proportion \[0-1\]                  |
+| FSUM                | Sum of partial volume fractions of stick components                | Ball-and-stick(s)                                                                  | Volume fraction \[0-1\]             |
+| Fi                  | Volume fraction of stick i                                         | Ball-and-stick(s)                                                                  | Volume fraction \[0-1\]             |
+| D                   | Diffusivity                                                        | Ball-and-stick(s)                                                                  | microns<sup>2<\sup>/ms <sup>1<\sup> |
+| DSTD                | Standard deviation of diffusivity                                  | Ball-and-stick(s)                                                                  | microns<sup>2<\sup>/ms              |
+| RTPP                | Return to the plane probability                                    | MAPMRI                                                                             | Probability \[0-1\]                 |
+| RTAP                | Return to axis probability                                         | MAPMRI                                                                             | Probability \[0-1\]                 |
+
+<sup>1<\sup> For example, for free water in body temperature, the diffusivity in units of microns<sup>2<\sup>/ms should be approximately 3.0.
 
 ### Directionally-encoded colour (DEC) maps
 
@@ -406,16 +406,16 @@ RECOMMENDED to appear within the "`Constraints`" field when "`TractographyClass`
 
 RECOMMENDED to appear within the "`Parameters`" field when "`TractographyClass`" is "`local`":
 
-| **Key name**      | **Description**                                    |
-| ----------------- | -------------------------------------------------- |
-| Units             | "mm","norm" (applies to all within "`Parameters`") |
-| StepSize          | value                                              |
-| AngleCurvature    | value (maximum angle per step)                     |
-| RadiusCurvature   | value (minimal radius of curvature)                |
-| MinimumLength     | value                                              |
-| MaximumLength     | value                                              |
-| IntegrationOrder  | integer                                            |
-| Unidirectional    | bool                                               |
+| **Key name**      | **Description**                                      |
+| ----------------- | ---------------------------------------------------- |
+| Units             | {`mm`,`norm`} (applies to all within "`Parameters`") |
+| StepSize          | value                                                |
+| AngleCurvature    | value (maximum angle per step)                       |
+| RadiusCurvature   | value (minimal radius of curvature)                  |
+| MinimumLength     | value                                                |
+| MaximumLength     | value                                                |
+| IntegrationOrder  | integer                                              |
+| Unidirectional    | bool                                                 |
 
 RECOMMENDED to appear within the "Seeding" field when `TractographyClass` is `local`:
 

From 41ecca4f4a9f8def0fd9098496d32e36dca2e7b2 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Wed, 24 Apr 2019 14:09:11 +1000
Subject: [PATCH 099/191] Diffusion derivatives: Further fix of superscript
 usage

Follows 1d0613e9.
---
 src/05-derivatives/05-diffusion-derivatives.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index a985cb95da..2e2914e70e 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -271,9 +271,9 @@ These maps are saved 3D NIfTI files (x,y,z). Some examples of such maps are as f
 | `<parameter>` value | Description                                                        | Possible Model sources                                                             | Unit or scale                       |
 | ------------------- | ------------------------------------------------------------------ | -----------------------------------------------------------------------------------| ----------------------------------- |
 | FA                  | Fractional Anisotropy                                              | DTI, DKI, WMTI (D, Dh, Dr)                                                         | Unitless \[0-1\]                    |
-| MD                  | Mean diffusivity (also called apparent diffusion coefficient, ADC) | DTI, DKI, WMTI (D, Dh, Dr)                                                         | microns<sup>2<\sup>/ms <sup>1<\sup> |
-| AD                  | Axial Diffusivity (also called parallel diffusivity)               | DTI, DKI, WMTI (D, Dh, Dr)                                                         | microns<sup>2<\sup>/ms <sup>1<\sup> |
-| RD                  | Radial Diffusivity (also called perpendicular diffusivity)         | DTI, DKI, WMTI (D, Dh, Dr)                                                         | microns<sup>2<\sup>/ms <sup>1<\sup> |
+| MD                  | Mean diffusivity (also called apparent diffusion coefficient, ADC) | DTI, DKI, WMTI (D, Dh, Dr)                                                         | microns<sup>2</sup>/ms <sup>1</sup> |
+| AD                  | Axial Diffusivity (also called parallel diffusivity)               | DTI, DKI, WMTI (D, Dh, Dr)                                                         | microns<sup>2</sup>/ms <sup>1</sup> |
+| RD                  | Radial Diffusivity (also called perpendicular diffusivity)         | DTI, DKI, WMTI (D, Dh, Dr)                                                         | microns<sup>2</sup>/ms <sup>1</sup> |
 | MODE                | Mode of the tensor                                                 | DTI, DKI, WMTI (D, Dh, Dr)                                                         |                                     |
 | LINEARITY           | Tensor linearity (Westin 1997)                                     | DTI, DKI, WMTI (D, Dh, Dr)                                                         |                                     |
 | PLANARITY           | Tensor planarity (Westin 1997)                                     | DTI, DKI, WMTI (D, Dh, Dr)                                                         |                                     |
@@ -284,12 +284,12 @@ These maps are saved 3D NIfTI files (x,y,z). Some examples of such maps are as f
 | GFA                 | Generalized Fractional Anisotropy                                  | CSA, CSD, SHORE, MAPMRI, Forecast (or any model that can be represented as an ODF) | Proportion \[0-1\]                  |
 | FSUM                | Sum of partial volume fractions of stick components                | Ball-and-stick(s)                                                                  | Volume fraction \[0-1\]             |
 | Fi                  | Volume fraction of stick i                                         | Ball-and-stick(s)                                                                  | Volume fraction \[0-1\]             |
-| D                   | Diffusivity                                                        | Ball-and-stick(s)                                                                  | microns<sup>2<\sup>/ms <sup>1<\sup> |
-| DSTD                | Standard deviation of diffusivity                                  | Ball-and-stick(s)                                                                  | microns<sup>2<\sup>/ms              |
+| D                   | Diffusivity                                                        | Ball-and-stick(s)                                                                  | microns<sup>2</sup>/ms <sup>1</sup> |
+| DSTD                | Standard deviation of diffusivity                                  | Ball-and-stick(s)                                                                  | microns<sup>2</sup>/ms              |
 | RTPP                | Return to the plane probability                                    | MAPMRI                                                                             | Probability \[0-1\]                 |
 | RTAP                | Return to axis probability                                         | MAPMRI                                                                             | Probability \[0-1\]                 |
 
-<sup>1<\sup> For example, for free water in body temperature, the diffusivity in units of microns<sup>2<\sup>/ms should be approximately 3.0.
+<sup>1</sup> For example, for free water in body temperature, the diffusivity in units of microns<sup>2</sup>/ms should be approximately 3.0.
 
 ### Directionally-encoded colour (DEC) maps
 

From fd9a57244e36e2427d23b594ae620d8a4b21fbcd Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Wed, 24 Apr 2019 14:22:31 +1000
Subject: [PATCH 100/191] Diffusion derivatives: Fix error in DKI & WMTI model
 descriptions

---
 src/05-derivatives/05-diffusion-derivatives.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 2e2914e70e..6db082ad20 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -67,8 +67,8 @@ version of the specification.
 | Model label | Name & citation                                                                                | Description                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | ----------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `DTI`       | Diffusion tensor imaging (Basser et al. 1994)                                                  | 4D image with Dxx, Dxy, Dxz, Dyy, Dyz, Dzz; the 6 unique parameters of the diffusion tensor.                                                                                                                                                                                                                                                                                                                                           |
-| `DKI`       | Diffusion kurtosis imaging (Jensen et al., 2005)                                               | 4D image with Dxx, Dxy, Dxz, Dyy, Dyz, Dzz, Wxxxx, Wyyy, Wzzzz, Wxxxy, Wxxxz, Wxyyy, Wyyyz, Wxzzz, Wyzzz, Wxxyy, Wxxzz, Wyyzz, Wxxyz, Wxyyz, Wxyzz; Where D is the diffusion tensor and W is the kurtosis tensor.                                                                                                                                                                                                                      |
-| `WMTI`      | White matter tract integrity (Fieremans et al., 2011)                                          | 4D image with Dxx, Dxy, Dxz, Dyy, Dyz, Dzz, Wxxxx, Wyyy, Wzzzz, Wxxxy, Wxxxz, Wxyyy, Wyyyz, Wxzzz, Wyzzz, Wxxyy, Wxxzz, Wyyzz, Wxxyz, Wxyyz, Wxyzz, Dhxx, Dhxy, Dhxz, Dhyy, Dhyz, Dhzz, Drxx, Drxy, Drxz, Dryy, Dryz, Drzz, AWF; where D is the diffusion tensor, W is the kurtosis tensor, AWF is the additional axonal water fraction parameter                                                                                      |
+| `DKI`       | Diffusion kurtosis imaging (Jensen et al., 2005)                                               | 4D image with Dxx, Dxy, Dxz, Dyy, Dyz, Dzz, Wxxxx, Wyyyy, Wzzzz, Wxxxy, Wxxxz, Wxyyy, Wyyyz, Wxzzz, Wyzzz, Wxxyy, Wxxzz, Wyyzz, Wxxyz, Wxyyz, Wxyzz; Where D is the diffusion tensor and W is the kurtosis tensor.                                                                                                                                                                                                                      |
+| `WMTI`      | White matter tract integrity (Fieremans et al., 2011)                                          | 4D image with Dxx, Dxy, Dxz, Dyy, Dyz, Dzz, Wxxxx, Wyyyy, Wzzzz, Wxxxy, Wxxxz, Wxyyy, Wyyyz, Wxzzz, Wyzzz, Wxxyy, Wxxzz, Wyyzz, Wxxyz, Wxyyz, Wxyzz, Dhxx, Dhxy, Dhxz, Dhyy, Dhyz, Dhzz, Drxx, Drxy, Drxz, Dryy, Dryz, Drzz, AWF; where D is the diffusion tensor, W is the kurtosis tensor, AWF is the additional axonal water fraction parameter                                                                                      |
 | `CSD`       | Constrained Spherical Deconvolution (Tournier et al. 2007; Descoteaux et al. 2009)             | 4D image with spherical harmonic (SH) coefficients (number of volumes and their ordering depends on the model maximal degree and basis set, specified in the sidecar)                                                                                                                                                                                                                                                                  |
 | `NODDI`     | Neurite Orientation Dispersion and Density Imaging (Zhang et al. 2012, Daducci et al., 2015)   | Three 3D images, with <parameter> equal to {`ICVF`,`OD`,`ISOVF`}: ICVF is the “intracellular volume fraction” (also known as NDI); OD is the “orientation dispersion” (the variance of the Bingham; also known as ODI); ISOVF is the isotropic component volume fraction (also known as IVF). Additionally a vector-valued map with the parameter name "`direction`" may provide the XYZ direction of the estimated fibre orientation. |
 | `DSI`       | Diffusion Spectrum Imaging (Wedeen et al. 2008; Paquette et al 2017)                           | DSI is generally used to compute the diffusion ODF (Orientation Distribution Function). No parameters are generally returned, but an ODF can be saved as a map.                                                                                                                                                                                                                                                                        |

From 6f788a50d5ff7d6ff2e76034767b3a6c83940661 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Wed, 24 Apr 2019 14:22:53 +1000
Subject: [PATCH 101/191] Diffusion derivatives: Use subscripts in model
 descriptions

---
 .../05-diffusion-derivatives.md               | 28 +++++++++----------
 1 file changed, 14 insertions(+), 14 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 6db082ad20..79ecce21ad 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -64,20 +64,20 @@ field. If a new model is used, common sense should be used to derive a name
 following the BIDS standard, and should ideally be integrated in a follow-up
 version of the specification.
 
-| Model label | Name & citation                                                                                | Description                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| ----------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `DTI`       | Diffusion tensor imaging (Basser et al. 1994)                                                  | 4D image with Dxx, Dxy, Dxz, Dyy, Dyz, Dzz; the 6 unique parameters of the diffusion tensor.                                                                                                                                                                                                                                                                                                                                           |
-| `DKI`       | Diffusion kurtosis imaging (Jensen et al., 2005)                                               | 4D image with Dxx, Dxy, Dxz, Dyy, Dyz, Dzz, Wxxxx, Wyyyy, Wzzzz, Wxxxy, Wxxxz, Wxyyy, Wyyyz, Wxzzz, Wyzzz, Wxxyy, Wxxzz, Wyyzz, Wxxyz, Wxyyz, Wxyzz; Where D is the diffusion tensor and W is the kurtosis tensor.                                                                                                                                                                                                                      |
-| `WMTI`      | White matter tract integrity (Fieremans et al., 2011)                                          | 4D image with Dxx, Dxy, Dxz, Dyy, Dyz, Dzz, Wxxxx, Wyyyy, Wzzzz, Wxxxy, Wxxxz, Wxyyy, Wyyyz, Wxzzz, Wyzzz, Wxxyy, Wxxzz, Wyyzz, Wxxyz, Wxyyz, Wxyzz, Dhxx, Dhxy, Dhxz, Dhyy, Dhyz, Dhzz, Drxx, Drxy, Drxz, Dryy, Dryz, Drzz, AWF; where D is the diffusion tensor, W is the kurtosis tensor, AWF is the additional axonal water fraction parameter                                                                                      |
-| `CSD`       | Constrained Spherical Deconvolution (Tournier et al. 2007; Descoteaux et al. 2009)             | 4D image with spherical harmonic (SH) coefficients (number of volumes and their ordering depends on the model maximal degree and basis set, specified in the sidecar)                                                                                                                                                                                                                                                                  |
-| `NODDI`     | Neurite Orientation Dispersion and Density Imaging (Zhang et al. 2012, Daducci et al., 2015)   | Three 3D images, with <parameter> equal to {`ICVF`,`OD`,`ISOVF`}: ICVF is the “intracellular volume fraction” (also known as NDI); OD is the “orientation dispersion” (the variance of the Bingham; also known as ODI); ISOVF is the isotropic component volume fraction (also known as IVF). Additionally a vector-valued map with the parameter name "`direction`" may provide the XYZ direction of the estimated fibre orientation. |
-| `DSI`       | Diffusion Spectrum Imaging (Wedeen et al. 2008; Paquette et al 2017)                           | DSI is generally used to compute the diffusion ODF (Orientation Distribution Function). No parameters are generally returned, but an ODF can be saved as a map.                                                                                                                                                                                                                                                                        |
-| `CSA`       | Constant solid angle (Aganj et al. 2010)                                                       | 4D image with SH coefficients (number of volumes and their ordering depends on the model maximal degree and basis set, specified in the side-car)                                                                                                                                                                                                                                                                                      |
-| `SHORE`     | Simple Harmonic Oscillator based Reconstruction and Estimation. (Ozarslan et al. 2008)         | 4D image with basis coefficients depending on choice of basis.                                                                                                                                                                                                                                                                                                                                                                         |
-| `MAPMRI`    | Mean Apparent Propagator MRI. (Ozarslan, 2013)                                                 | 4D image with basis coefficients depending on choice of basis.                                                                                                                                                                                                                                                                                                                                                                         |
-| `FORECAST`  | Fiber ORientation Estimated using Continuous Axially Symmetric Tensors. (Zuchelli et al. 2017) | 4D image with SH coefficients.                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `fwDTI`     | Free water DTI (Hoy et al. 2014)                                                               | One 4D image with parameter name "`tensor`", containing 6 volumes in the order D_c_xx, D_c_xy, D_c_xz, D_c_yy, D_c_yz, D_c_zz, where D_c is the fw-corrected diffusion tensor in each voxel; one 3D image with parameter name "`FWF`" corresponding to the free water fraction in each voxel. .                                                                                                                                        |
-| `BedpostX`  | Ball-and-Stick model (Behrens et al. 2007; Jabdbi et al, MRM 2012)                             | 5D image (xyz, m, n) for m parameters and n MCMC samples (n=1 implies best-fit parameters). Parameters are f_i, th_i, ph_i (volume fraction, polar angle, azimuthal angle) for up to 3 fibres, d, d_std (for “multiexponential” model)                                                                                                                                                                                                 |
+| Model label | Name & citation                                                                                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| ----------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DTI`       | Diffusion tensor imaging (Basser et al. 1994)                                                  | 4D image with D<sub>xx</sub>, D<sub>xy</sub>, D<sub>xz</sub>, D<sub>yy</sub>, D<sub>yz</sub>, D<sub>zz</sub>; the 6 unique parameters of the diffusion tensor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `DKI`       | Diffusion kurtosis imaging (Jensen et al., 2005)                                               | 4D image with D<sub>xx</sub>, D<sub>xy</sub>, D<sub>xz</sub>, D<sub>yy</sub>, D<sub>yz</sub>, D<sub>zz</sub>, W<sub>xxxx</sub>, W<sub>yyyy</sub>, W<sub>zzzz</sub>, W<sub>xxxy</sub>, W<sub>xxxz</sub>, W<sub>xyyy</sub>, W<sub>yyyz</sub>, W<sub>xzzz</sub>, W<sub>yzzz</sub>, W<sub>xxyy</sub>, W<sub>xxzz</sub>, W<sub>yyzz</sub>, W<sub>xxyz</sub>, W<sub>xyyz</sub>, W<sub>xyzz</sub>; Where D is the diffusion tensor and W is the kurtosis tensor.                                                                                                                                                                                                                                                                     |
+| `WMTI`      | White matter tract integrity (Fieremans et al., 2011)                                          | 4D image with D<sub>xx</sub>, D<sub>xy</sub>, D<sub>xz</sub>, D<sub>yy</sub>, D<sub>yz</sub>, D<sub>zz</sub>, W<sub>xxxx</sub>, W<sub>yyyy</sub>, W<sub>zzzz</sub>, W<sub>xxxy</sub>, W<sub>xxxz</sub>, W<sub>xyyy</sub>, W<sub>yyyz</sub>, W<sub>xzzz</sub>, W<sub>yzzz</sub>, W<sub>xxyy</sub>, W<sub>xxzz</sub>, W<sub>yyzz</sub>, W<sub>xxyz</sub>, W<sub>xyyz</sub>, W<sub>xyzz</sub>, Dh<sub>xx</sub>, Dh<sub>xy</sub>, Dh<sub>xz</sub>, Dh<sub>yy</sub>, Dh<sub>yz</sub>, Dh<sub>zz</sub>, Dr<sub>xx</sub>, Dr<sub>xy</sub>, Dr<sub>xz</sub>, Dr<sub>yy</sub>, Dr<sub>yz</sub>, Dr<sub>zz</sub>, AWF; where D is the diffusion tensor, W is the kurtosis tensor, AWF is the additional axonal water fraction parameter |
+| `CSD`       | Constrained Spherical Deconvolution (Tournier et al. 2007; Descoteaux et al. 2009)             | 4D image with spherical harmonic (SH) coefficients (number of volumes and their ordering depends on the model maximal degree and basis set, specified in the sidecar)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `NODDI`     | Neurite Orientation Dispersion and Density Imaging (Zhang et al. 2012, Daducci et al., 2015)   | Three 3D images, with <parameter> equal to {`ICVF`,`OD`,`ISOVF`}: ICVF is the “intracellular volume fraction” (also known as NDI); OD is the “orientation dispersion” (the variance of the Bingham; also known as ODI); ISOVF is the isotropic component volume fraction (also known as IVF). Additionally a vector-valued map with the parameter name "`direction`" may provide the XYZ direction of the estimated fibre orientation.                                                                                                                                                                                                                                                                                        |
+| `DSI`       | Diffusion Spectrum Imaging (Wedeen et al. 2008; Paquette et al 2017)                           | DSI is generally used to compute the diffusion ODF (Orientation Distribution Function). No parameters are generally returned, but an ODF can be saved as a map.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `CSA`       | Constant solid angle (Aganj et al. 2010)                                                       | 4D image with SH coefficients (number of volumes and their ordering depends on the model maximal degree and basis set, specified in the side-car)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `SHORE`     | Simple Harmonic Oscillator based Reconstruction and Estimation. (Ozarslan et al. 2008)         | 4D image with basis coefficients depending on choice of basis.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `MAPMRI`    | Mean Apparent Propagator MRI. (Ozarslan, 2013)                                                 | 4D image with basis coefficients depending on choice of basis.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `FORECAST`  | Fiber ORientation Estimated using Continuous Axially Symmetric Tensors. (Zuchelli et al. 2017) | 4D image with SH coefficients.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `fwDTI`     | Free water DTI (Hoy et al. 2014)                                                               | One 4D image with parameter name "`tensor`", containing 6 volumes in the order Dc<sub>xx</sub>, Dc<sub>xy</sub>, Dc<sub>xz</sub>, Dc<sub>yy</sub>, Dc<sub>yz</sub>, Dc<sub>zz</sub>, where Dc is the fw-corrected diffusion tensor in each voxel; one 3D image with parameter name "`FWF`" corresponding to the free water fraction in each voxel. .                                                                                                                                                                                                                                                                                                                                                                          |
+| `BedpostX`  | Ball-and-Stick model (Behrens et al. 2007; Jabdbi et al, MRM 2012)                             | 5D image (xyz, m, n) for m parameters and n MCMC samples (n=1 implies best-fit parameters). Parameters are f<sub>i</sub>, th<sub>i</sub>, ph<sub>i</sub> (volume fraction, polar angle, azimuthal angle) for up to 3 fibres, D, D<sub>std</sub> (for “multiexponential” model)                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 
 The JSON sidecar contains the following key/value pairs common for all models:
 

From f28ba08ac3d6c5853b6fa9f7c2488edf91fe7ece Mon Sep 17 00:00:00 2001
From: Yaroslav Halchenko <debian@onerussian.com>
Date: Tue, 30 Apr 2019 11:11:40 -0400
Subject: [PATCH 102/191] DOC: really minor typo

---
 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 d3e3b6d0e0..b8551013a3 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -54,7 +54,7 @@ As for any BIDS dataset a `dataset_description.json` file MUST be found at the
 top level of the particular pipeline:
 `<dataset>/derivatives/<pipeline_name>/dataset_description.json`
 
-In addition to raw BIDS datasets derived BIDS datasets includ the following
+In addition to raw BIDS datasets derived BIDS datasets include the following
 required or recommended `dataset_description.json` keys (a dot in the Key name
 denotes a key in a subdictionary):
 

From d44d712a55f244b8de14b30ca591b4445aed5938 Mon Sep 17 00:00:00 2001
From: Yaroslav Halchenko <debian@onerussian.com>
Date: Thu, 9 May 2019 09:24:21 -0400
Subject: [PATCH 103/191] ENH: use <label> for _desc- - not some <value> +
 clarify <value>

---
 src/05-derivatives/01-introduction.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index b8551013a3..138a729eed 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -195,6 +195,8 @@ sub-01/anat/sub-01_hemi-L_space-individual_thickness.json
 
 -   Each Derivatives filename MUST be of the form:
     `<source_keywords>[_keyword-<value>]_<suffix>.<ext>`
+    (where `<value>` could either be an `<index>` or a `<label>` depending on
+    the keyword)
 
 -   When the derivatives chain involves outputs derived from a single raw input,
     `source_keywords` MUST be the entire source filename, with the ommission of
@@ -209,7 +211,7 @@ sub-01/anat/sub-01_hemi-L_space-individual_thickness.json
     create and use the sidecar JSON files to detail the specifics of individual
     files.
 
--   When necessary to distinguish two files, the `_desc-<value>` keyword-value
+-   When necessary to distinguish two files, the `_desc-<label>` keyword-value
     should be used. This includes the cases of needing to distinguish both
     differing inputs and differing outputs (e.g., `_desc-T1w` and `_desc-T2w` to
     distinguish brain mask files derived from T1w and T2w images; or `_desc-sm4`

From 50690653e78bf744b69b5b6200ba9abaff282d35 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Tue, 28 May 2019 11:02:42 -0400
Subject: [PATCH 104/191] FIX: Apply suggestions from @sappelhoff review

---
 CODEOWNERS                            |  5 ++--
 src/02-common-principles.md           |  9 ++++---
 src/05-derivatives/01-introduction.md | 34 ++++++++++++++-------------
 3 files changed, 24 insertions(+), 24 deletions(-)

diff --git a/CODEOWNERS b/CODEOWNERS
index a547d92f01..ce07f9ca43 100644
--- a/CODEOWNERS
+++ b/CODEOWNERS
@@ -11,10 +11,9 @@
 # Individual sections
 /src/01-common-principles.md @chrisgorgo @DimitriPapadopoulos
 /src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md @chrisgorgo
-/src/04-modality-specific-files/03-electroencephalography.md @sappelhoff
+/src/04-modality-specific-files/03-electroencephalography.md @sappelhoff @ezemikulan
+/src/04-modality-specific-files/04-intracranial-electroencephalography.md @ezemikulan
 /src/05-derivatives/03-structural-derivatives.md @edickie @ahoopes
 /src/05-derivatives/04-functional-derivatives.md @effigies
 /src/05-derivatives/05-diffusion-derivatives.md @francopestilli @oesteban
-/src/04-modality-specific-files/03-electroencephalography.md @sappelhoff @ezemikulan
-/src/04-modality-specific-files/04-intracranial-electroencephalography.md @ezemikulan
 /src/99-appendices/06-meg-file-formats.md @monkeyman192
diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index 967d74079e..d901da8524 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -96,11 +96,10 @@ However, in the case that these data are to be included:
     `sourcedata/sub-01/ses-pre/func/sub-01_ses-pre_task-rest_bold.dicom.tgz` or
     `sourcedata/sub-01/ses-pre/func/MyEvent.sce`.
 
-1.  A README file SHOULD be found at the root of the `sourcedata` folder 
-    (or both). This file should describe the nature of the
-    raw data or the derived data. We RECOMMEND including the PDF print-out with 
-    the actual sequence parameters generated by the scanner in the `sourcedata` 
-    folder.
+1.  A README file SHOULD be found at the root of the `sourcedata` folder.
+    This file should describe the nature of the raw data or the derived data.
+    We RECOMMEND including the PDF print-out with  the actual sequence
+    parameters generated by the scanner in the `sourcedata`  folder.
 
 Alternatively one can organize their data in the following way
 
diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 138a729eed..e6cc99e61b 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -17,8 +17,8 @@ Derivatives can be stored/distributed in two ways:
     RECOMMENDED to use the format `<pipeline>-<variant>` in cases where it is
     anticipated that the same pipeline will output more than one variant (e.g.,
     `AFNI-blurring`, `AFNI-noblurring`, etc.). For the sake of consistency, the
-    subfolder name needs to be a substring of `PipelineDescription.Name` field
-    in the `dataset_description.json` (see below).
+    subfolder name MUST be a substring of `PipelineDescription.Name` field in
+    the `dataset_description.json` (see below).
 
     For example:
 
@@ -32,17 +32,17 @@ Derivatives can be stored/distributed in two ways:
     dataset. This way of specifying derivatives is particularly useful when the
     source dataset is provided with read-only access, and for publishing
     derivatives as independent bodies of work, or for describing derivatives
-    that were created from more than one source dataset. It is consistent with
-    BIDS principles for the `sourcedata/` subdirectory to be used to include or
-    reference the source dataset(s) as it existed when the derivatives were
-    generated. Likewise, any code used to generate the derivatives from the
-    source data may be included in the `code/` subdirectory.
+    that were created from more than one source dataset. The `sourcedata/`
+    subdirectory MAY be used to include the source dataset(s) that were used
+    to generate the derivatives.
+    Likewise, any code used to generate the derivatives from the source data
+    MAY be included in the `code/` subdirectory.
 
 The rest of the Derivatives specification assumes Case 1, but Case 2 applies
 after removing `/derivatives/<pipeline_name>` from template names. In both cases
 every derivatives dataset is considered a BIDS dataset and must include a
 `dataset_description.json` file at the root level. Consequently, files should be
-organized to comply with the BIDS to the full extent possible (i.e., unless
+organized to comply with BIDS to the full extent possible (i.e., unless
 explicitly contradicted below). Any subject-specific derivatives should be
 housed within each subject’s directory; if session-specific derivatives are
 generated, they should be deposited under a session subdirectory within the
@@ -90,9 +90,9 @@ Example:
 
 ## Coordinate systems
 
-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
+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 on the file format:
 
 | File format                  | Description             | Allowed `CoordinateSystem` values                                                                                                                                                                             |
@@ -116,10 +116,11 @@ sub-01/func/sub-01_task-rest_space-HCPMNIfsLR32k_bold.nii
 ## Common file level metadata fields
 
 Each derivative file SHOULD be described by a JSON file provided as a sidecar or
-higher up in the hierarchy of the derived dataset (according to Inheritance
-Principle - section 3.5 of the main specification) unless a particular
-derivative includes REQUIRED metadata fields in which case a JSON file is also
-REQUIRED. Each derivative type defines their own set of fields, but all of them
+higher up in the hierarchy of the derived dataset (according to
+[The Inheritance Principle](../02-common-principles.md#the-inheritance-principle))
+unless a particular derivative includes REQUIRED metadata fields in which case a
+JSON file is also REQUIRED.
+Each derivative type defines their own set of fields, but all of them
 share the following (non-required) ones:
 
 | **Key name**     | **Description**                                                                                                                                                                                                                                                                                                                                       |
@@ -174,7 +175,8 @@ sub-01/anat/sub-01_hemi-L_space-individual_thickness.json
     pertinent fields is very valuable and thus encouraged. Moreover, for some
     types of files, there may be one or more required metadata fields, in which
     case at least one metadata file containing that field must be located
-    somewhere within the file’s hierarchy (per the Inheritance Principle).
+    somewhere within the file’s hierarchy (per [the Inheritance
+    Principle](../02-common-principles.md#the-inheritance-principle)).
 
 -   When chaining derivative pipelines, any JSON fields that were specified as
     mandatory in the input files should be propagated forward in the output

From 9d281fe16a8e4b097176d91e093761fd60541279 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Tue, 28 May 2019 11:03:46 -0400
Subject: [PATCH 105/191] FIX: Code block with indentations

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

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index e6cc99e61b..ad28cf7679 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -22,11 +22,9 @@ Derivatives can be stored/distributed in two ways:
 
     For example:
 
-    ```Text
-    <dataset>/derivatives/fmripreprocess-v1/sub-0001
-    <dataset>/derivatives/spm/sub-0001
-    <dataset>/derivatives/vbm/sub-0001
-    ```
+        <dataset>/derivatives/fmripreprocess-v1/sub-0001
+        <dataset>/derivatives/spm/sub-0001
+        <dataset>/derivatives/vbm/sub-0001
 
 1.  As a standalone dataset independent of the source (raw or derived) BIDS
     dataset. This way of specifying derivatives is particularly useful when the

From 78f814337ec6ad475997e9b4d8ec76116ff5c668 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Tue, 28 May 2019 11:56:16 -0400
Subject: [PATCH 106/191] ENH: Use pymdownx.superfences

---
 Pipfile                               |  1 +
 Pipfile.lock                          | 21 +++++++++++----------
 mkdocs.yml                            |  1 +
 src/05-derivatives/01-introduction.md |  8 +++++---
 4 files changed, 18 insertions(+), 13 deletions(-)

diff --git a/Pipfile b/Pipfile
index 455fece456..535c0e0bb3 100644
--- a/Pipfile
+++ b/Pipfile
@@ -6,6 +6,7 @@ name = "pypi"
 [packages]
 mkdocs = "==1.0.4"
 mkdocs-material = "==4.1.2"
+pymdown-extensions = "==6.0.0"
 
 [dev-packages]
 
diff --git a/Pipfile.lock b/Pipfile.lock
index aaf778482a..327fb42911 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "21a65a0eae9dbcf464e3df5f8b14f8b49cb966eb1bfa61e3ccf9a9e63085945a"
+            "sha256": "effb38045a509709aef13afe50f1022ab64a9855d99a958199709545b2095151"
         },
         "pipfile-spec": 6,
         "requires": {
@@ -32,17 +32,17 @@
         },
         "livereload": {
             "hashes": [
-                "sha256:29cadfabcedd12eed792e0131991235b9d4764d4474bed75cf525f57109ec0a2",
-                "sha256:e632a6cd1d349155c1d7f13a65be873b38f43ef02961804a1bba8d817fa649a7"
+                "sha256:78d55f2c268a8823ba499305dcac64e28ddeb9a92571e12d543cd304faf5817b",
+                "sha256:89254f78d7529d7ea0a3417d224c34287ebfe266b05e67e51facaf82c27f0f66"
             ],
-            "version": "==2.6.0"
+            "version": "==2.6.1"
         },
         "markdown": {
             "hashes": [
-                "sha256:fc4a6f69a656b8d858d7503bda633f4dd63c2d70cf80abdc6eafa64c4ae8c250",
-                "sha256:fe463ff51e679377e3624984c829022e2cfb3be5518726b06f608a07a3aad680"
+                "sha256:2e50876bcdd74517e7b71f3e7a76102050edec255b3983403f1a63e7c8a41e7a",
+                "sha256:56a46ac655704b91e5b7e6326ce43d5ef72411376588afa1dd90e881b83c7e8c"
             ],
-            "version": "==3.1"
+            "version": "==3.1.1"
         },
         "markupsafe": {
             "hashes": [
@@ -95,16 +95,17 @@
         },
         "pygments": {
             "hashes": [
-                "sha256:5ffada19f6203563680669ee7f53b64dabbeb100eb51b61996085e99c03b284a",
-                "sha256:e8218dd399a61674745138520d0d4cf2621d7e032439341bc3f647bff125818d"
+                "sha256:71e430bc85c88a430f000ac1d9b331d2407f681d6f6aec95e8bcfbc3df5b0127",
+                "sha256:881c4c157e45f30af185c1ffe8d549d48ac9127433f2c380c24b84572ad66297"
             ],
-            "version": "==2.3.1"
+            "version": "==2.4.2"
         },
         "pymdown-extensions": {
             "hashes": [
                 "sha256:25b0a7967fa697b5035e23340a48594e3e93acb10b06d74574218ace3347d1df",
                 "sha256:6cf0cf36b5a03b291ace22dc2f320f4789ce56fbdb6635a3be5fadbf5d7694dd"
             ],
+            "index": "pypi",
             "version": "==6.0"
         },
         "pyyaml": {
diff --git a/mkdocs.yml b/mkdocs.yml
index 66828b26c2..9e383af4f1 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -5,6 +5,7 @@ extra_javascript:
 markdown_extensions:
     - toc:
         anchorlink: true
+    - pymdownx.superfences
 plugins:
     - search
 docs_dir: 'src'
diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index ad28cf7679..7061ca6ede 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -22,9 +22,11 @@ Derivatives can be stored/distributed in two ways:
 
     For example:
 
-        <dataset>/derivatives/fmripreprocess-v1/sub-0001
-        <dataset>/derivatives/spm/sub-0001
-        <dataset>/derivatives/vbm/sub-0001
+    ```
+    <dataset>/derivatives/fmripreprocess-v1/sub-0001
+    <dataset>/derivatives/spm/sub-0001
+    <dataset>/derivatives/vbm/sub-0001
+    ```
 
 1.  As a standalone dataset independent of the source (raw or derived) BIDS
     dataset. This way of specifying derivatives is particularly useful when the

From 35899c8d0f4c8042e732d8b6b79727c3886bf8c2 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Tue, 28 May 2019 12:09:02 -0400
Subject: [PATCH 107/191] FIX: Language for code block, missing comma

---
 src/05-derivatives/01-introduction.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 7061ca6ede..765b873ab4 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -22,7 +22,7 @@ Derivatives can be stored/distributed in two ways:
 
     For example:
 
-    ```
+    ```Plain
     <dataset>/derivatives/fmripreprocess-v1/sub-0001
     <dataset>/derivatives/spm/sub-0001
     <dataset>/derivatives/vbm/sub-0001
@@ -54,7 +54,7 @@ As for any BIDS dataset a `dataset_description.json` file MUST be found at the
 top level of the particular pipeline:
 `<dataset>/derivatives/<pipeline_name>/dataset_description.json`
 
-In addition to raw BIDS datasets derived BIDS datasets include the following
+In addition to raw BIDS datasets, derived BIDS datasets include the following
 required or recommended `dataset_description.json` keys (a dot in the Key name
 denotes a key in a subdictionary):
 

From 0821f71ef253059a518925f93b69d38dc6d10ef3 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Tue, 9 Jul 2019 13:43:52 -0400
Subject: [PATCH 108/191] Drop modality-specific derivatives for now

---
 .../03-structural-derivatives.md              | 142 ------
 .../04-functional-derivatives.md              | 386 ---------------
 .../05-diffusion-derivatives.md               | 467 ------------------
 3 files changed, 995 deletions(-)
 delete mode 100644 src/05-derivatives/03-structural-derivatives.md
 delete mode 100644 src/05-derivatives/04-functional-derivatives.md
 delete mode 100644 src/05-derivatives/05-diffusion-derivatives.md

diff --git a/src/05-derivatives/03-structural-derivatives.md b/src/05-derivatives/03-structural-derivatives.md
deleted file mode 100644
index e35d9797fe..0000000000
--- a/src/05-derivatives/03-structural-derivatives.md
+++ /dev/null
@@ -1,142 +0,0 @@
-# Structural (anatomical) derivatives
-
-## Reconstructed cortical surfaces
-
-Reconstructed cortical surfaces should be stored as GIFTI files, and each
-hemisphere should be stored separately.
-
-Template:
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        anat/
-            <source_keywords>_hemi-{L|R}[_space-<surfspace>][_volspace-<volspace>][_desc-<label>]_<surftype>.surf.gii
-```
-
-Example:
-
-```Text
-pipeline/
-    sub-001/
-        anat/
-            sub-001_hemi-L_pial.surf.gii
-            sub-001_hemi-R_pial.surf.gii
-```
-
-The supported surface types (`<surftype>` suffix) are:
-
-| `<surftype>` | Description                                                          |
-| ------------ | -------------------------------------------------------------------- |
-| wm           | The gray matter / white matter border for the cortex                 |
-| smoothwm     | The smoothed gray matter / white matter border                       |
-| pial         | The gray matter / pial matter border                                 |
-| midthickness | The midpoints between wm and pial surfaces                           |
-| inflated     | An inflation of the midthickness surface (useful for visualization)  |
-| vinflated    | A very-inflated midthicknesss surface (also for visualization)       |
-| sphere       | The sphere (used for registration - see transforms for nomenclature) |
-| flat         | The flattened surface (used for visualization)                       |
-
-`space` filename keyword is restricted to
-[Surface Coordinate Spaces](../99-appendices/08-coordinate-systems.md#Surface)
-and `volspace` corresponds to the 3D coordinate space described in
-[Volume Coordinate Spaces](../99-appendices/08-coordinate-systems.md#Volume). In
-contrast to other derivatives the sidecar metadata field `SpatialReference` (see
-[Introduction](01-introduction.md#Common-file-level-metadata-fields)) is not
-required for any space, but is recommended when `volspace` is set to
-`individual`. In such case it should point to the volume defining the 3D
-coordinate system with witch the surface mesh is aligned with.
-
-## Surface-Mapped Anatomical Scalar Derivatives
-
-Surface-mapped scalar overlays should be stored as either GIFTI or CIFTI files
-(which allow for the combination of left and right hemispheres).
-
-Template:
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        anat/
-            <source_keywords>[_hemi-{L|R}][_space-<space>][_desc-<label>]_<suffix>.{shape.gii|dscalar.nii}
-```
-
-The REQUIRED extension for scalar GIFTI files is `.shape.gii`. The `hemi` key is
-required for GIFTI files. For example:
-
-```Text
-pipeline/
-    sub-001/
-        anat/
-            sub-001_hemi-L_curv.shape.gii
-            sub-001_hemi-R_curv.shape.gii
-```
-
-The REQUIRED extension for scalar CIFTI files is `.dscalar.nii`. For example:
-
-```Text
-pipeline/
-    sub-001/
-        anat/
-            sub-001_curv.dscalar.nii
-```
-
-The file `<suffix>` MUST be one of the following values:
-
-| `<suffix>`   | Description                                           |
-| ------------ | ----------------------------------------------------- |
-| `curv`       | Cortical surface curvature indices                    |
-| `thickness`  | Cortical thickness                                    |
-| `area`       | Discretized surface area across regions               |
-| `dist`       | Distance from a point                                 |
-| `defects`    | Marked regions with surface defects                   |
-| `sulc`       | Sulcal depth                                          |
-| `myelinmap`  | Myelin map calculated from T1w to T2w ratio           |
-| `distortion` | Distortion map calculated from a surface registration |
-
-## Morphometrics
-
-Structural statistics produced by segmentation routines should be stored within
-tsv files, which could contain common parameters specified in the table below.
-
-Template:
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        func|anat|dwi/
-            <source_keywords>[_desc-<label>]_morph.tsv
-
-```
-
-Example:
-
-```Text
-pipeline/
-    sub-001/
-        anat/
-            sub-001_desc-volumetric_morph.tsv
-```
-
-| Column name | Description                                     |
-| ----------- | ----------------------------------------------- |
-| index       | RECOMMENDED. Label integer index                |
-| name        | RECOMMENDED. Structure name                     |
-| centroid    | OPTIONAL. Center coordinate of structure        |
-| volume      | OPTIONAL. Volume of structure                   |
-| intensity   | OPTIONAL. Intensity of voxels within structure  |
-| thickness   | OPTIONAL. Thickness of cortical structure       |
-| area        | OPTIONAL. Surface area of cortical structure    |
-| curv        | OPTIONAL. Curvature index of cortical structure |
-
-Some parameters might require unit specification or have multiple associated
-statistics (such as avg, std, min, max, range). The suggested syntax for such
-columns is `<parameter>[-<stat>][-<units>]`. An example volumetric stats file
-might look something like this:
-
-```Text
-index  name               volume-mm3  intensity-avg  intensity-std
-11     Brainstem          23415.9     80.11          3.40
-32     Left-Hippocampus   5349.7      75.23          2.27
-32     Right-Hippocampus  4112.1      76.98          4.01
-```
diff --git a/src/05-derivatives/04-functional-derivatives.md b/src/05-derivatives/04-functional-derivatives.md
deleted file mode 100644
index 4807d38475..0000000000
--- a/src/05-derivatives/04-functional-derivatives.md
+++ /dev/null
@@ -1,386 +0,0 @@
-# Functional derivatives
-
-## Functional derivatives maps
-
-Template:
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        func/
-            <source_keywords>[_space-<space>][_desc-<label>]_<suffix>.nii[.gz]
-            <source_keywords>[_space-<space>][_desc-<label>]_<suffix>.json
-```
-
-for example:
-
-```Text
-pipeline1/
-    sub-001/
-        func/
-            sub-001_task-rest_run-1_space-MNI305_mean.nii.gz
-            sub-001_task-rest_run-1_space-MNI305_mean.json
-```
-
-The following table lists allowed suffixes and their corresponding measures:
-
-| `<suffix>`       | Measure                                                          |
-| ---------------- | ---------------------------------------------------------------- |
-| `mean`           | Mean across the temporal/4th dimension of the data               |
-| `std`            | Standard deviation across the temporal/4th dimension of the data |
-| `tsnr`           | Temporal SNR (i.e. mean / std)                                   |
-| `sfs`            | Signal fluctuation sensitivity                                   |
-| `alff`           | Amplitude low frequency fluctuations                             |
-| `falff`          | Fractional amplitude of low frequency fluctuations               |
-| `reho`           | Regional homogeneity (voxelwise only)                            |
-| `dcb`, `dcw`     | Voxelwise degree centrality binary and weighted                  |
-| `ecb`, `ecw`     | Voxelwise eigenvector centrality binary and weighted             |
-| `lfcdb`, `lfcdw` | Local functional connectivity density                            |
-| `vmhc`           | Voxel mirrored homotopic connectivity                            |
-
-The following metadata JSON fields are valid for derivative maps:
-
-| Key name       | Description                                                               | Required for suffix        |
-| -------------- | ------------------------------------------------------------------------- | -------------------------- |
-| BandpassFilter | String describing all relevant parameters of the applied bandpass filter. | `alff`, `falff`            |
-| Neighborhood   | String describing neighborhood for regional measures.                     | `reho`                     |
-| Threshold      | String describing threshold used for determining graph edges.             | `dcb`, `dcw`, `ecb`, `ecw` |
-| Method         | String describing method used to calculate measure.                       | `dcb`, `dcw`, `ecb`, `ecw` |
-
-## Time series
-
-A time series is a chronologically ordered series of numeric values.
-Time series will generally be stored as tables, with a row of column headers
-indicating the name of the series.
-In the case where every voxel has a time series, then the data should be stored
-in a 4D NIfTI file.
-
-All time series files MUST be accompanied by a data dictionary in JSON format,
-consistent with the format described in
-[Common principles](../02-common-principles.md#tabular-files), which describes
-metadata for each column name.
-In the case of NIfTI time series files, the notion of column name does not
-apply, so column-level metadata may be applied to the entire file.
-In addition, the following fields apply to the entire file in all cases:
-
-| Field name        | Definition                                                                                                                                                   |
-| :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| SamplingFrequency | REQUIRED. Sampling frequency (in Hz) of all columns in the file. Special value `"TR"` indicates one sample per volume of a corresponding BOLD series.        |
-| StartTime         | OPTIONAL. Start time in seconds in relation to the start of acquisition of the first volume in the corresponding imaging file (negative values are allowed). |
-
-Note that there are several differences with these fields in
-[Physiological and other continuous recordings](../04-modality-specific-files/06-physiological-and-other-continuous-recordings.md).
-The `"TR"` sampling frequency serves to indicate that no resampling is needed
-to use the series as a regressor for BOLD data, including BOLD series with
-non-uniform sampling, such as clustered sparse acquisition.
-`StartTime` is assumed to be 0 and therefore not mandatory.
-Additionally, because time series TSV files have column headers, the `Columns`
-field is omitted.
-
-### General time series
-
-Template:
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        func/
-	        <source_keywords>[_desc-<label>]_timeseries.tsv
-	        <source_keywords>[_desc-<label>]_timeseries.json
-```
-
-for example:
-
-```Text
-sub-001/
-    func/
-        sub-001_task-rest_run-1_desc-confounds_timeseries.tsv
-        sub-001_task-rest_run-1_desc-confounds_timeseries.json
-```
-
-Any time series with common timing information may be stored in a `timeseries`
-file.
-If a time series is specified in another sub-section, then any additional
-required metadata MUST be stored in the JSON description of the column.
-
-#### Column names
-
-Column names are unique alphanumeric values that are defined in a relevant JSON
-sidecar file. For a series of related columns, it is RECOMMENDED to use
-zero-based indexing as a suffix. For example, the first six aCompCor components
-may be named `a_comp_cor_00` ... `a_comp_cor_05`. Custom column names must not
-conflict with reserved names specified in this document.
-
-Reserved names are specified in the remaining subsections.
-
-#### Time series transformations
-
-Any column may have the following suffixes appended to indicate transformations
-applied to the original time series data:
-
-| Transformation | Description                                                                 |
-| -------------- | --------------------------------------------------------------------------- |
-| `_shift_back`  | The time series has been lagged by one TR. `x_shift_back[i] = x[i-1]`       |
-| `_dt`          | The discrete first derivative of the time series. `x_dt[i] = x[i+1] - x[i]` |
-| `_sq`          | The square of the time series                                               |
-| `_var_norm`    | The time series has been variance normalized                                |
-| `_centered`    | The time series has had its mean subtracted                                 |
-
-For example, `rot_z_shift_back_sq` means the square of the lagged version of the
-Z rotation (see [Motion-related time series](#motion-related-time-series)).
-
-### ROI-based time series extraction
-
-Template:
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        func/
-            <source_keywords>[_atlas-<atlas_label>][_desc-<label>]_timeseries.<tsv|nii[.gz]>
-            <source_keywords>[_atlas-<atlas_label>][_desc-<label>]_timeseries.json
-```
-
-for example:
-
-```Text
-sub-001/
-    func/
-        sub-001_task-rest_run-1_atlas-AAL_timeseries.tsv
-        sub-001_task-rest_run-1_atlas-AAL_timeseries.json
-        sub-001_task-rest_run-1_desc-anaticor_timeseries.nii.gz
-        sub-001_task-rest_run-1_desc-anaticor_timeseries.json
-```
-
-ROI-based time series will generally be stored as tables, with a row of column
-headers indicating the name of the time series.
-In the case where every voxel has a time series (i.e., voxel-wise regressors,
-as in ANATICOR), then the time series should be saved as a NIfTI file.
-
-#### Column metadata special fields
-
-Atlas (optional) - A label indicating an atlas that defines a region or set of
-regions in the volume. An atlas may be three- or four-dimensional, which affects
-the interpretation of the roi index.
-
-ROI (optional) - For 3D atlases, the ROI label should be numeric, corresponding
-to the value of the voxels in the ROI. For 4D atlases, the ROI label should be
-numeric, corresponding to the volume index containing the ROI mask. The
-following special labels correspond to common ROIs that may be defined by many
-atlases or segmentation algorithms:
-
-| ROI Value      | Description                                                                            |
-| -------------- | -------------------------------------------------------------------------------------- |
-| WhiteMatter    | Signal derived from white matter ROI.                                                  |
-| CSF            | Signal derived from cerebro-spinal fluid ROI.                                          |
-| Background     | Signal derived from background (out of brain) ROI.                                     |
-| GreyMatter     | Signal derived from grey matter ROI.                                                   |
-| Ventricles     | Signal derived from ventricles ROI.                                                    |
-| CircleOfWillis | Signal derived from circle of Willis ROI.                                              |
-| GlobalSignal   | Vector of mean values within the brain mask. Can be used for Global Signal Regression. |
-
-#### Column names
-
-Column names are unique alphanumeric values that are defined in a relevant JSON
-sidecar file. A naming convention might be to concatenate the atlas, ROI index,
-summarization method (defined below) and transformations (see [Time series
-transformations](#time-series-transformations)) using snake case. For example,
-`harvard_oxford_cortical_4_PC` could indicate ROI 4 of the Harvard-Oxford
-cortical atlas, summarized by taking the first principal component.
-
-#### Summarization methods
-
-To indicate the summarization method applied to construct a single time series
-for an ROI, the following column suffixes are defined:
-
-| Column suffix | Description of the transformation                                                                                                                       |
-| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `_mean`       | The mean of voxel time series                                                                                                                           |
-| `_median`     | The median of voxel time series                                                                                                                         |
-| `_pc[_<x>]`   | The ith eigenvariate from principal component analysis, where `x` is 0 indexed. If `x` is not specified, the first component is implied (i.e., `pc_0`). |
-| `_spat_reg`   | Spatial regression                                                                                                                                      |
-
-Example:
-
-```Text
-sub-001/
-    func/
-        sub-001_task-rest_run-1_timeseries.tsv
-```
-
-```Text
-white_matter_mean global_signal_mean ventricles_mean
-12                98                 11
-11                34                 53
-54                34                 34
-```
-
-```Text
-sub-001/
-    func/
-        sub-001_task-rest_run-1_timeseries.json
-```
-
-```JSON
-{
-    "SamplingFrequency": "TR",
-    "white_matter_mean": {
-        "ROI": "WhiteMatter"
-    },
-    "global_signal_mean": {
-        "ROI": "GlobalSignal"
-    },
-    "ventricles_mean": {
-        "ROI": "Ventricles"
-    }
-}
-```
-
-### Motion-related time series
-
-Template:
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-    func/
-        <source_keywords>[_desc-<label>]_motion.tsv
-        <source_keywords>[_desc-<label>]_motion.json
-```
-
-#### Column names
-
-The six basic motion parameters derived from motion correction have the
-following names and units:
-
-| Column name                     | Units   | Description            |
-| ------------------------------- | ------- | ---------------------- |
-| `trans_x`, `trans_y`, `trans_z` | mm      | Translation parameters |
-| `rot_x`, `rot_y`, `rot_z`       | radians | Rotation parameters    |
-
-Transformations (see [Time series
-transformations](#time-series-transformations)) of motion parameters may be
-included in the same file.
-For example, `rot_z_shift_back_sq` means square of the lagged version of Z
-rotation.
-
-The following columns indicate summarized motion, as defined in the
-corresponding references:
-
-| Column name              | Units | Description                                                         |
-| ------------------------ | ----- | ------------------------------------------------------------------- |
-| `framewise_displacement` | mm    | Framewise displacement (Power, et al., 2012)                        |
-| `rmsd`                   | mm    | Root mean square deviation (Jenkinson, 1999)                        |
-| `rms`                    | mm    | Root mean square of translation parameters (Van Dijk, et al., 2012) |
-
-### Temporal outlier masks
-
-Template:
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        func/
-	        <source_keywords>[_desc-<label>]_outliers.tsv
-            <source_keywords>[_desc-<label>]_outliers.json
-```
-
-Outlier masks are columns of zeros (0), with ones (1) indicating volumes that
-have been identified as outliers by some method.
-
-#### Column names
-
-Column names for outliers correspond to the type of outlier or method for
-identifying the outlier. Column names should take the form `method[XX]`, where
-`XX` is an optional index.
-
-For example, if a BOLD series included two initial dummy scans,
-`non_steady_state` may be a column with a 1 for the first two volumes, or
-`non_steady_state_00` and `non_steady_state_01` may be columns with a 1 in the
-first and second position, respectively.
-
-The following methods are defined as reserved words:
-
-| Column name            | Description                                              |
-| ---------------------- | -------------------------------------------------------- |
-| `non_steady_state_<x>` | Initial non-steady-state volumes. One column per volume. |
-
-### Other time series
-
-Time series that are not otherwise specified MUST be placed in a
-`_timeseries.tsv` file (see [General time series](#general-time-series)).
-
-#### Column names
-
-The following time series are defined as reserved words:
-
-| Column name    | Description                                           |
-| -------------- | ----------------------------------------------------- |
-| `dvars`        | Change in variance (Brett, 2006, Power, et al., 2012) |
-| `std_dvars`    | Standardized DVARS (Nichols, 2013)                    |
-| `cosine_<X>`   | Discrete cosine basis vectors                         |
-| `legendre_<X>` | Legendre polynomial basis vectors                     |
-
-### Spatiotemporal decompositions
-
-Template:
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        func/
-            <source_keywords>[_desc-<label>]_<mixing|components>.tsv
-            <source_keywords>[_desc-<label>]_<mixing|components>.nii.gz
-            <source_keywords>[_desc-<label>]_decomposition.json
-```
-
-for example:
-
-```Text
-sub-001/
-    func/
-        sub-001_task-rest_run-1_desc-MELODIC_components.nii.gz
-        sub-001_task-rest_run-1_desc-MELODIC_mixing.tsv
-        sub-001_task-rest_run-1_desc-MELODIC_decomposition.json
-```
-
-```Text
-sub-001/
-    func/
-        sub-001_task-rest_run-1_desc-tICA_mixing.nii.gz
-        sub-001_task-rest_run-1_desc-tICA_components.tsv
-        sub-001_task-rest_run-1_desc-tICA_decomposition.json
-```
-
-Spatiotemporal decompositions produce either spatial or temporal components,
-along with conjugate mixing matrices that can be represented as time series and
-spatial maps, respectively. The combination of suffix and extension indicates
-which class of algorithm produced the outputs.
-
-Mixing matrices may be omitted for algorithms that are temporal decompositions
-with no spatial component, such as CompCor variants.
-
-Spatiotemporal decomposition files MUST be accompanied by a data dictionary in
-JSON format, consistent with Raw-BIDS section 4.2, which describes metadata for
-each column name. In addition to column names, the following MANDATORY field is
-added:
-
-| Key name | Description                                           |
-| -------- | ----------------------------------------------------- |
-| Method   | REQUIRED. Algorithm name and (if applicable) version. |
-
-#### Column names
-
-Column names in spatiotemporal decompositions take the form of
-`<decomposition>_<index>`, where `<decomposition>` is the name of the
-decomposition algorithm, and `<index>` is a numeric identifier. Indices SHOULD
-start at 0. If there is a natural ordering, indices should reflect that
-ordering. For example, the aCompCor component which explains the most variance
-should be named `a_comp_cor_00`.
-
-The following reserved words indicate common algorithms:
-
-| Column name              | Description                                                                                                                                                                                                |
-| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `[a|t|w|c]_comp_cor_<x>` | CompCor (Behzadi, et al., 2007) calculated with voxels chosen based on: `a`: anatomically derived ROIs (white matter and CSF), `t`: temporal variance, `w`: white matter voxels only, `c`: CSF voxels only |
-| `melodic_<x>`            | Columns from the mixing matrix in FSL MELODIC                                                                                                                                                              |
diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
deleted file mode 100644
index 5ba96e4bf1..0000000000
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ /dev/null
@@ -1,467 +0,0 @@
-# Diffusion derivatives
-
-## Preprocessed diffusion weighted images
-
-Multiple different versions of preprocessing can be stored for the same source
-data. To distinguish them from each other, the `desc` filename keyword can be
-used. Details of preprocessing performed for each variation of the processing
-should be included in the pipeline documentation.
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        dwi/
-            <source_keywords>[_space-<space>][_desc-<label>]_dwi.nii[.gz]
-            <source_keywords>[_space-<space>][_desc-<label>]_dwi.bvals
-            <source_keywords>[_space-<space>][_desc-<label>]_dwi.bvecs
-            <source_keywords>[_space-<space>][_desc-<label>]_dwi.json
-```
-
-The JSON sidecar file is REQUIRED (due to the REQUIRED `SkullStripped` field -
-see [Common Data Types](02-common-data-types.md)), and if present can be used to
-store information about what preprocessing options were used (for example
-whether denoising was performed, corrections applied for field inhomogeneity /
-gradient non-linearity / subject motion / eddy currents, intensity normalization was
-performed, etc.).
-
-Additional reserved JSON metadata fields:
-
-| **Key name**                   | **Description**                                                                                                              |
-| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
-| Denoising                      | OPTIONAL. String. Denoising method                                                                                           |
-| MotionCorrection               | OPTIONAL. Boolean. Motion correction                                                                                         |
-| EddyCurrentCorrection          | OPTIONAL. Boolean. Eddy currents corrections                                                                                 |
-| IntensityNormalizationMethod   | OPTIONAL. String. Method (if any) used for intensity normalization                                                           |
-| FieldInhomogeneityCorrection   | OPTIONAL. Boolean. Correction for geometric distortions arising from magnetic field inhomogeneity                            |
-| GradientNonLinearityCorrection | OPTIONAL. String. Correction for non-linear gradients; allowed values: `none`, `geometry`, `gradients`, `geometry&gradients` |
-
-## Diffusion Models (and input parameters)
-
-Diffusion MRI can be modeled using various paradigms to extract a more easily
-understandable representation of the diffusion process and the underlying
-structure. To do so, parameters might be needed to control how the signal is fit
-to the model. Those parameters are called **input parameters** in the following.
-Once the model is fit, the resulting representation can be saved using a number
-of values per voxel. Those values will be called **output** or **estimated
-parameters** in the following.
-
-**Estimated parameters** are saved as NIFTI files (see section Models for the
-expected content of each model), and **input parameters** are saved in the
-sidecar JSON file.
-
-The following is a general example of naming convention:
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        dwi/
-            <source_keywords>[_space-<space>][_desc-<label>]_model-<label>[_parameter-<parameter>]_diffmodel.nii[.gz]
-            <source_keywords>[_space-<space>][_desc-<label>]_model-<label>_diffmodel.json
-```
-
-The following models are codified and should be used in the `model-<label>`
-field. If a new model is used, common sense should be used to derive a name
-following the BIDS standard, and should ideally be integrated in a follow-up
-version of the specification.
-
-| Model label | Name & citation                                                                                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| ----------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `DTI`       | Diffusion tensor imaging (Basser et al. 1994)                                                  | 4D image with D<sub>xx</sub>, D<sub>xy</sub>, D<sub>xz</sub>, D<sub>yy</sub>, D<sub>yz</sub>, D<sub>zz</sub>; the 6 unique parameters of the diffusion tensor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `DKI`       | Diffusion kurtosis imaging (Jensen et al., 2005)                                               | 4D image with D<sub>xx</sub>, D<sub>xy</sub>, D<sub>xz</sub>, D<sub>yy</sub>, D<sub>yz</sub>, D<sub>zz</sub>, W<sub>xxxx</sub>, W<sub>yyyy</sub>, W<sub>zzzz</sub>, W<sub>xxxy</sub>, W<sub>xxxz</sub>, W<sub>xyyy</sub>, W<sub>yyyz</sub>, W<sub>xzzz</sub>, W<sub>yzzz</sub>, W<sub>xxyy</sub>, W<sub>xxzz</sub>, W<sub>yyzz</sub>, W<sub>xxyz</sub>, W<sub>xyyz</sub>, W<sub>xyzz</sub>; Where D is the diffusion tensor and W is the kurtosis tensor.                                                                                                                                                                                                                                                                     |
-| `WMTI`      | White matter tract integrity (Fieremans et al., 2011)                                          | 4D image with D<sub>xx</sub>, D<sub>xy</sub>, D<sub>xz</sub>, D<sub>yy</sub>, D<sub>yz</sub>, D<sub>zz</sub>, W<sub>xxxx</sub>, W<sub>yyyy</sub>, W<sub>zzzz</sub>, W<sub>xxxy</sub>, W<sub>xxxz</sub>, W<sub>xyyy</sub>, W<sub>yyyz</sub>, W<sub>xzzz</sub>, W<sub>yzzz</sub>, W<sub>xxyy</sub>, W<sub>xxzz</sub>, W<sub>yyzz</sub>, W<sub>xxyz</sub>, W<sub>xyyz</sub>, W<sub>xyzz</sub>, Dh<sub>xx</sub>, Dh<sub>xy</sub>, Dh<sub>xz</sub>, Dh<sub>yy</sub>, Dh<sub>yz</sub>, Dh<sub>zz</sub>, Dr<sub>xx</sub>, Dr<sub>xy</sub>, Dr<sub>xz</sub>, Dr<sub>yy</sub>, Dr<sub>yz</sub>, Dr<sub>zz</sub>, AWF; where D is the diffusion tensor, W is the kurtosis tensor, AWF is the additional axonal water fraction parameter |
-| `CSD`       | Constrained Spherical Deconvolution (Tournier et al. 2007; Descoteaux et al. 2009)             | 4D image with spherical harmonic (SH) coefficients (number of volumes and their ordering depends on the model maximal degree and basis set, specified in the sidecar)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `NODDI`     | Neurite Orientation Dispersion and Density Imaging (Zhang et al. 2012, Daducci et al., 2015)   | Three 3D images, with <parameter> equal to {`ICVF`,`OD`,`ISOVF`}: ICVF is the “intracellular volume fraction” (also known as NDI); OD is the “orientation dispersion” (the variance of the Bingham; also known as ODI); ISOVF is the isotropic component volume fraction (also known as IVF). Additionally a vector-valued map with the parameter name "`direction`" may provide the XYZ direction of the estimated fibre orientation.                                                                                                                                                                                                                                                                                        |
-| `DSI`       | Diffusion Spectrum Imaging (Wedeen et al. 2008; Paquette et al 2017)                           | DSI is generally used to compute the diffusion ODF (Orientation Distribution Function). No parameters are generally returned, but an ODF can be saved as a map.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `CSA`       | Constant solid angle (Aganj et al. 2010)                                                       | 4D image with SH coefficients (number of volumes and their ordering depends on the model maximal degree and basis set, specified in the side-car)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `SHORE`     | Simple Harmonic Oscillator based Reconstruction and Estimation. (Ozarslan et al. 2008)         | 4D image with basis coefficients depending on choice of basis.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `MAPMRI`    | Mean Apparent Propagator MRI. (Ozarslan, 2013)                                                 | 4D image with basis coefficients depending on choice of basis.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `FORECAST`  | Fiber ORientation Estimated using Continuous Axially Symmetric Tensors. (Zuchelli et al. 2017) | 4D image with SH coefficients.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `fwDTI`     | Free water DTI (Hoy et al. 2014)                                                               | One 4D image with parameter name "`tensor`", containing 6 volumes in the order Dc<sub>xx</sub>, Dc<sub>xy</sub>, Dc<sub>xz</sub>, Dc<sub>yy</sub>, Dc<sub>yz</sub>, Dc<sub>zz</sub>, where Dc is the fw-corrected diffusion tensor in each voxel; one 3D image with parameter name "`FWF`" corresponding to the free water fraction in each voxel. .                                                                                                                                                                                                                                                                                                                                                                          |
-| `BedpostX`  | Ball-and-Stick model (Behrens et al. 2007; Jabdbi et al, MRM 2012)                             | 5D image (xyz, m, n) for m parameters and n MCMC samples (n=1 implies best-fit parameters). Parameters are f<sub>i</sub>, th<sub>i</sub>, ph<sub>i</sub> (volume fraction, polar angle, azimuthal angle) for up to 3 fibres, D, D<sub>std</sub> (for “multiexponential” model)                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-
-The JSON sidecar contains the following key/value pairs common for all models:
-
-| **Key name**     | **Description**                                                                                                                      |
-| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| Shells           | OPTIONAL. Shells that were utilized to fit the model, as a list of b-values. If the key is not present, all shells were used.        |
-| Gradients        | OPTIONAL. Subset of gradients utilized to fit the model, as a list of three-elements lists. If not present, all gradients were used. |
-| ModelDescription | OPTIONAL. Extended information to describe the model.                                                                                |
-| ModelURL         | OPTIONAL. URL to the implementation of the specific model utilized.                                                                  |
-| Parameters       | OPTIONAL. A dictionary of model parameters (see below).                                                                              |
-
-Parameters that may be stored within the JSON sidecar "Parameters" field depend on the particular model used:
-
--   `DTI` :
-
-    -   `FitMethod` : {`WLS`,`IWLS`,`OLS`,`NLLS`}
-    -   `OutlierRejection`: boolean
-    -   `RESTORESigma` : value
-
--   `DKI` and `WMTI`:
-
-    -   `FitMethod` : {`WLS`,`IWLS`,`OLS`,`NLLS`}
-
--   `CSD`:
-
-    -   `Tissue` : string
-    -   `SphericalHarmonicDegree` : value
-    -   `ResponseFunctionZSH` : values (1 row per unique *b*-value as listed in "`Shells`"; 1 column per even harmonic degree starting from zero)
-    -   `ResponseFunctionTensor` : values (vector of 4 values: three tensor eigenvalues, then reference b=0 intensity)
-    -   `SphericalHarmonicBasis` : {`MRtrix3`,`DESCOTEAUX`}
-    -   `NonNegativityConstraint` : {`soft`,`hard`}
-
--   `NODDI`:
-
-    -   `DPar` : value
-    -   `DIso` : value
-    -   `Lambda1` : value
-    -   `Lambda2` : value
-
--   `DSI` :
-
-    -   `GridSize` : value
-    -   `RStart` : value
-    -   `RStep` : value
-    -   `REnd` : value
-    -   `FilterWidth` : value
-
--   `CSA` :
-
-    -   `SphericalHarmonicOrder` : value
-    -   `Smoothing` : value
-    -   `Basis` : value
-
--   `SHORE` :
-
-    -   `RadialOrder` : value
-    -   `Zeta` : value
-    -   `LambdaN` : value
-    -   `LambdaL` : value
-    -   `Tau` : value
-    -   `ConstrainE0` : value
-    -   `PositiveConstraint` : value
-    -   `PosGrid` : value
-    -   `PosRadius` : value
-
--   `MAPMRI` :
-
-    -   `RadialOrder` : value
-    -   `LaplacianRegularization` : bool
-    -   `LaplacianWeighting` : value
-    -   `PositivityConstraint` : bool
-    -   `Tau` : value
-    -   `ConstrainE0` : value
-    -   `PositiveConstraint` : value
-    -   `PosGrid` : value
-    -   `PosRadius` : value
-    -   `AnisotropicScaling` : bool
-    -   `EigenvalueThreshold` : value
-    -   `PosGrid` : value
-    -   `BvalThreshold` : value
-    -   `DTIScaleEstimation` : bool
-    -   `StaticDiffusivity` : value
-
--   `FORECAST` :
-
-    -   `Sphere` : value
-    -   `DecAlg` : value
-    -   `LambdaLb` : value
-    -   `SphericalHarmonicsOrder` : value
-
--   `fwDTI` :
-
-    -   `FitMethod` : {"WLS","NLLS"}
-
--   `BEDPOSTX` :
-
-    -   `NFibers` : value
-    -   `Fudge` : value
-    -   `BurnIn` : value
-    -   `NJumps` : value
-    -   `SampleEvery` : value
-    -   `Model` : {`monoexponential`,`multiexponentialStick`,`multiexponentialZeppelin`}
-
-Examples:
-
-A Diffusion Tensor fit:
-
-```Text
-my_diffusion_pipeline/
-    sub-01/
-        dwi/
-            sub-01_space-T1w_desc-WLS_model-DTI_diffmodel.nii.gz
-            sub-01_space-T1w_desc-WLS_model-DTI_diffmodel.json
-```
-
-Contents of JSON file:
-
-```JSON
-{
-    "Parameters": {
-        "FitMethod": "WLS"
-    }
-}
-```
-
-A multi-shell, multi-tissue Constrained Spherical Deconvolution fit:
-
-```Text
-my_diffusion_pipeline/
-    sub-01/
-        dwi/
-            sub-01_model-CSD_desc-WM_diffmodel.nii.gz
-            sub-01_model-CSD_desc-WM_diffmodel.json
-            sub-01_model-CSD_desc-GM_diffmodel.nii.gz
-            sub-01_model-CSD_desc-GM_diffmodel.json
-            sub-01_model-CSD_desc-CSF_diffmodel.nii.gz
-            sub-01_model-CSD_desc-CSF_diffmodel.json
-```
-
-Contents of JSON file (using "`_tissue-WM`" as example):
-
-```JSON
-{
-    "Shells": [ 0, 1000, 2000, 3000 ],
-    "Parameters": {
-        "Tissue": "White matter",
-        "SphericalHarmonicDegree": 8,
-        "ResponseFunctionZSH": [ [ 15335 0 0 0 0 0 ],
-                                 [ 7688 -2766 597 -82 10 -5 ],
-                                 [ 5258 -2592 1024 -270 48 -11 ],
-                                 [ 4226 -2193 1124 -436 119 -19 ] ]
-        "SphericalHarmonicBasis": "MRtrix3",
-        "NonNegativityConstraint": "hard"
-    }
-}
-```
-
-A NODDI fit:
-
-```Text
-my_diffusion_pipeline/
-    sub-01/
-        dwi/
-            sub-01_model-NODDI_parameter-ICVF_diffmodel.nii.gz
-            sub-01_model-NODDI_parameter-OD_diffmodel.nii.gz
-            sub-01_model-NODDI_parameter-ISOVF_diffmodel.nii.gz
-            sub-01_model-NODDI_parameter-direction_diffmodel.nii.gz
-            sub-01_model-NODDI_diffmodel.json
-```
-
-## Model-derived maps (output parameters)
-
-Models output maps of estimated parameters. Commonly one parameter is estimated
-per voxel; we call these maps of parameters. Two types of maps are described in
-this specification: scalar and vector maps. Scalar maps are saved as 3D
-.nii/nii.gz files. Vector maps are saved as 4D .nii/nii.gz files. Below the
-specification for the naming of the files and a the list of currently accepted
-fields for the maps.
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        dwi/
-            <source_keywords>[_space-<space>]_model-<label>[_desc-<label>]_<parameter>.nii[.gz]
-```
-
-### Scalar maps
-
-These maps are saved 3D NIfTI files (x,y,z). Some examples of such maps are as follows:
-
-| `<parameter>` value | Description                                                        | Possible Model sources                                                             | Unit or scale                       |
-| ------------------- | ------------------------------------------------------------------ | -----------------------------------------------------------------------------------| ----------------------------------- |
-| FA                  | Fractional Anisotropy                                              | DTI, DKI, WMTI (D, Dh, Dr)                                                         | Unitless \[0-1\]                    |
-| MD                  | Mean diffusivity (also called apparent diffusion coefficient, ADC) | DTI, DKI, WMTI (D, Dh, Dr)                                                         | microns<sup>2</sup>/ms <sup>1</sup> |
-| AD                  | Axial Diffusivity (also called parallel diffusivity)               | DTI, DKI, WMTI (D, Dh, Dr)                                                         | microns<sup>2</sup>/ms <sup>1</sup> |
-| RD                  | Radial Diffusivity (also called perpendicular diffusivity)         | DTI, DKI, WMTI (D, Dh, Dr)                                                         | microns<sup>2</sup>/ms <sup>1</sup> |
-| MODE                | Mode of the tensor                                                 | DTI, DKI, WMTI (D, Dh, Dr)                                                         |                                     |
-| LINEARITY           | Tensor linearity (Westin 1997)                                     | DTI, DKI, WMTI (D, Dh, Dr)                                                         |                                     |
-| PLANARITY           | Tensor planarity (Westin 1997)                                     | DTI, DKI, WMTI (D, Dh, Dr)                                                         |                                     |
-| SPHERICITY          | Tensor sphericity (Westin 1997)                                    | DTI, DKI, WMTI (D, Dh, Dr)                                                         |                                     |
-| MK                  | Mean kurtosis                                                      | DKI, WMTI                                                                          | Unitless                            |
-| RK                  | Radial kurtosis                                                    | DKI, WMTI                                                                          | Unitless                            |
-| AK                  | Axial kurtosis                                                     | DKI, WMTI                                                                          | Unitless                            |
-| GFA                 | Generalized Fractional Anisotropy                                  | CSA, CSD, SHORE, MAPMRI, Forecast (or any model that can be represented as an ODF) | Proportion \[0-1\]                  |
-| FSUM                | Sum of partial volume fractions of stick components                | Ball-and-stick(s)                                                                  | Volume fraction \[0-1\]             |
-| Fi                  | Volume fraction of stick i                                         | Ball-and-stick(s)                                                                  | Volume fraction \[0-1\]             |
-| D                   | Diffusivity                                                        | Ball-and-stick(s)                                                                  | microns<sup>2</sup>/ms <sup>1</sup> |
-| DSTD                | Standard deviation of diffusivity                                  | Ball-and-stick(s)                                                                  | microns<sup>2</sup>/ms              |
-| RTPP                | Return to the plane probability                                    | MAPMRI                                                                             | Probability \[0-1\]                 |
-| RTAP                | Return to axis probability                                         | MAPMRI                                                                             | Probability \[0-1\]                 |
-
-<sup>1</sup> For example, for free water in body temperature, the diffusivity in units of microns<sup>2</sup>/ms should be approximately 3.0.
-
-### Directionally-encoded colour (DEC) maps
-
-These maps are saved as 4D NIfTI files with 3 volumes (x,y,z,{RGB}), where the
-three values in each voxel correspond to red, green and blue components indicating
-directionality of the underlying model (each of which must be a non-negative value),
-and the norm of the vector encodes any scalar parameter from the diffusion model.
-Images encoded in this way should include the field "`_desc-DEC`" in order to
-distinguish them from vector-valued maps (see below).
-
-A common example is DEC FA maps, where the fractional anisotropy from the diffusion
-tensor model is coloured according to the direction of the principal eigenvector:
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        dwi/
-            <source_keywords>_model-DTI_desc-DEC_FA.nii[.gz]
-```
-
-### Vector-valued maps
-
-These maps are saved as 4D NIfTI files (x,y,z, 3\*n), where each triplet of volumes
-encodes both a direction in 3D space and some quantitiative value (these are
-sometimes referred to as "fixels"). The number of volumes in the image must be
-3 times the maximal number of fixels that can appear in any voxel in the image
-(since 3 volumes are required to represent the data for each individual fixel).
-For voxels that contain less than this number of fixels, the excess volumes
-should contain either zero-filling, or NaN values. Exactly what is encoded by
-the amplitude of each XYZ triplet depends on the underlying model properties
-that were used to derive the map, with some examples being:
-
-| `<map_label>` values | Description                                                 |
-| -------------------- | ----------------------------------------------------------- |
-| PDF                  | Diffusion propagator                                        |
-| EVECS                | Eigenvectors of a model that has eigenvectors (such as DTI) |
-| PEAKS                | Directions and amplitudes of ODF maxima on the sphere       |
-
-## Describing tractography
-
-Tractography normally generates one of two primary file types: tractograms or
-NIfTi files containing maps. Tractograms are files containing a collection of
-streamlines, which are objects describing the path of idealized brain fiber
-fascicles (ensembles of neural fibers that travel together). Tractography
-visitation maps contain 3D spatial histograms of the number / fraction of
-streamlines intersecting each voxel, but do not contain the individual
-streamlines trajectories themselves. Two tractogram file formats are supported;
-tractography visitation maps should be saved as NIfTIs.
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        dwi/
-            <source_keywords>[_space-<space>][_desc-<label>][_subset-<label>]_tractography.[trk|tck|nii[.gz]]
-```
-
-### Filename keys
-
-`desc` (optional) – A way to refer to a specific instance of the tractography
-process. The combination of tractography methods and parameters that were used
-to create this tractography result should be described in the associated JSON
-file.
-
-`subset` (optional) – A label descriptor for the the subset of streamlines
-included in this file; if not specified, a whole brain tractography is assumed
-(a tractogram). Example of subsets can be `short` if only short streamlines were
-kept, or `subsampled50` if only 50% of the streamlines were kept.
-
-### File formats
-
--   [.trk - Diffusion Toolkit (+TrackVis)](https://web.archive.org/web/20190103230122/http://www.trackvis.org/docs/?subsect=fileformat)
--   [.tck - MRtrix](https://web.archive.org/web/20190103230209/https://mrtrix.readthedocs.io/en/latest/getting_started/image_data.html#tracks-file-format-tck)
-
-### JSON Metadata
-
-We have two main classes of tractography algorithms: Global or Local
-tractography, each with various supported algorithms.
-
-| Class  | Algorithms | Reference                                                                                                                            |
-| ------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| LOCAL  | PROB       | Sherbondy, A.J., et al. (2008); Tournier J.D. et al. (2012); Behrens et al. (2007)                                                   |
-| LOCAL  | DET        | Conturo, T. et al. (1999); Mori, S. et al. (1999)                                                                                    |
-| LOCAL  | EUDX       | Garyfallidis et al. (2010); Mori, S. et al. (1999)                                                                                   |
-| LOCAL  | FACT       | Jiang, H. et al. (2005)                                                                                                              |
-| LOCAL  | STT        | Lazar, M. et al. (2003)                                                                                                              |
-| LOCAL  | NULL       | Morris et al. (2008)                                                                                                                 |
-| GLOBAL | UKF        | Malcolm J-G. et al. (2009)                                                                                                           |
-| GLOBAL | SpinGlass  | Fillard P. et al. (2009)                                                                                                             |
-| GLOBAL | ENS        | Takemura et al. (2016)                                                                                                               |
-| GLOBAL | Other      | Mangin, J.F. et al. (2013); Aganj, I. et al. (2011); Neher, P.F. et al. (2012); Jbabdi, S., et al. (2007); Reisert, M. et al. (2011) |
-
-The JSON sidecar contains the following key/value pairs:
-
-| **Key name**       | **Description**                                                                                                      |
-| ------------------ | -------------------------------------------------------------------------------------------------------------------- |
-| TractographyClass  | REQUIRED. Allowed values: `local`, `global`                                                                          |
-| TractographyMethod | REQUIRED. Allowed values: `probabilistic`,`deterministic`,`eudx`,`fact`,`stt`,`null`,`ukf`,`spinglass`,`ens`,`other` |
-| Count              | REQUIRED. integer                                                                                                    |
-| Description        | OPTIONAL. string                                                                                                     |
-| Constraints        | OPTIONAL. A dictionary containing various ways in which the tractography outcome is constrained (see below).         |
-| Parameters         | OPTIONAL. A dictionary of model parameters (see below).                                                              |
-| Seeding            | OPTIONAL. A dictionary describing how streamlines were initialised (see below).                                      |
-
-RECOMMENDED to appear within the "`Constraints`" field when "`TractographyClass`" is "`local`":
-
-| **Key name**      | **Description**                                                                             |
-| ----------------- | ------------------------------------------------------------------------------------------- |
-| AnatomicalType    | {`ACT`,`CMC`}                                                                               |
-| AnatomicalImage   | string (name of anatomical tissue segmentation image)                                       |
-| Include           | list of names of inclusion ROIs (streamlines must intersect all)                            |
-| OrderedInclude    | list of names of ordered inclusion ROIs (streamlines must intersect all in order specified) |
-| Exclude           | list of names of exclusion ROIs (streamlines must not intersect any)                        |
-| Mask              | list of names of mask ROIs (streamlines must exist within)                                  |
-
-RECOMMENDED to appear within the "`Parameters`" field when "`TractographyClass`" is "`local`":
-
-| **Key name**      | **Description**                                      |
-| ----------------- | ---------------------------------------------------- |
-| Units             | {`mm`,`norm`} (applies to all within "`Parameters`") |
-| StepSize          | value                                                |
-| AngleCurvature    | value (maximum angle per step)                       |
-| RadiusCurvature   | value (minimal radius of curvature)                  |
-| MinimumLength     | value                                                |
-| MaximumLength     | value                                                |
-| IntegrationOrder  | integer                                              |
-| Unidirectional    | bool                                                 |
-
-RECOMMENDED to appear within the "Seeding" field when `TractographyClass` is `local`:
-
-| **Key name** | **Description**                                                                                                          |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------ |
-| SourceType   | {`sphere`,`voxels`,`surface`,`odf`}                                                                                      |
-| Location     | values: If "`SourceType`" is "`sphere`", provide a 4-vector containin the XYZ location and radius in mm of the sphere    |
-| Name         | string: If "`SourceType`" is not "`sphere`", give the filename from which seeds were derived                             |
-| CountType    | {`global`,`local`} (i.e. does Count reflect a count per voxel / vertex, or a single count for the entire reconstruction) |
-| Count        | integer                                                                                                                  |
-
-Example:
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        dwi/
-            sub-01_desc-DET_tractography.trk
-            sub-01_desc-DET_tractography.json
-```
-
-```JSON
-{
-    "TractographyClass": "local",
-    "TractographyMethod": "deterministic",
-    "Parameters": {
-        "StepSize": 0.5
-    }
-}
-```
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        dwi/
-            sub-01_subset-shortfibers_tractography.trk
-            sub-01_subset-shortfibers_tractography.json
-```
-
-```JSON
-{
-    "TractographyClass": "global",
-    "TractographyMethod": "UKF",
-    "Description": "UKF tracking where only short fibers were kept."
-    "Parameters": {
-        "MaximumLength": 50.0
-    }
-}
-```

From bcf6406528048d40085134996cad5758df99ef6d Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Tue, 9 Jul 2019 16:05:56 -0400
Subject: [PATCH 109/191] ENH: Restore derivative sub-BEPs to BEP list for now

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

diff --git a/src/07-extensions.md b/src/07-extensions.md
index 4d7e6bc379..2d12dac1a5 100644
--- a/src/07-extensions.md
+++ b/src/07-extensions.md
@@ -35,8 +35,11 @@ provides a direct link to the documentation.
 | [BEP004](https://docs.google.com/document/d/1kyw9mGgacNqeMbp4xZet3RnDhcMmf4_BmRgKaOkO2Sc) | Susceptibility Weighted Imaging (SWI)                                                                      | Fidel Alfaro Almagro                                                       |
 | [BEP005](https://docs.google.com/document/d/15tnn5F10KpgHypaQJNNGiNKsni9035GtDqJzWqkkP6c) | Arterial Spin Labeling (ASL)                                                                               | Henk-Jan Mutsaerts and Michael Chappell                                    |
 | [BEP009](https://docs.google.com/document/d/1mqMLnxVdLwZjDd4ZiWFqjEAmOmfcModA_R535v3eQs0) | Positron Emission Tomography (PET)                                                                         | Melanie Ganz                                                               |
+| [BEP011](https://docs.google.com/document/d/1YG2g4UkEio4t_STIBOqYOwneLEs1emHIXbGKynx7V0Y) | The structural preprocessing derivatives                                                                   | Andrew Hoopes                                                              |
+| [BEP012](https://docs.google.com/document/d/16CvBwVMAs0IMhdoKmlmcm3W8254dQmNARo-7HhE-lJU) | The functional preprocessing derivatives                                                                   | Camille Maumet and Chris Markiewicz                                        |
 | [BEP014](https://docs.google.com/document/d/11gCzXOPUbYyuQx8fErtMO9tnOKC3kTWiL9axWkkILNE) | The affine transformations and nonlinear field warps                                                       | Oscar Esteban                                                              |
 | [BEP015](https://docs.google.com/document/d/1WYOTXDB7GzlHoWqLjd45I3uGBgPxXddST-NTqBnroJE) | Mapping file                                                                                               | Eric Earl, Camille Maumet, and Vasudev Raguram                             |
+| [BEP016](https://docs.google.com/document/d/1cQYBvToU7tUEtWMLMwXUCB_T8gebCotE1OczUpMYW60) | The diffusion weighted imaging derivatives                                                                 | Franco Pestilli and Oscar Esteban                                          |
 | [BEP017](https://docs.google.com/document/d/1ugBdUF6dhElXdj3u9vw0iWjE6f_Bibsro3ah7sRV0GA) | Generic BIDS connectivity data schema                                                                      | Eugene Duff and Paul McCarthy                                              |
 | [BEP018](https://docs.google.com/document/d/1uRkgyzESLKuGjXi98Z97Wh6vt-iLN5nOAb9TG16CjUs) | Genetic information                                                                                        | Cyril R Pernet, Clara Moreau, and Thomas Nichols                           |
 | [BEP019](https://docs.google.com/document/d/1FqJI791ycXr0bfRg2qyLqAf0RpVttJ2cInOgMWrKsNU) | DICOM Metadata                                                                                             | Satrajit Ghosh                                                             |
@@ -58,16 +61,13 @@ of the specification.
 | [BEP007](https://docs.google.com/document/d/1gs7USIVO1OApZs3IVo6TeXw9_tfzxhjM2-m--ex4g6o) | Hierarchical Event Descriptor (HED) Tags   | Chris Gorgolewski                                 |
 | [BEP008](https://docs.google.com/document/d/1FWex_kSPWVh_f4rKgd5rxJmxlboAPtQlmBc1gyZlRZM) | Magnetoencephalography (MEG)               | Guiomar Niso                                      |
 | [BEP010](https://docs.google.com/document/d/1qMUkoaXzRMlJuOcfTYNr3fTsrl4SewWjffjMD5Ew6GY) | intracranial Electroencephalograpgy (iEEG) | Chris Holdgraf, Dora Hermes                       |
-| [BEP003](https://docs.google.com/document/d/1Wwc4A6Mow4ZPPszDIWfCUCRNstn7d_zzaWPcfcHmgI4) | Common Derivatives                                                                                         | Chris Gorgolewski                                                          |
+| [BEP003](https://docs.google.com/document/d/1Wwc4A6Mow4ZPPszDIWfCUCRNstn7d_zzaWPcfcHmgI4) | Common Derivatives                         | Chris Gorgolewski                                 |
 
 BEPs that have been closed down or merged into other BEPs:
 
 | Extension label                                                                           | Title                                                                                                      | What happened?                                                             |
 | :---------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------- |
-| [BEP011](https://docs.google.com/document/d/1YG2g4UkEio4t_STIBOqYOwneLEs1emHIXbGKynx7V0Y) | The structural preprocessing derivatives                                                                   | merged into BEP003                                                         |
-| [BEP012](https://docs.google.com/document/d/16CvBwVMAs0IMhdoKmlmcm3W8254dQmNARo-7HhE-lJU) | The functional preprocessing derivatives                                                                   | merged into BEP003                                                         |
-| [BEP013](https://docs.google.com/document/d/1qBNQimDx6CuvHjbDvuFyBIrf2WRFUOJ-u50canWjjaw) | The resting state fMRI derivatives                                                                         | merged into BEP003                                                         |
-| [BEP016](https://docs.google.com/document/d/1cQYBvToU7tUEtWMLMwXUCB_T8gebCotE1OczUpMYW60) | The diffusion weighted imaging derivatives                                                                 | merged into BEP003                                                         |
+| [BEP013](https://docs.google.com/document/d/1qBNQimDx6CuvHjbDvuFyBIrf2WRFUOJ-u50canWjjaw) | The resting state fMRI derivatives                                                                         | merged into BEP012                                                         |
 
 All of the extension ideas that are not backwards compatible and thus
 will have to wait for BIDS 2.0 are listed

From e4a4d6571aa5b8cd5790af508801ba73abfef9d5 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Tue, 9 Jul 2019 16:12:05 -0400
Subject: [PATCH 110/191] FIX: Remove modality-specific files from mkdocs.yml

---
 mkdocs.yml | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/mkdocs.yml b/mkdocs.yml
index 31f382b250..4e40283ef0 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -30,9 +30,6 @@ nav:
       - Derivatives:
         - Introduction: 05-derivatives/01-introduction.md
         - Common data types: 05-derivatives/02-common-data-types.md
-        - Structural derivatives: 05-derivatives/03-structural-derivatives.md
-        - Functional derivatives: 05-derivatives/04-functional-derivatives.md
-        - Diffusion derivatives: 05-derivatives/05-diffusion-derivatives.md
       - Longitudinal and multi-site studies: 06-longitudinal-and-multi-site-studies.md
       - Extending the BIDS specification: 07-extensions.md
       - Appendix:

From f880fff30fce1c386beecf3fe73a1f4a605ff387 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Mon, 15 Jul 2019 14:23:19 -0400
Subject: [PATCH 111/191] Apply suggestions from code review

Co-Authored-By: Franklin Feingold <35307458+franklin-feingold@users.noreply.github.com>
---
 src/05-derivatives/02-common-data-types.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index 88f3e01d29..c4483e5970 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>/
-        func|anat|dwi/
+        anat|func|dwi/
         <source_keywords>[_space-<space>][_desc-<label>]_<suffix>.<ext>
 ```
 
@@ -73,7 +73,7 @@ Template:
 ```Text
 <pipeline_name>/
     sub-<participant_label>/
-        func|anat|dwi/
+        anat|func|dwi/
         <source_keywords>[_space-<space>][_desc-<label>]_mask.nii.gz
 ```
 
@@ -118,7 +118,7 @@ Common JSON metadata fields:
 ### Discrete Segmentations
 
 Discrete segmentations of brain tissue represent each tissue class with a unique
-integer label in a 3D volume. See "Anatomical Labels" for interpretation how
+integer label in a 3D volume. See [Anatomical Labels](#anatomical-labels) for interpretation how
 integer values map to tissue classes.
 
 Template:
@@ -126,7 +126,7 @@ Template:
 ```Text
 <pipeline_name>/
     sub-<participant_label>/
-        func|anat|dwi/
+        anat|func|dwi/
             <source_keywords>[_space-<space>]_dseg.nii.gz
 ```
 
@@ -151,7 +151,7 @@ pipeline/
             sub-001_space-orig_label-GM_dseg.nii.gz
 ```
 
-See "Anatomical labels" for reserved key values for `label`.
+See [Anatomical Labels](#anatomical-labels) for reserved key values for `label`.
 
 ### Probabilistic Segmentations
 
@@ -179,7 +179,7 @@ pipeline/
             sub-001_space-orig_label-WM_probseg.nii.gz
 ```
 
-See "Anatomical labels" for reserved key values for `label`.
+See [Anatomical labels](#anatomical-labels) for reserved key values for `label`.
 
 A 4D probabilistic segmentation, in which each frame corresponds to a different
 tissue class, must provide a label mapping in its JSON sidecar. For example:
@@ -205,7 +205,7 @@ for each volume:
 }
 ```
 
-Values of `label` need to map to Abbreviations defined in "Anatomical Labels".
+Values of `label` need to map to Abbreviations defined in [Anatomical Labels](#anatomical-labels).
 
 ### Surface Parcellations
 
@@ -221,7 +221,7 @@ Template:
             <source_keywords>[_hemi-{L|R}][_space-<space>]_dseg.{label.gii|dlabel.nii}
 ```
 
-The REQUIRED extension for GIFTI parcellations is `.label.gii`. The hemi tag is
+The REQUIRED extension for GIFTI parcellations is `.label.gii`. The `hemi` tag is
 REQUIRED for GIFTI files. For example:
 
 ```Text

From ac1c4fee8a243d8ee70e24594881d60f0d798e37 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Tue, 16 Jul 2019 09:48:07 -0400
Subject: [PATCH 112/191] Apply suggestions from code review

---
 src/05-derivatives/01-introduction.md      | 6 +++---
 src/05-derivatives/02-common-data-types.md | 5 ++++-
 2 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 765b873ab4..8e8af9c195 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -97,8 +97,8 @@ keyword depend on the file format:
 
 | File format                  | Description             | Allowed `CoordinateSystem` values                                                                                                                                                                             |
 | ---------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| NIfTI (`.nii` and `.nii.gz`) | Volume data             | Coordinate systems listed in [Template Based Coordinate Systems: Volume](../99-appendices/08-coordinate-systems.md#volume). If `individual` or `custom` is used then setting `SpatialReference` is REQUIRED   |
-| GIFTI (`.gii`)               | Surface data            | Coordinate systems listed in [Template Based Coordinate Systems: Surface](../99-appendices/08-coordinate-systems.md#surface). If `individual` or `custom` is used then setting `SpatialReference` is REQUIRED |
+| NIfTI (`.nii` and `.nii.gz`) | Volume data             | Coordinate systems listed in [Template Based Coordinate Systems: Volume](../99-appendices/08-coordinate-systems.md#volume). If `individual` or `custom` is used then setting [`SpatialReference`](#spatialreference-key-allowed-values) is REQUIRED   |
+| GIFTI (`.gii`)               | Surface data            | Coordinate systems listed in [Template Based Coordinate Systems: Surface](../99-appendices/08-coordinate-systems.md#surface). If `individual` or `custom` is used then setting [`SpatialReference`](#spatialreference-key-allowed-values) is REQUIRED |
 | CIFTI (`.nii`)               | Volume and surface data | Coordinate systems listed in [Template Based Coordinate Systems: Hybrid (Volume/Surface) aliases](../99-appendices/08-coordinate-systems.md#hybrid-volumesurface-aliases)                                     |
 
 Examples:
@@ -201,7 +201,7 @@ sub-01/anat/sub-01_hemi-L_space-individual_thickness.json
     the keyword)
 
 -   When the derivatives chain involves outputs derived from a single raw input,
-    `source_keywords` MUST be the entire source filename, with the ommission of
+    `source_keywords` MUST be the entire source filename, with the omission of
     the source suffix and extension. One exception to this rule is filename
     keywords that are no longer relevant. Depending on the nature of the
     derivative file, the suffix can either be the same as the source file if
diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index c4483e5970..e6e32edf83 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -21,12 +21,15 @@ data types in the specification. Examples:
 -   Inhomogeneity corrected and skull stripped T1w files.
 
 -   Motion-corrected DWI files.
+- Time-domain filtered and ICA cleaned EEG data
 
 The `space` keyword is recomended to distinguish files with different underlying
 coordinate systems or registered to different reference maps. The
 `desc` keyword is a general purpose field with freeform values. To distinguish
 between multiple different versions of processing for the same input data the
-`desc` keyword should be used. Note that even though `space` and `desc` are
+`desc` keyword should be used.
+
+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.
 

From e1de6dec0ed32a0608a4a1b5f7137da0cc42f645 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Tue, 16 Jul 2019 12:33:31 -0400
Subject: [PATCH 113/191] FIX: Table alignment

---
 src/05-derivatives/01-introduction.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 8e8af9c195..54fa439b57 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -95,11 +95,11 @@ 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 on the file format:
 
-| File format                  | Description             | Allowed `CoordinateSystem` values                                                                                                                                                                             |
-| ---------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| File format                  | Description             | Allowed `CoordinateSystem` values                                                                                                                                                                                                                     |
+| ---------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | NIfTI (`.nii` and `.nii.gz`) | Volume data             | Coordinate systems listed in [Template Based Coordinate Systems: Volume](../99-appendices/08-coordinate-systems.md#volume). If `individual` or `custom` is used then setting [`SpatialReference`](#spatialreference-key-allowed-values) is REQUIRED   |
 | GIFTI (`.gii`)               | Surface data            | Coordinate systems listed in [Template Based Coordinate Systems: Surface](../99-appendices/08-coordinate-systems.md#surface). If `individual` or `custom` is used then setting [`SpatialReference`](#spatialreference-key-allowed-values) is REQUIRED |
-| CIFTI (`.nii`)               | Volume and surface data | Coordinate systems listed in [Template Based Coordinate Systems: Hybrid (Volume/Surface) aliases](../99-appendices/08-coordinate-systems.md#hybrid-volumesurface-aliases)                                     |
+| CIFTI (`.nii`)               | Volume and surface data | Coordinate systems listed in [Template Based Coordinate Systems: Hybrid (Volume/Surface) aliases](../99-appendices/08-coordinate-systems.md#hybrid-volumesurface-aliases)                                                                             |
 
 Examples:
 

From 064cad480a8110c42e0a57c9855d4cc2e26bc732 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Tue, 16 Jul 2019 12:40:20 -0400
Subject: [PATCH 114/191] FIX: Consistent list

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

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index e6e32edf83..8043c1e856 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -15,12 +15,9 @@ Processing in this context means transformations of data that does not change
 the number of dimensions of the input and are not explicitly covered by other
 data types in the specification. Examples:
 
--   Motion-corrected, temporally denoised, and transformed to MNI space bold
-    files.
-
--   Inhomogeneity corrected and skull stripped T1w files.
-
--   Motion-corrected DWI files.
+- Motion-corrected, temporally denoised, and transformed to MNI space bold files.
+- Inhomogeneity corrected and skull stripped T1w files.
+- Motion-corrected DWI files.
 - Time-domain filtered and ICA cleaned EEG data
 
 The `space` keyword is recomended to distinguish files with different underlying

From 442b98de5deee06201439e3a5dd0a875cdec3970 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Tue, 16 Jul 2019 14:43:54 -0400
Subject: [PATCH 115/191] FIX: Weird list style

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

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index 8043c1e856..ec82699a5c 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -15,10 +15,10 @@ Processing in this context means transformations of data that does not change
 the number of dimensions of the input and are not explicitly covered by other
 data types in the specification. Examples:
 
-- Motion-corrected, temporally denoised, and transformed to MNI space bold files.
-- Inhomogeneity corrected and skull stripped T1w files.
-- Motion-corrected DWI files.
-- Time-domain filtered and ICA cleaned EEG data
+-  Motion-corrected, temporally denoised, and transformed to MNI space bold files.
+-  Inhomogeneity corrected and skull stripped T1w files.
+-  Motion-corrected DWI files.
+-  Time-domain filtered and ICA cleaned EEG data
 
 The `space` keyword is recomended to distinguish files with different underlying
 coordinate systems or registered to different reference maps. The

From cad13ddc726a5822a299171e45b0e24c4327d356 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Tue, 16 Jul 2019 14:57:18 -0400
Subject: [PATCH 116/191] FIX: Weird list style

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

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index ec82699a5c..d348f4b20a 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -15,10 +15,10 @@ Processing in this context means transformations of data that does not change
 the number of dimensions of the input and are not explicitly covered by other
 data types in the specification. Examples:
 
--  Motion-corrected, temporally denoised, and transformed to MNI space bold files.
--  Inhomogeneity corrected and skull stripped T1w files.
--  Motion-corrected DWI files.
--  Time-domain filtered and ICA cleaned EEG data
+ -  Motion-corrected, temporally denoised, and transformed to MNI space bold files.
+ -  Inhomogeneity corrected and skull stripped T1w files.
+ -  Motion-corrected DWI files.
+ -  Time-domain filtered and ICA cleaned EEG data
 
 The `space` keyword is recomended to distinguish files with different underlying
 coordinate systems or registered to different reference maps. The

From 7bde6ce4d8358805215ca2b65b2c1e1874b3b360 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Wed, 14 Aug 2019 15:13:59 -0400
Subject: [PATCH 117/191] FIX: Clarify naming derivatives after pipeline

---
 src/05-derivatives/01-introduction.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 54fa439b57..3e45ea848a 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -17,13 +17,14 @@ Derivatives can be stored/distributed in two ways:
     RECOMMENDED to use the format `<pipeline>-<variant>` in cases where it is
     anticipated that the same pipeline will output more than one variant (e.g.,
     `AFNI-blurring`, `AFNI-noblurring`, etc.). For the sake of consistency, the
-    subfolder name MUST be a substring of `PipelineDescription.Name` field in
-    the `dataset_description.json` (see below).
+    subfolder name MUST be the `PipelineDescription.Name` field in
+    `data_description.json`, optionally followed by a hyphen and a suffix (see
+    below).
 
     For example:
 
     ```Plain
-    <dataset>/derivatives/fmripreprocess-v1/sub-0001
+    <dataset>/derivatives/fmriprep-v1.4.1/sub-0001
     <dataset>/derivatives/spm/sub-0001
     <dataset>/derivatives/vbm/sub-0001
     ```

From 85c54ea25fb54bf42b4f2dbaa7d12109672c6866 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Wed, 14 Aug 2019 15:23:26 -0400
Subject: [PATCH 118/191] RF: Abstract PipelineDescription.Container from
 Docker and Singularity-specific tags

---
 src/05-derivatives/01-introduction.md | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 3e45ea848a..9172f94edd 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -59,14 +59,13 @@ In addition to raw BIDS datasets, derived BIDS datasets include the following
 required or recommended `dataset_description.json` keys (a dot in the Key name
 denotes a key in a subdictionary):
 
-| **Key name**                                | **Description**                                                                                                                                                                                                                              |
-| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 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.DockerHubContainerTag   | OPTIONAL. Docker Hub tag where the software container image used in this analysis can be found.                                                                                                                                              |
-| PipelineDescription.SingularityContainerURL | OPTIONAL. URL where the Singularity software container image used in this analysis can be found.                                                                                                                                             |
-| 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`.                                                                        |
+| **Key name**                  | **Description**                                                                                                                                                                                                                              |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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`.
+| 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:
 
@@ -77,7 +76,10 @@ Example:
     "PipelineDescription": {
         "Name": "FMRIPREP",
         "Version": "1.2.5",
-        "DockerHubContainerTag": "poldracklab/fmriprep:1.2.5"
+        "Container": {
+            "Type": "docker",
+            "Tag": "poldracklab/fmriprep:1.2.5"
+            }
         },
     "SourceDatasets": [
         {

From 64d306a5767b6b8ce4752ecc452c090a6eabbeaa Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Wed, 14 Aug 2019 12:55:03 -0700
Subject: [PATCH 119/191] Pacify linkchecker

---
 src/02-common-principles.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index df209d8e17..85d054153a 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -161,7 +161,7 @@ field in `dataset_description.json` of each subfolder of `derivatives` to:
 }
 ```
 
-See [Derived dataset and pipeline description](05-derivatives/01-introduction.md#Derived-dataset-and-pipeline-description)
+See [Derived dataset and pipeline description](05-derivatives/01-introduction.md#derived-dataset-and-pipeline-description)
 for more information.
 
 ## The Inheritance Principle

From 9f95aa6dd1811da62eb00f3c197582b8d8b04d18 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Thu, 15 Aug 2019 11:24:40 -0700
Subject: [PATCH 120/191] [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 6921e62c4bc733d9475ce00339882f0808207158 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Fri, 16 Aug 2019 09:17:13 -0400
Subject: [PATCH 121/191] [SPEC] Separate out imaging-specific "common
 derivatives"

---
 src/05-derivatives/02-common-data-types.md | 273 +--------------------
 src/05-derivatives/03-imaging.md           | 268 ++++++++++++++++++++
 2 files changed, 280 insertions(+), 261 deletions(-)
 create mode 100644 src/05-derivatives/03-imaging.md

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index d348f4b20a..cdcbaf304f 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -1,6 +1,6 @@
 # Common data types
 
-## Processed, coregistered and/or resampled volumes
+## Preprocessed or cleaned data
 
 Template:
 
@@ -11,24 +11,23 @@ Template:
         <source_keywords>[_space-<space>][_desc-<label>]_<suffix>.<ext>
 ```
 
-Processing in this context means transformations of data that does not change
+Preprocessing in this context means transformations of data that do not change
 the number of dimensions of the input and are not explicitly covered by other
 data types in the specification. Examples:
 
- -  Motion-corrected, temporally denoised, and transformed to MNI space bold files.
- -  Inhomogeneity corrected and skull stripped T1w files.
- -  Motion-corrected DWI files.
+ -  Motion-corrected, temporally denoised, and transformed to MNI space BOLD series
+ -  Inhomogeneity corrected and skull stripped T1w files
+ -  Motion-corrected DWI files
  -  Time-domain filtered and ICA cleaned EEG data
 
 The `space` keyword is recomended to distinguish files with different underlying
-coordinate systems or registered to different reference maps. The
-`desc` keyword is a general purpose field with freeform values. To distinguish
-between multiple different versions of processing for the same input data the
-`desc` keyword should be used.
+coordinate systems or registered to different reference maps.
+The `desc` keyword is a general purpose field with freeform values.
+To distinguish between multiple different versions of processing for the same
+input data the `desc` keyword should be used.
 
-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.
+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.
 
 Examples:
 
@@ -59,253 +58,5 @@ pipeline1/
 All REQUIRED metadata fields coming from a derivative file’s source file(s) MUST
 be propagated to the JSON description of the derivative unless the processing
 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:
+static volume, a SamplingFrequency property would no longer be relevant).
 
-| **Key name**  | **Description**                                                                                 |
-| ------------- | ----------------------------------------------------------------------------------------------- |
-| SkullStripped | REQUIRED. Boolean. Whether the volume was skull stripped (non-brain voxels set to zero) or not. |
-
-## Masks
-
-Template:
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        anat|func|dwi/
-        <source_keywords>[_space-<space>][_desc-<label>]_mask.nii.gz
-```
-
-A binary (1 - inside, 0 - outside) mask in the space defined by `<space>`. By
-default (i.e., if no transformation has taken place) the value of `space` should
-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 |
-
-Examples:
-
-```Text
-func_loc/
-    sub-001/
-        func/
-           sub-001_task-rest_run-1_space-MNI305_desc-PFC_mask.nii.gz
-           sub-001_task-rest_run-1_space-MNI305_desc-PFC_mask.json
-```
-
-```Text
-manual_masks/
-    sub-001/
-        anat/
-            sub-001_desc-tumor_mask.nii.gz
-            sub-001_desc-tumor_mask.json
-```
-
-## Segmentations and parcellations
-
-Common JSON metadata fields:
-
-| **Key name** | **Description**                                                                                    |
-| ------------ | -------------------------------------------------------------------------------------------------- |
-| Manual       | OPTIONAL. Boolean. Indicates if the segmenation was performed manually or via an automated process |
-| Atlas        | OPTIONAL. Which atlas (if any) was used to derive the segmentation.                                |
-
-### Discrete Segmentations
-
-Discrete segmentations of brain tissue represent each tissue class with a unique
-integer label in a 3D volume. See [Anatomical Labels](#anatomical-labels) for interpretation how
-integer values map to tissue classes.
-
-Template:
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        anat|func|dwi/
-            <source_keywords>[_space-<space>]_dseg.nii.gz
-```
-
-Example:
-
-```Text
-pipeline/
-    sub-001/
-        anat/
-            sub-001_space-orig_dseg.nii.gz
-            sub-001_space-orig_dseg.json
-```
-
-A segmentation could be a binary mask that functions as a discrete `label` for a
-single structure. In this case, the label key must be used to specify the
-corresponding structure. For example:
-
-```Text
-pipeline/
-    sub-001/
-        anat/
-            sub-001_space-orig_label-GM_dseg.nii.gz
-```
-
-See [Anatomical Labels](#anatomical-labels) for reserved key values for `label`.
-
-### Probabilistic Segmentations
-
-Probabilistic segmentations of brain tissue represent a single tissue class with
-values ranging from 0 to 1 in individual 3D volumes or across multiple frames.
-Similarly to a discrete, binary segmentation, the label key can be used to
-specify the corresponding structure.
-
-Template:
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        func|anat|dwi/
-            <source_keywords>[space-<space>][_label-<label>]_probseg.nii.gz
-```
-
-Example:
-
-```Text
-pipeline/
-    sub-001/
-        anat/
-            sub-001_space-orig_label-BG_probseg.nii.gz
-            sub-001_space-orig_label-WM_probseg.nii.gz
-```
-
-See [Anatomical labels](#anatomical-labels) for reserved key values for `label`.
-
-A 4D probabilistic segmentation, in which each frame corresponds to a different
-tissue class, must provide a label mapping in its JSON sidecar. For example:
-
-```Text
-pipeline/
-    sub-001/
-	    anat/
-		    sub-001_space-orig_probseg.nii.gz
-		    sub-001_space-orig_probseg.json
-```
-
-The JSON sidecar must include the label-map key that specifies a tissue label
-for each volume:
-
-```JSON
-{
-    "LabelMap": [
-        "BG",
-        "WM",
-        "GM"
-        ]
-}
-```
-
-Values of `label` need to map to Abbreviations defined in [Anatomical Labels](#anatomical-labels).
-
-### Surface Parcellations
-
-Discrete parcellations (surface segmentations) of cortical structures should be
-stored as GIFTI or CIFTI file.
-
-Template:
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        anat/
-            <source_keywords>[_hemi-{L|R}][_space-<space>]_dseg.{label.gii|dlabel.nii}
-```
-
-The REQUIRED extension for GIFTI parcellations is `.label.gii`. The `hemi` tag is
-REQUIRED for GIFTI files. For example:
-
-```Text
-pipeline/
-    sub-001/
-        anat/
-            sub-001_hemi-L_dparc.label.gii
-            sub-001_hemi-R_dparc.label.gii
-```
-
-The REQUIRED extension for CIFTI parcellations is `.dlabel.nii`. For example:
-
-```Text
-pipeline/
-    sub-001/
-        anat/
-            sub-001_dparc.dlabel.nii
-            sub-001_dparc.dlabel.nii
-```
-
-### Anatomical Labels
-
-BIDS supplies a standard, generic label-index dictionary, defined in the table
-below, that contains common tissue classes and can be used to map segmentations
-(and parcellations) between lookup tables.
-
-| Integer value | Description             | Abbreviation (label) |
-| ------------- | ----------------------- | -------------------- |
-| 0             | Background              | BG                   |
-| 1             | Grey Matter             | GM                   |
-| 2             | White Matter            | WM                   |
-| 3             | Cerebrospinal Fluid     | CSF                  |
-| 4             | Grey and White Matter   | GWM                  |
-| 5             | Bone                    | B                    |
-| 6             | Soft Tissue             | ST                   |
-| 7             | Non-brain               | NB                   |
-| 8             | Lesion                  | L                    |
-| 9             | Cortical Grey Matter    | CGM                  |
-| 10            | Subcortical Grey Matter | SCGM                 |
-| 11            | Brainstem               | BS                   |
-| 12            | Cerebellum              | CBM                  |
-
-These definitions can be overridden (or added to) by providing custom labels in
-a sidecar `<matches>.tsv` file, in which `<matches>` corresponds to segmentation
-filename.
-
-Example:
-
-```Text
-pipeline/
-    sub-001/
-        anat/
-            sub-001_space-orig_dseg.nii.gz
-            sub-001_space-orig_dseg.tsv
-```
-
-Definitions can also be specified with a top-level dseg.tsv, which propagates to
-segmentations in relative subdirectories.
-
-Example:
-
-```Text
-pipeline/
-    dseg.tsv
-    sub-001/
-        anat/
-            sub-001_space-orig_dseg.nii.gz
-```
-
-These tsv lookup tables should contain the following columns:
-
-| Column name | Description                                                             |
-| ----------- | ----------------------------------------------------------------------- |
-| index       | REQUIRED. The label integer index                                       |
-| name        | REQUIRED. The unique label name                                         |
-| abbr        | OPTIONAL. The unique label abbreviation                                 |
-| mapping     | OPTIONAL. Corresponding integer label in the standard BIDS label lookup |
-| color       | OPTIONAL. Hexadecimal. Label color for visualization                    |
-
-An example, custom dseg.tsv that defines three labels:
-
-```Text
-index   name            abbr	color       mapping
-100     "Grey Matter"	GM      #ff53bb	    1
-101     "White Matter"	WM      #2f8bbe	    2
-102     "Brainstem"     BS      #36de72	    11
-```
diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
new file mode 100644
index 0000000000..8a1f9dbc6c
--- /dev/null
+++ b/src/05-derivatives/03-imaging.md
@@ -0,0 +1,268 @@
+# Imaging data types
+
+This section pertains to imaging data, which characteristically have spatial
+extent and resolution.
+
+## Preprocessed, coregistered and/or resampled volumes
+
+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:
+
+| **Key name**  | **Description**                                                                                 |
+| ------------- | ----------------------------------------------------------------------------------------------- |
+| SkullStripped | REQUIRED. Boolean. Whether the volume was skull stripped (non-brain voxels set to zero) or not. |
+
+
+## Masks
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        anat|func|dwi/
+            <source_keywords>[_space-<space>][_desc-<label>]_mask.nii.gz
+```
+
+A binary (1 - inside, 0 - outside) mask in the space defined by `<space>`. By
+default (i.e., if no transformation has taken place) the value of `space` should
+be set to `orig`.
+
+JSON metadata fields:
+
+| **Key name** | **Description**                                                                                                                                |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| RawSources   | Same as defined in [Introduction][intro], 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 |
+
+Examples:
+
+```Text
+func_loc/
+    sub-001/
+        func/
+           sub-001_task-rest_run-1_space-MNI305_desc-PFC_mask.nii.gz
+           sub-001_task-rest_run-1_space-MNI305_desc-PFC_mask.json
+```
+
+```Text
+manual_masks/
+    sub-001/
+        anat/
+            sub-001_desc-tumor_mask.nii.gz
+            sub-001_desc-tumor_mask.json
+```
+
+## Segmentations and parcellations
+
+Common JSON metadata fields:
+
+| **Key name** | **Description**                                                                                    |
+| ------------ | -------------------------------------------------------------------------------------------------- |
+| Manual       | OPTIONAL. Boolean. Indicates if the segmenation was performed manually or via an automated process |
+| Atlas        | OPTIONAL. Which atlas (if any) was used to derive the segmentation.                                |
+
+### Discrete Segmentations
+
+Discrete segmentations of brain tissue represent each tissue class with a unique
+integer label in a 3D volume. See [Anatomical Labels](#anatomical-labels) for interpretation how
+integer values map to tissue classes.
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        anat|func|dwi/
+            <source_keywords>[_space-<space>]_dseg.nii.gz
+```
+
+Example:
+
+```Text
+pipeline/
+    sub-001/
+        anat/
+            sub-001_space-orig_dseg.nii.gz
+            sub-001_space-orig_dseg.json
+```
+
+A segmentation could be a binary mask that functions as a discrete `label` for a
+single structure. In this case, the label key must be used to specify the
+corresponding structure. For example:
+
+```Text
+pipeline/
+    sub-001/
+        anat/
+            sub-001_space-orig_label-GM_dseg.nii.gz
+```
+
+See [Anatomical Labels](#anatomical-labels) for reserved key values for `label`.
+
+### Probabilistic Segmentations
+
+Probabilistic segmentations of brain tissue represent a single tissue class with
+values ranging from 0 to 1 in individual 3D volumes or across multiple frames.
+Similarly to a discrete, binary segmentation, the label key can be used to
+specify the corresponding structure.
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        func|anat|dwi/
+            <source_keywords>[space-<space>][_label-<label>]_probseg.nii.gz
+```
+
+Example:
+
+```Text
+pipeline/
+    sub-001/
+        anat/
+            sub-001_space-orig_label-BG_probseg.nii.gz
+            sub-001_space-orig_label-WM_probseg.nii.gz
+```
+
+See [Anatomical labels](#anatomical-labels) for reserved key values for `label`.
+
+A 4D probabilistic segmentation, in which each frame corresponds to a different
+tissue class, must provide a label mapping in its JSON sidecar. For example:
+
+```Text
+pipeline/
+    sub-001/
+	    anat/
+		    sub-001_space-orig_probseg.nii.gz
+		    sub-001_space-orig_probseg.json
+```
+
+The JSON sidecar must include the label-map key that specifies a tissue label
+for each volume:
+
+```JSON
+{
+    "LabelMap": [
+        "BG",
+        "WM",
+        "GM"
+        ]
+}
+```
+
+Values of `label` need to map to Abbreviations defined in [Anatomical Labels](#anatomical-labels).
+
+### Surface Parcellations
+
+Discrete parcellations (surface segmentations) of cortical structures should be
+stored as GIFTI or CIFTI file.
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        anat/
+            <source_keywords>[_hemi-{L|R}][_space-<space>]_dseg.{label.gii|dlabel.nii}
+```
+
+The REQUIRED extension for GIFTI parcellations is `.label.gii`. The `hemi` tag is
+REQUIRED for GIFTI files. For example:
+
+```Text
+pipeline/
+    sub-001/
+        anat/
+            sub-001_hemi-L_dparc.label.gii
+            sub-001_hemi-R_dparc.label.gii
+```
+
+The REQUIRED extension for CIFTI parcellations is `.dlabel.nii`. For example:
+
+```Text
+pipeline/
+    sub-001/
+        anat/
+            sub-001_dparc.dlabel.nii
+            sub-001_dparc.dlabel.nii
+```
+
+### Anatomical Labels
+
+BIDS supplies a standard, generic label-index dictionary, defined in the table
+below, that contains common tissue classes and can be used to map segmentations
+(and parcellations) between lookup tables.
+
+| Integer value | Description             | Abbreviation (label) |
+| ------------- | ----------------------- | -------------------- |
+| 0             | Background              | BG                   |
+| 1             | Grey Matter             | GM                   |
+| 2             | White Matter            | WM                   |
+| 3             | Cerebrospinal Fluid     | CSF                  |
+| 4             | Grey and White Matter   | GWM                  |
+| 5             | Bone                    | B                    |
+| 6             | Soft Tissue             | ST                   |
+| 7             | Non-brain               | NB                   |
+| 8             | Lesion                  | L                    |
+| 9             | Cortical Grey Matter    | CGM                  |
+| 10            | Subcortical Grey Matter | SCGM                 |
+| 11            | Brainstem               | BS                   |
+| 12            | Cerebellum              | CBM                  |
+
+These definitions can be overridden (or added to) by providing custom labels in
+a sidecar `<matches>.tsv` file, in which `<matches>` corresponds to segmentation
+filename.
+
+Example:
+
+```Text
+pipeline/
+    sub-001/
+        anat/
+            sub-001_space-orig_dseg.nii.gz
+            sub-001_space-orig_dseg.tsv
+```
+
+Definitions can also be specified with a top-level dseg.tsv, which propagates to
+segmentations in relative subdirectories.
+
+Example:
+
+```Text
+pipeline/
+    dseg.tsv
+    sub-001/
+        anat/
+            sub-001_space-orig_dseg.nii.gz
+```
+
+These tsv lookup tables should contain the following columns:
+
+| Column name | Description                                                             |
+| ----------- | ----------------------------------------------------------------------- |
+| index       | REQUIRED. The label integer index                                       |
+| name        | REQUIRED. The unique label name                                         |
+| abbr        | OPTIONAL. The unique label abbreviation                                 |
+| mapping     | OPTIONAL. Corresponding integer label in the standard BIDS label lookup |
+| color       | OPTIONAL. Hexadecimal. Label color for visualization                    |
+
+An example, custom dseg.tsv that defines three labels:
+
+```Text
+index   name            abbr	color       mapping
+100     "Grey Matter"	GM      #ff53bb	    1
+101     "White Matter"	WM      #2f8bbe	    2
+102     "Brainstem"     BS      #36de72	    11
+```
+
+
+[]: <> (################)
+[]: <> (Link definitions)
+[]: <> (################)
+
+[intro]: 01-introduction.md
+[common_preproc]: 02-common-data-types.md#preprocessed-or-cleaned-data

From 2bc990d5d3ff69f2c585ac1445c85899564b6c85 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Wed, 4 Sep 2019 11:22:07 -0400
Subject: [PATCH 122/191] ENH: Clarify data type, EEG examples, space/desc
 wording

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

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index cdcbaf304f..6e58e42d23 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -7,27 +7,29 @@ Template:
 ```Text
 <pipeline_name>/
     sub-<participant_label>/
-        anat|func|dwi/
-        <source_keywords>[_space-<space>][_desc-<label>]_<suffix>.<ext>
+        <datatype>/
+            <source_keywords>[_space-<space>][_desc-<label>]_<suffix>.<ext>
 ```
 
 Preprocessing in this context means transformations of data that do not change
 the number of dimensions of the input and are not explicitly covered by other
-data types in the specification. Examples:
+data types in the specification.
+Examples:
 
  -  Motion-corrected, temporally denoised, and transformed to MNI space BOLD series
  -  Inhomogeneity corrected and skull stripped T1w files
  -  Motion-corrected DWI files
- -  Time-domain filtered and ICA cleaned EEG data
+ -  Time-domain filtered EEG data
+ -  Spatially filtered EEG data
 
 The `space` keyword is recomended to distinguish files with different underlying
 coordinate systems or registered to different reference maps.
-The `desc` keyword is a general purpose field with freeform values.
-To distinguish between multiple different versions of processing for the same
-input data the `desc` keyword should be used.
+The `desc` (description) keyword is a general purpose field with freeform values,
+which SHOULD be used to distinguish between multiple different versions of
+processing for the same input data.
 
-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.
+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.
 
 Examples:
 
@@ -59,4 +61,3 @@ All REQUIRED metadata fields coming from a derivative file’s source file(s) MU
 be propagated to the JSON description of the derivative unless the processing
 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).
-

From c384f97261f92f5a678ad406fd25924ee2455ae8 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Fri, 16 Aug 2019 07:50:25 -0700
Subject: [PATCH 123/191] [STY] Remove blank lines

---
 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 8a1f9dbc6c..ff94830bb3 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -14,7 +14,6 @@ In 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. |
 
-
 ## Masks
 
 Template:
@@ -259,7 +258,6 @@ index   name            abbr	color       mapping
 102     "Brainstem"     BS      #36de72	    11
 ```
 
-
 []: <> (################)
 []: <> (Link definitions)
 []: <> (################)

From 5e906288ce6da75ceea9cea2ff5fe507fb0bdaff Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Thu, 12 Sep 2019 15:03:54 -0400
Subject: [PATCH 124/191] MAINT: Update TOC, CODEOWNERS

---
 CODEOWNERS | 7 ++++---
 mkdocs.yml | 1 +
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/CODEOWNERS b/CODEOWNERS
index ce07f9ca43..ee7729e3a7 100644
--- a/CODEOWNERS
+++ b/CODEOWNERS
@@ -13,7 +13,8 @@
 /src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md @chrisgorgo
 /src/04-modality-specific-files/03-electroencephalography.md @sappelhoff @ezemikulan
 /src/04-modality-specific-files/04-intracranial-electroencephalography.md @ezemikulan
-/src/05-derivatives/03-structural-derivatives.md @edickie @ahoopes
-/src/05-derivatives/04-functional-derivatives.md @effigies
-/src/05-derivatives/05-diffusion-derivatives.md @francopestilli @oesteban
+/src/05-derivatives/03-imaging.md @effigies
+/src/05-derivatives/04-structural-derivatives.md @edickie @ahoopes
+/src/05-derivatives/05-functional-derivatives.md @effigies
+/src/05-derivatives/06-diffusion-derivatives.md @francopestilli @oesteban
 /src/99-appendices/06-meg-file-formats.md @monkeyman192
diff --git a/mkdocs.yml b/mkdocs.yml
index 9728116ab7..88fa7df38f 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -30,6 +30,7 @@ nav:
       - Derivatives:
         - Introduction: 05-derivatives/01-introduction.md
         - Common data types: 05-derivatives/02-common-data-types.md
+        - Imaging data types: 05-derivatives/03-imaging.md
       - Longitudinal and multi-site studies: 06-longitudinal-and-multi-site-studies.md
       - Extending the BIDS specification: 07-extensions.md
       - Appendix:

From 92686705ba8b29217bb6834ebe7f1b7937c83355 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Thu, 12 Sep 2019 16:36:14 -0400
Subject: [PATCH 125/191] ENH: Add language around non-compliant derivative
 datasets and files

---
 src/02-common-principles.md           | 17 ++++++++++++-----
 src/05-derivatives/01-introduction.md | 13 +++++++++++++
 2 files changed, 25 insertions(+), 5 deletions(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index d4f9decd65..088e2a7930 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -123,7 +123,8 @@ However, in the case that these data are to be included:
     `sourcedata/sub-01/ses-pre/func/sub-01_ses-pre_task-rest_bold.dicom.tgz` or
     `sourcedata/sub-01/ses-pre/func/MyEvent.sce`.
 
-1.  A README file SHOULD be found at the root of the `sourcedata` folder.
+1.  A README file SHOULD be found at the root of the `sourcedata` folder or the
+    `derivatives` folder, or both.
     This file should describe the nature of the raw data or the derived data.
     We RECOMMEND including the PDF print-out with  the actual sequence
     parameters generated by the scanner in the `sourcedata`  folder.
@@ -146,10 +147,13 @@ my_dataset/
     ...
 ```
 
-In this example **only the `rawdata` subfolder and all subfolders of `derivatives`
-need to be BIDS compliant** datasets. This specification does not prescribe 
-anything about the contents of `sourcedata` folders in the above example - nor 
-does it prescribe the `sourcedata`, `derivatives`, or `rawdata` folder names. 
+In this example **only the `rawdata` subfolder** needs to be a BIDS-compliant
+dataset.
+The subfolders of `derivatives` MAY be BIDS-compliant derivatives datasets
+(see [Non-compliant datasets][] for further discussion).
+This specification does not prescribe anything about the contents of `sourcedata`
+folders in the above example - nor does it prescribe the `sourcedata`,
+`derivatives`, or `rawdata` folder names.
 The above example is just a convention that can be useful for organizing raw, 
 source, and derived data while maintaining BIDS compliancy of the raw data 
 folder. When using this convention it is RECOMMENDED to set the `SourceDatasets`
@@ -450,3 +454,6 @@ special cases. They should be named using all lowercase with a name that
 reflects the nature of the scan (e.g., `calibration`). Naming of files within
 the directory should follow the same scheme as above (e.g.,
 `sub-control01_calibration_Xcalibration.nii.gz`)
+
+
+[Non-compliant datasets]: 05-derivatives/01-introduction.md#non-compliant-datasets
diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 55efef53ee..a0a501079e 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -222,3 +222,16 @@ sub-01/anat/sub-01_hemi-L_space-individual_thickness.json
     distinguish brain mask files derived from T1w and T2w images; or `_desc-sm4`
     and `_desc-sm8` to distinguish between outputs generated with two different
     levels of smoothing).
+
+-   When naming files that are not yet standardized, it is RECOMMENDED to use
+    names consistent with BIDS conventions where those conventions apply.
+    For example, if a summary statistic is derived from a given task, the file
+    name SHOULD contain `_task-<label>`.
+
+## Non-compliant datasets
+
+Nothing in this specification should be interpreted to disallow the
+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.

From dbdcfbc57b7fdc1aeb77736cb53495bb98a7560a Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Tue, 17 Sep 2019 16:21:52 -0400
Subject: [PATCH 126/191] STY: Drop double newline

---
 src/02-common-principles.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index 088e2a7930..2fbf638f4b 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -455,5 +455,4 @@ reflects the nature of the scan (e.g., `calibration`). Naming of files within
 the directory should follow the same scheme as above (e.g.,
 `sub-control01_calibration_Xcalibration.nii.gz`)
 
-
 [Non-compliant datasets]: 05-derivatives/01-introduction.md#non-compliant-datasets

From 6ca059877617b674677b3a5fda891d80dfb91210 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Tue, 17 Sep 2019 16:24:32 -0400
Subject: [PATCH 127/191] STY: Fix link style

---
 src/02-common-principles.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index 2fbf638f4b..12b3b35a3d 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -150,7 +150,7 @@ my_dataset/
 In this example **only the `rawdata` subfolder** needs to be a BIDS-compliant
 dataset.
 The subfolders of `derivatives` MAY be BIDS-compliant derivatives datasets
-(see [Non-compliant datasets][] for further discussion).
+(see [Non-compliant datasets][non-compliant-datasets] for further discussion).
 This specification does not prescribe anything about the contents of `sourcedata`
 folders in the above example - nor does it prescribe the `sourcedata`,
 `derivatives`, or `rawdata` folder names.
@@ -455,4 +455,4 @@ reflects the nature of the scan (e.g., `calibration`). Naming of files within
 the directory should follow the same scheme as above (e.g.,
 `sub-control01_calibration_Xcalibration.nii.gz`)
 
-[Non-compliant datasets]: 05-derivatives/01-introduction.md#non-compliant-datasets
+[non-compliant-datasets]: 05-derivatives/01-introduction.md#non-compliant-datasets

From 70dc2628e3bc6dff81f1f4af3ce89292705bd74f Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Wed, 18 Sep 2019 10:29:25 -0400
Subject: [PATCH 128/191] Update src/05-derivatives/01-introduction.md

---
 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 55efef53ee..ece365ef8a 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -17,7 +17,7 @@ Derivatives can be stored/distributed in two ways:
     RECOMMENDED to use the format `<pipeline>-<variant>` in cases where it is
     anticipated that the same pipeline will output more than one variant (e.g.,
     `AFNI-blurring`, `AFNI-noblurring`, etc.). For the sake of consistency, the
-    subfolder name MUST be the `PipelineDescription.Name` field in
+    subfolder name SHOULD be the `PipelineDescription.Name` field in
     `data_description.json`, optionally followed by a hyphen and a suffix (see
     below).
 

From 2c5db7c2ff75698fcf9174bda2d34ce3c6835e85 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Tue, 8 Oct 2019 16:43:27 -0400
Subject: [PATCH 129/191] Update src/02-common-principles.md

---
 src/02-common-principles.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index 12b3b35a3d..047ac56082 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -147,7 +147,8 @@ my_dataset/
     ...
 ```
 
-In this example **only the `rawdata` subfolder** needs to be a BIDS-compliant
+In this example, where `sourcedata` and `derivatives` are not nested inside
+`rawdata`, **only the `rawdata` subfolder** needs to be a BIDS-compliant
 dataset.
 The subfolders of `derivatives` MAY be BIDS-compliant derivatives datasets
 (see [Non-compliant datasets][non-compliant-datasets] for further discussion).

From 4fa236fcfbe2fbbd50f0f6518d3c13481a22d7cc Mon Sep 17 00:00:00 2001
From: Cyril Pernet <cyril.pernet@ed.ac.uk>
Date: Wed, 23 Oct 2019 17:15:20 +0100
Subject: [PATCH 130/191] specify further the pipeline following #345

#345  discuss splitting a pipeline into multiple derivatives with/without nesting
---
 src/05-derivatives/01-introduction.md | 22 +++++++++++++++++-----
 1 file changed, 17 insertions(+), 5 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 4c9a1c8330..dbb5042404 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -12,22 +12,34 @@ Derivatives can be stored/distributed in two ways:
 
 1.  Under a `derivatives/` subfolder in the root of the source BIDS dataset
     folder to make a clear distinction between raw data and results of data
-    processing. Each pipeline has a dedicated directory under which it stores
-    all of its outputs. There are few restriction on the directory name; it is
-    RECOMMENDED to use the format `<pipeline>-<variant>` in cases where it is
-    anticipated that the same pipeline will output more than one variant (e.g.,
+    processing. A data processing pipeline will typically have a dedicated directory 
+    under which it stores all of its outputs. Different components of a pipeline can, 
+    however, also be stored under different subfolders. There are few restrictions on
+    the directory names; it is RECOMMENDED to use the format `<pipeline>-<variant>` in 
+    cases where it is anticipated that the same pipeline will output more than one variant (e.g.,
     `AFNI-blurring`, `AFNI-noblurring`, etc.). For the sake of consistency, the
     subfolder name SHOULD be the `PipelineDescription.Name` field in
     `data_description.json`, optionally followed by a hyphen and a suffix (see
     below).
 
-    For example:
+    Examples of single pipeline outputs:
 
     ```Plain
     <dataset>/derivatives/fmriprep-v1.4.1/sub-0001
     <dataset>/derivatives/spm/sub-0001
     <dataset>/derivatives/vbm/sub-0001
     ```
+    Examples of a split pipeline outputs:
+    ```Plain
+    <dataset>/derivatives/spm_preproc/sub-0001
+    <dataset>/derivatives/spm_stats/sub-0001
+    ```
+    or using a nested structure
+    ```Plain
+    <dataset>/derivatives/spm_preproc/sub-0001
+    <dataset>/derivatives/spm_preproc/sub-0001/spm_stats/sub-0001
+    ```    
+
 
 1.  As a standalone dataset independent of the source (raw or derived) BIDS
     dataset. This way of specifying derivatives is particularly useful when the

From e793715125791d0404f40bcc5eb1dcb94a4f6f03 Mon Sep 17 00:00:00 2001
From: Cyril Pernet <cyril.pernet@ed.ac.uk>
Date: Wed, 30 Oct 2019 07:58:01 +0000
Subject: [PATCH 131/191] Update src/05-derivatives/01-introduction.md

Co-Authored-By: Chris Markiewicz <markiewicz@stanford.edu>
---
 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 dbb5042404..e43c21e328 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -37,7 +37,7 @@ Derivatives can be stored/distributed in two ways:
     or using a nested structure
     ```Plain
     <dataset>/derivatives/spm_preproc/sub-0001
-    <dataset>/derivatives/spm_preproc/sub-0001/spm_stats/sub-0001
+    <dataset>/derivatives/spm_preproc/derivatives/spm_stats/sub-0001
     ```    
 
 

From fe17c4c0b5dfd6693e32a1d3e3b38707eefd8334 Mon Sep 17 00:00:00 2001
From: Cyril Pernet <cyril.pernet@ed.ac.uk>
Date: Wed, 30 Oct 2019 07:58:18 +0000
Subject: [PATCH 132/191] Update src/05-derivatives/01-introduction.md

Co-Authored-By: Chris Markiewicz <markiewicz@stanford.edu>
---
 src/05-derivatives/01-introduction.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index e43c21e328..ebaccd31f7 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -34,7 +34,9 @@ Derivatives can be stored/distributed in two ways:
     <dataset>/derivatives/spm_preproc/sub-0001
     <dataset>/derivatives/spm_stats/sub-0001
     ```
-    or using a nested structure
+
+    Example of a pipeline with nested derivative directories:
+
     ```Plain
     <dataset>/derivatives/spm_preproc/sub-0001
     <dataset>/derivatives/spm_preproc/derivatives/spm_stats/sub-0001

From 7b418ea401ce88694a54d0ef2e4a0cbad0dfeb9b Mon Sep 17 00:00:00 2001
From: Cyril Pernet <cyril.pernet@ed.ac.uk>
Date: Wed, 30 Oct 2019 07:58:28 +0000
Subject: [PATCH 133/191] Update src/05-derivatives/01-introduction.md

Co-Authored-By: Chris Markiewicz <markiewicz@stanford.edu>
---
 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 ebaccd31f7..a3c01037d2 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -22,7 +22,7 @@ Derivatives can be stored/distributed in two ways:
     `data_description.json`, optionally followed by a hyphen and a suffix (see
     below).
 
-    Examples of single pipeline outputs:
+    Example of derivatives with one directory per pipeline:
 
     ```Plain
     <dataset>/derivatives/fmriprep-v1.4.1/sub-0001

From 28b2b592e844d32b7d0b541a4abd90971775c35b Mon Sep 17 00:00:00 2001
From: Cyril Pernet <cyril.pernet@ed.ac.uk>
Date: Wed, 30 Oct 2019 07:58:44 +0000
Subject: [PATCH 134/191] Update src/05-derivatives/01-introduction.md

Co-Authored-By: Chris Markiewicz <markiewicz@stanford.edu>
---
 src/05-derivatives/01-introduction.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index a3c01037d2..977755b443 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -29,7 +29,9 @@ Derivatives can be stored/distributed in two ways:
     <dataset>/derivatives/spm/sub-0001
     <dataset>/derivatives/vbm/sub-0001
     ```
-    Examples of a split pipeline outputs:
+
+    Example of a pipeline with split derivative directories:
+
     ```Plain
     <dataset>/derivatives/spm_preproc/sub-0001
     <dataset>/derivatives/spm_stats/sub-0001

From c200cff39c8913c4dbe4c877650b12f16cefdf0f Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Mon, 4 Nov 2019 11:25:54 -0500
Subject: [PATCH 135/191] FIX: Links to coordinate system appendix

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

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 977755b443..ea118e4a81 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -114,11 +114,11 @@ 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 on the file format:
 
-| File format                  | Description             | Allowed `CoordinateSystem` values                                                                                                                                                                                                                     |
-| ---------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| NIfTI (`.nii` and `.nii.gz`) | Volume data             | Coordinate systems listed in [Template Based Coordinate Systems: Volume](../99-appendices/08-coordinate-systems.md#volume). If `individual` or `custom` is used then setting [`SpatialReference`](#spatialreference-key-allowed-values) is REQUIRED   |
-| GIFTI (`.gii`)               | Surface data            | Coordinate systems listed in [Template Based Coordinate Systems: Surface](../99-appendices/08-coordinate-systems.md#surface). If `individual` or `custom` is used then setting [`SpatialReference`](#spatialreference-key-allowed-values) is REQUIRED |
-| CIFTI (`.nii`)               | Volume and surface data | Coordinate systems listed in [Template Based Coordinate Systems: Hybrid (Volume/Surface) aliases](../99-appendices/08-coordinate-systems.md#hybrid-volumesurface-aliases)                                                                             |
+| File format                  | Description             | Allowed `CoordinateSystem` values                                                                                                                                                                                                                                      |
+| ---------------------------- | ----------------------- | -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| NIfTI (`.nii` and `.nii.gz`) | Volume data             | Coordinate systems listed in [Template Based Coordinate Systems](../99-appendices/08-coordinate-systems.md#template-based-coordinate-systems). If `individual` or `custom` is used then setting [`SpatialReference`](#spatialreference-key-allowed-values) is REQUIRED |
+| GIFTI (`.gii`)               | Surface data            | Coordinate systems listed in [Template Based Coordinate Systems](../99-appendices/08-coordinate-systems.md#template-based-coordinate-systems). If `individual` or `custom` is used then setting [`SpatialReference`](#spatialreference-key-allowed-values) is REQUIRED |
+| CIFTI (`.nii`)               | Volume and surface data | Coordinate systems listed in [Template Based Coordinate Systems: Hybrid (Volume/Surface) aliases](../99-appendices/08-coordinate-systems.md#hybrid-volumesurface-aliases)                                                                                              |
 
 Examples:
 

From dd626c1fa5a3ada47643b9647f7d702dd8813d02 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Thu, 5 Dec 2019 10:20:57 -0800
Subject: [PATCH 136/191] [FIX] Revise template-generated coordinate systems
 (#307)

* [FIX] Revise template-generated coordinate systems

This PR supersedes #213, and should be rebased with master after #306 is
merged.

W.r.t. master it only adds the table of _Nonstandard template
identifiers_

W.r.t. `common-derivatives`, the changes are:

  - [x] Removed the distinction between surface templates and volumetric
        templates. After all, to properly apply a surface template one
        should first spatially normalize to a particular volumetric
        template. Although it is possible to create mixed templates
        (e.g. using ``MNI152Lin`` to generate a mapping for volumetric
        coordinates and then, say, ``fsLR`` for the surface after some
        surface mapping process), this option should be discouraged.
        Anyways, this discussion does not affect how the names of BIDS
        entities should be specified, since one can always describe how
        the template coordinates are generated with the information
        described in this PR.
  - [x] Removed ``MNI152NLin6AsymConte69`` because it does not define
        any new coordinate system (see
        https://github.com/bids-standard/bids-specification/pull/207#discussion_r278911304),
  - [x] Removed ``FS305`` as it is now covered by ``fsaverage``.
  - [x] Reorganized subsections in "standard" vs "nonstandard" spaces.

* fix: added the concept of ``scanner`` as an Image-based coordinate system

- [x] Describes more clearly the situation when files do not have
``space-`` definition.
- [x] Remove the ``ReferenceIndex`` as an index does not generate a
coordinate system (the concept here is mixed up with that of  image
registration, which is just a process).
---
 src/05-derivatives/01-introduction.md      | 45 ++++++++++++++++----
 src/99-appendices/08-coordinate-systems.md | 49 ++++++++++++----------
 2 files changed, 63 insertions(+), 31 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index ea118e4a81..d96715bb9d 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -112,13 +112,14 @@ Example:
 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 on the file format:
+keyword depend are identifiers given in section [Image-Based Coordinate
+Systems](../99-appendices/08-coordinate-systems.md#image-based-coordinate-systems).
 
-| File format                  | Description             | Allowed `CoordinateSystem` values                                                                                                                                                                                                                                      |
-| ---------------------------- | ----------------------- | -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| NIfTI (`.nii` and `.nii.gz`) | Volume data             | Coordinate systems listed in [Template Based Coordinate Systems](../99-appendices/08-coordinate-systems.md#template-based-coordinate-systems). If `individual` or `custom` is used then setting [`SpatialReference`](#spatialreference-key-allowed-values) is REQUIRED |
-| GIFTI (`.gii`)               | Surface data            | Coordinate systems listed in [Template Based Coordinate Systems](../99-appendices/08-coordinate-systems.md#template-based-coordinate-systems). If `individual` or `custom` is used then setting [`SpatialReference`](#spatialreference-key-allowed-values) is REQUIRED |
-| CIFTI (`.nii`)               | Volume and surface data | Coordinate systems listed in [Template Based Coordinate Systems: Hybrid (Volume/Surface) aliases](../99-appendices/08-coordinate-systems.md#hybrid-volumesurface-aliases)                                                                                              |
+| File format                  | Description             |
+| ---------------------------- | ----------------------- |
+| NIfTI (`.nii` and `.nii.gz`) | Volume data             |
+| GIFTI (`.gii`)               | Surface data            |
+| CIFTI (`.nii`)               | Volume and surface data |
 
 Examples:
 
@@ -146,9 +147,8 @@ 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.                                                                                                                                                                                                                |
+| 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.                                                                                       |
-| ReferenceIndex   | REQUIRED when an index into a 4D (SpatialReference) file is used. Used to index into a 4D spatial-reference file.                                                                                                                                                                                                                                     |
 
 ### SpatialReference key allowed values
 
@@ -187,6 +187,35 @@ sub-01/anat/sub-01_hemi-L_space-individual_thickness.json
 }
 ```
 
+Preprocessed `bold` NIfTI file in the original coordinate space of the
+original run. Please mind that in this case `RawSources` key is REQUIRED
+(and also `desc-<label>` so that the name does not overlap with the
+original filename).
+
+```Text
+sub-01/func/sub-01_task-rest_desc-preproc_bold.nii.gz
+sub-01/func/sub-01_task-rest_desc-preproc_bold.json
+```
+
+```JSON
+{
+    "RawSources": ["/sub-01/func/sub-01_task-rest_bold.nii.gz"]
+}
+```
+
+If this file was generated with prior knowledge from additional sources
+(e.g., say the same subject's `T1w`), then the first item of `RawSources`
+should be the original `bold` file that defined the coordinate system:
+
+```JSON
+{
+    "RawSources": [
+        "/sub-01/func/sub-01_task-rest_bold.nii.gz",
+        "/sub-01/anat/sub-01_T1w.nii.gz"
+    ]
+}
+```
+
 ## Metadata conventions
 
 -   Unless specified otherwise, individual sidecar JSON files and all metadata
diff --git a/src/99-appendices/08-coordinate-systems.md b/src/99-appendices/08-coordinate-systems.md
index c243f5640a..ce4494f2c8 100644
--- a/src/99-appendices/08-coordinate-systems.md
+++ b/src/99-appendices/08-coordinate-systems.md
@@ -108,43 +108,39 @@ Restricted keywords for the `XXXCoordinateSystem` field in the
     [ACPC site](http://www.fieldtriptoolbox.org/faq/acpc/) on the FieldTrip
     toolbox wiki.
 
-## Template Based Coordinate Systems
+## Image-based Coordinate Systems
 
 The transformation of the real world geometry to an artificial frame of
-reference is described in `XXXCoordinateSystem`. Unless otherwise specified
-below, the origin is at the AC and the orientation of the axes is RAS. Unless
-specified explicitly in the sidecar file in the `XXCoordinateSystemUnits` field,
+reference is described in `ImageCoordinateSystem`.
+The origin of the coordinate system and orientation of axes MUST be defined
+by the metadata or headers of the image/surface file (e.g. the
+`x-form` matrices and codes of NIfTI) that serves as `ImageCoordinateSystemReference`.
+Unless specified explicitly in the sidecar file in the `ImageCoordinateSystemUnits` field,
 the units are assumed to be mm.
 
-### Common for Surface and Volume
-
-| Coordinate System | Description                                                                                                                                                                                                                                                           |
-| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| individual        | Participant specific anatomical space (for example derived from T1w and/or T2w images). This coordinate system requires specifying an additional, participant-specific file to be fully defined. In context of surfaces this space has been refered to as `fsnative`. |
-| custom            | Custom space defined using a group/study-specific template. This coordinate system requires specifying an additional file to be fully defined.                                                                                                                        |
-
 ### Standard template identifiers
 
 | Coordinate System                                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| FS305                                               | FreeSurfer variant of the MNI305 space                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | ICBM452AirSpace                                     | Reference space defined by the "average of 452 T1-weighted MRIs of normal young adult brains" with "linear transforms of the subjects into the atlas space using a 12-parameter affine transformation" [https://www.loni.usc.edu/research/atlases](https://www.loni.usc.edu/research/atlases)                                                                                                                                                                                                                          |
 | ICBM452Warp5Space                                   | Reference space defined by the "average of 452 T1-weighted MRIs of normal young adult brains" "based on a 5th order polynomial transformation into the atlas space" [https://www.loni.usc.edu/research/atlases](https://www.loni.usc.edu/research/atlases)                                                                                                                                                                                                                                                             |
-| IXI549Space                                         | Reference space defined by the average of the "549 (...) subjects from the IXI dataset" linearly transformed to ICBM MNI 452. Used by SPM12. [http://www.brain-development.org/](http://www.brain-development.org/)                                                                                                                                                                                                                                                                                                    |
-| fsaverage\[&#124;Sym\]                              | The `fsaverage` is a **dual template** providing both volumetric and surface coordinates references. The volumetric template corresponds to a FreeSurfer variant of `MNI305` space. The `fsaverage` atlas also defines a surface reference system (formerly described as fsaverage\[3&#124;4&#124;5&#124;6&#124;sym\]). The `fsaverageSym` is the symmetric counterpart of `fsaverage`.                                                                                                                                |
+| IXI549Space                                         | Reference space defined by the average of the "549 (...) subjects from the IXI dataset" linearly transformed to ICBM MNI 452.Used by SPM12. [http://www.brain-development.org/](http://www.brain-development.org/)                                                                                                                                                                                                                                                                                                     |
+| fsaverage\[3&#124;4&#124;5&#124;6&#124;sym\]        | DISCOURAGED, please use `fsaverage` without modifiers. Images were sampled to the FreeSurfer surface reconstructed from the subject’s T1w image, and registered to an fsaverage template                                                                                                                                                                                                                                                                                                                               |
+| fsaverage                                           | The `fsaverage` is a **dual template** providing both volumetric and surface coordinates references. The volumetric template corresponds to a FreeSurfer variant of `MNI305` space. The `fsaverage` atlas also defines a surface reference system (formerly described as fsaverage\[3&#124;4&#124;5&#124;6&#124;sym\]).                                                                                                                                                                                                |
+| fsaverageSym                                        | The `fsaverage` is a **dual template** providing both volumetric and surface coordinates references. The volumetric template corresponds to a FreeSurfer variant of `MNI305` space. The `fsaverageSym` atlas also defines a symmetric surface reference system (formerly described as `fsaveragesym`).                                                                                                                                                                                                                 |
 | fsLR                                                | The `fsLR` is a **dual template** providing both volumetric and surface coordinates references. The volumetric template corresponds to `MNI152NLin6Asym`. Surface templates are given at several sampling densities: 164k (used by HCP pipelines for 3T and 7T anatomical analysis), 59k (used by HCP pipelines for 7T MRI bold and DWI analysis), 32k (used by HCP pipelines for 3T MRI bold and DWI analysis), or 4k (used by HCP pipelines for MEG analysis) fsaverage_LR surface reconstructed from the T1w image. |
 | MNIColin27                                          | Average of 27 T1 scans of a single subject [http://www.bic.mni.mcgill.ca/ServicesAtlases/Colin27Highres](http://www.bic.mni.mcgill.ca/ServicesAtlases/Colin27Highres)                                                                                                                                                                                                                                                                                                                                                  |
 | MNI152Lin                                           | Also known as ICBM (version with linear coregistration) [http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152Lin](http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152Lin)                                                                                                                                                                                                                                                                                                                                             |
 | MNI152NLin2009\[a-c\]\[Sym&#124;Asym\]              | Also known as ICBM (non-linear coregistration with 40 iterations, released in 2009). It comes in either three different flavours each in symmetric or asymmetric version. [http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin2009](http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin2009)                                                                                                                                                                                                                 |
 | MNI152NLin6Sym                                      | Also known as symmetric ICBM 6th generation (non-linear coregistration). Used by SPM99 - SPM8. [http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin6](http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin6)                                                                                                                                                                                                                                                                                                  |
-| MNI152NLin6Asym                                     | A variation of `MNI152NLin6Sym` built by A. Janke that is released as the *MNI template* of FSL. Volumetric templates included with [HCP-Pipelines](https://github.com/Washington-University/HCPpipelines/tree/master/global/templates) correspond to this template too. See [10.1016/j.neuroimage.2012.01.024](https://doi.org/10.1016/j.neuroimage.2012.01.024).                                                                                                                                                     |
-| MNI152NLin6AsymConte69                              | Template based on MNI152NLin6Asym using Conte69 data. Built by Human Connectome Project. [https://github.com/Washington-University/HCPpipelines/tree/master/global/templates](https://github.com/Washington-University/HCPpipelines/tree/master/global/templates)                                                                                                                                                                                                                                                      |
+| MNI152NLin6ASym                                     | A variation of `MNI152NLin6Sym` built by A. Janke that is released as the *MNI template* of FSL. Volumetric templates included with [HCP-Pipelines](https://github.com/Washington-University/HCPpipelines/tree/master/global/templates) correspond to this template too. See [10.1016/j.neuroimage.2012.01.024](https://doi.org/10.1016/j.neuroimage.2012.01.024).                                                                                                                                                     |
 | MNI305                                              | Also known as avg305.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| NIHPD\[Sym&#124;Asym\]                              | Pediatric templates generated from the NIHPD sample. Available for different age groups (4.5–18.5 y.o., 4.5–8.5 y.o., 7–11 y.o., 7.5–13.5 y.o., 10–14 y.o., 13–18.5 y.o. This template also comes in either -symmetric or -asymmetric flavor. [http://www.bic.mni.mcgill.ca/ServicesAtlases/NIHPD-obj1](http://www.bic.mni.mcgill.ca/ServicesAtlases/NIHPD-obj1)                                                                                                                                                       |
+| NIHPD                                               | Pediatric templates generated from the NIHPD sample. Available for different age groups (4.5–18.5 y.o., 4.5–8.5 y.o., 7–11 y.o., 7.5–13.5 y.o., 10–14 y.o., 13–18.5 y.o. This template also comes in either -symmetric or -asymmetric flavor. [http://www.bic.mni.mcgill.ca/ServicesAtlases/NIHPD-obj1](http://www.bic.mni.mcgill.ca/ServicesAtlases/NIHPD-obj1)                                                                                                                                                       |
 | OASIS30AntsOASISAnts                                | [https://figshare.com/articles/ANTs_ANTsR_Brain_Templates/915436](https://figshare.com/articles/ANTs_ANTsR_Brain_Templates/915436)                                                                                                                                                                                                                                                                                                                                                                                     |
 | OASIS30Atropos                                      | [https://mindboggle.info/data.html](https://mindboggle.info/data.html)                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | Talairach                                           | Piecewise linear scaling of the brain is implemented as described in TT88. [http://www.talairach.org/](http://www.talairach.org/)                                                                                                                                                                                                                                                                                                                                                                                      |
 | UNCInfant                                           | Infant Brain Atlases from Neonates to 1- and 2-year-olds. [https://www.nitrc.org/projects/pediatricatlas](https://www.nitrc.org/projects/pediatricatlas)                                                                                                                                                                                                                                                                                                                                                               |
+| UNCInfant\[0&#124;1&#124;2\]V\[21&#124;22&#124;23\] | DISCOURAGED, please use `UNCInfant` without modifiers. Infant Brain Atlases from Neonates to 1- and 2-year-olds. [https://www.nitrc.org/projects/pediatricatlas](https://www.nitrc.org/projects/pediatricatlas)                                                                                                                                                                                                                                                                                                        |
 
 The following template identifiers are retained for backwards compatibility
 of BIDS implementations.
@@ -156,13 +152,20 @@ presence MUST NOT produce a validation error.
 | fsaverage\[3&#124;4&#124;5&#124;6&#124;sym\]        | fsaverage\[&#124;Sym\] |
 | UNCInfant\[0&#124;1&#124;2\]V\[21&#124;22&#124;23\] | UNCInfant              |
 
-### Hybrid (Volume/Surface) aliases
+### Nonstandard coordinate system identifiers
+
+| Coordinate System | Description                                                                                                                                                                                                                                                           |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| individual        | Participant specific anatomical space (for example derived from T1w and/or T2w images). This coordinate system requires specifying an additional, participant-specific file to be fully defined. In context of surfaces this space has been refered to as `fsnative`. |
+| study             | Custom space defined using a group/study-specific template. This coordinate system requires specifying an additional file to be fully defined.                                                                                                                        |
 
-Hybrid spaces combining surface and volume data used with CIFTI files.
+### Non-template coordinate system identifiers
 
-| Coordinate System | Description                                                                                                                                                                                                                                                                                                                                                                                                           |
-| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| HCPMNIfsLR32k     | Combination of `MNI152NLin6AsymConte69` subcortical volumetric space (with 2mm grid) and `fsLR32k` surface space resulting in 91282 data points per timepoint. Used in Human Connectom Project. [https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/91282_Greyordinates](https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/91282_Greyordinates)      |
-| HCPMNIfsLR59k     | Combination of `MNI152NLin6AsymConte69` subcortical volumetric space (with 1.6mm grid) and `fsLR59k` surface space resulting in 170494 data points per timepoint. Used in Human Connectom Project. [https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/170494_Greyordinates](https://github.com/Washington-University/HCPpipelines/tree/master/global/templates/170494_Greyordinates) |
+The `scanner` coordinate system is implicit and assumed by default if the derivative filename does not define **any** `space-<label>`.
+Please note that `space-scanner` SHOULD NOT be used, it is mentioned in this specification to make its existence explicit.
+
+| Coordinate System | Description                                                                                                                                                                                                                                                           |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| scanner           | The intrinsic coordinate system of the original image (the first entry of `RawSources`) after reconstruction and conversion to NIfTI or equivalent for the case of surfaces and dual volume/surface files.                                                            |
 
 ---

From 4550458ced7cea256c40f87307a2ac889f61945f Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Mon, 24 Feb 2020 10:10:14 -0500
Subject: [PATCH 137/191] STY: Grey -> Gray

---
 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 ff94830bb3..120063dc34 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -199,16 +199,16 @@ below, that contains common tissue classes and can be used to map segmentations
 | Integer value | Description             | Abbreviation (label) |
 | ------------- | ----------------------- | -------------------- |
 | 0             | Background              | BG                   |
-| 1             | Grey Matter             | GM                   |
+| 1             | Gray Matter             | GM                   |
 | 2             | White Matter            | WM                   |
 | 3             | Cerebrospinal Fluid     | CSF                  |
-| 4             | Grey and White Matter   | GWM                  |
+| 4             | Gray and White Matter   | GWM                  |
 | 5             | Bone                    | B                    |
 | 6             | Soft Tissue             | ST                   |
 | 7             | Non-brain               | NB                   |
 | 8             | Lesion                  | L                    |
-| 9             | Cortical Grey Matter    | CGM                  |
-| 10            | Subcortical Grey Matter | SCGM                 |
+| 9             | Cortical Gray Matter    | CGM                  |
+| 10            | Subcortical Gray Matter | SCGM                 |
 | 11            | Brainstem               | BS                   |
 | 12            | Cerebellum              | CBM                  |
 
@@ -253,7 +253,7 @@ An example, custom dseg.tsv that defines three labels:
 
 ```Text
 index   name            abbr	color       mapping
-100     "Grey Matter"	GM      #ff53bb	    1
+100     "Gray Matter"	GM      #ff53bb	    1
 101     "White Matter"	WM      #2f8bbe	    2
 102     "Brainstem"     BS      #36de72	    11
 ```

From facda86f9a12d4afc8277ae17701c5de9bb3841a Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Thu, 2 Apr 2020 16:10:32 -0400
Subject: [PATCH 138/191] Update derivatives introduction with Oscar's
 suggestions

Co-Authored-By: Oscar Esteban <code@oscaresteban.es>
---
 src/02-common-principles.md           | 4 ++--
 src/05-derivatives/01-introduction.md | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index 09248c2696..4f803801d3 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -111,8 +111,8 @@ from accidental changes by file permissions. In addition it is easy to
 distinguish partial results from the raw data and share the latter. You can read
 more about organizing derivatives [here](05-derivatives/01-introduction.md).
 
-Similar rules apply to source data which is defined as data before 
-harmonization and/or file format conversion (for example E-Prime event logs or 
+Similar rules apply to source data, which is defined as data before
+harmonization, reconstruction, and/or file format conversion (for example E-Prime event logs or
 DICOM files). This specification currently does not go into details of 
 recommending a particular naming scheme for including different types of 
 source data (raw event logs, parameter files, etc. before conversion to BIDS). 
diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index d96715bb9d..a1bbfca65a 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -130,7 +130,7 @@ sub-01/anat/sub-01_hemi-L_space-fsaverage5_thickness.shape.gii
 sub-01/anat/sub-01_hemi-R_space-fsaverage5_thickness.shape.gii
 sub-01/anat/sub-01_hemi-L_space-individual_thickness.shape.gii
 sub-01/anat/sub-01_hemi-R_space-individual_thickness.shape.gii
-sub-01/func/sub-01_task-rest_space-HCPMNIfsLR32k_bold.nii
+sub-01/func/sub-01_task-rest_space-fsLR_bold.dtseries.nii
 ```
 
 ## Common file level metadata fields

From 002f7632c23e4207d7489cd72ec1e8e08a51c6df Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Thu, 2 Apr 2020 16:15:15 -0400
Subject: [PATCH 139/191] Accept Oscar's suggestions for common data types

Co-Authored-By: Oscar Esteban <code@oscaresteban.es>
---
 src/05-derivatives/02-common-data-types.md | 13 ++++---------
 1 file changed, 4 insertions(+), 9 deletions(-)

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index 6e58e42d23..3df0c4dfe7 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -12,8 +12,10 @@ Template:
 ```
 
 Preprocessing in this context means transformations of data that do not change
-the number of dimensions of the input and are not explicitly covered by other
-data types in the specification.
+the data type of the input (as expressed by its BIDS `suffix`).
+For instance, a change in the number of dimensions is likely to disrupt the propagation
+of the input's `suffix` and generally, the outcomes of such transformation
+cannot be considered _preprocessed_ or _cleaned data_.
 Examples:
 
  -  Motion-corrected, temporally denoised, and transformed to MNI space BOLD series
@@ -49,13 +51,6 @@ pipeline1/
             sub-001_task-rest_run-1_desc-MC_bold.json
 ```
 
-```Text
-pipeline1/
-    sub-001/
-        func/
-            sub-001_task-rest_run-1_desc-fmriprep_bold.nii.gz
-            sub-001_task-rest_run-1_desc-fmriprep_bold.json
-```
 
 All REQUIRED metadata fields coming from a derivative file’s source file(s) MUST
 be propagated to the JSON description of the derivative unless the processing

From f18b77fca8e6a0df463279776b4d1a65d8ee94a6 Mon Sep 17 00:00:00 2001
From: Yaroslav Halchenko <debian@onerussian.com>
Date: Mon, 11 May 2020 12:02:00 -0400
Subject: [PATCH 140/191] BF: minor - mising _ before space following
 <source_keywords>

---
 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 120063dc34..0ec2d86a64 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -114,7 +114,7 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         func|anat|dwi/
-            <source_keywords>[space-<space>][_label-<label>]_probseg.nii.gz
+            <source_keywords>[_space-<space>][_label-<label>]_probseg.nii.gz
 ```
 
 Example:

From 1fe71b8c82d1f1376c00adc724e8ace94ca4d581 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Thu, 21 May 2020 09:32:03 -0400
Subject: [PATCH 141/191] FIX: Minor bugs

---
 src/04-modality-specific-files/08-genetic-descriptor.md | 2 +-
 src/05-derivatives/02-common-data-types.md              | 1 -
 2 files changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/04-modality-specific-files/08-genetic-descriptor.md b/src/04-modality-specific-files/08-genetic-descriptor.md
index ad24b06fb4..52dbc823a8 100644
--- a/src/04-modality-specific-files/08-genetic-descriptor.md
+++ b/src/04-modality-specific-files/08-genetic-descriptor.md
@@ -1,7 +1,7 @@
 # Genetic Descriptor
 
 Support for genetic descriptors was developed as a [BIDS Extension
-Proposal](../06-extensions.md#bids-extension-proposals).
+Proposal](../07-extensions.md#bids-extension-proposals).
 The extension was primarily developed by Cyril Pernet and Clara Moreau with
 contributions from Tom Nichols and Jessica Turner.
 
diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index 3df0c4dfe7..77c9f4034f 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -51,7 +51,6 @@ pipeline1/
             sub-001_task-rest_run-1_desc-MC_bold.json
 ```
 
-
 All REQUIRED metadata fields coming from a derivative file’s source file(s) MUST
 be propagated to the JSON description of the derivative unless the processing
 makes them invalid (e.g., if a source 4D image is averaged to create a single

From a7beb3d3b0b1338e73e9cf39be4b1788597ee92c Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Fri, 22 May 2020 08:46:55 -0700
Subject: [PATCH 142/191] [ENH] Add ``res`` and ``den`` keywords to indicate
 resolution of resampled data (#301)

* fix: force-push a rewrite addressing minimal changes

* sty: make linter happy

* [STY] Add missing table fence

* fix: force-push a rewrite addressing minimal changes

* sty: make linter happy

* Update src/05-derivatives/02-common-data-types.md

Co-Authored-By: Chris Markiewicz <effigies@gmail.com>

* Address @effigies' and @edickie's comments

* sty: fix missaligned table fence

* fix: better description for example following @edickie's comment

* More generalizable concepts (addressing @robertoostenveld's comments)

* Update src/05-derivatives/02-common-data-types.md

Co-Authored-By: Elizabeth DuPre <emd222@cornell.edu>

* Address @robertoostenveld's comment

* fix: ``res-<index>`` -> ``res-<label>`` + admonitions

* fix: cover one @effigies' suggestion

* remove unnecessary edit

* fix: example with bad formatting

* RF: Move res/den keywords to imaging derivatives

* REVERT Removal of example from Common Data Types

* Drop tip that does not match context

* STY: Satisfy linter

* enh: include @robertoostenveld's suggestion

* ENH: Add SpatialReference dictionary option and example

* STY: Drop parens

* Allow resolution/density to be a string or dictionary

* Eliminate dtseries.json example, add space-fsLR to avoid ambiguity

* Update src/05-derivatives/01-introduction.md

Co-authored-by: Oscar Esteban <code@oscaresteban.es>

Co-authored-by: Chris Markiewicz <effigies@gmail.com>
Co-authored-by: Elizabeth DuPre <emd222@cornell.edu>
Co-authored-by: Christopher J. Markiewicz <markiewicz@stanford.edu>
---
 mkdocs.yml                            |   1 +
 src/05-derivatives/01-introduction.md |  37 +++++++--
 src/05-derivatives/03-imaging.md      | 105 +++++++++++++++++++++++++-
 3 files changed, 134 insertions(+), 9 deletions(-)

diff --git a/mkdocs.yml b/mkdocs.yml
index 14ab58c11b..9cc5498b34 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -10,6 +10,7 @@ markdown_extensions:
     - toc:
         anchorlink: true
     - pymdownx.superfences
+    - admonition
 plugins:
     - search
     - branchcustomization:
diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 3da7d3af8d..4a30f16287 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 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
diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index 0ec2d86a64..5a5626a1dd 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/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
 

From e5b41c02e1a88b39768b9124e5f517ccc69b8b66 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Sun, 24 May 2020 10:56:13 -0400
Subject: [PATCH 143/191] MNT: Postpone thickness GIFTI example to structural
 derivatives

---
 src/05-derivatives/01-introduction.md | 14 --------------
 1 file changed, 14 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 4a30f16287..54cefaa2f8 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -198,20 +198,6 @@ sub-01/func/sub-01_task-rest_space-fsLR_den-91k_bold.json
 }
 ```
 
-Participant cortical thickness GIFTI file in `individual` coordinate space.
-Please mind that in this case `SpatialReference` key is REQUIRED.
-
-```Text
-sub-01/anat/sub-01_hemi-L_space-individual_thickness.shape.gii
-sub-01/anat/sub-01_hemi-L_space-individual_thickness.json
-```
-
-```JSON
-{
-    "SpatialReference": "/sub-01/anat/sub-01_hemi-L_pial.surf.gii"
-}
-```
-
 Preprocessed `bold` NIfTI file in the original coordinate space of the
 original run. Please mind that in this case `RawSources` key is REQUIRED
 (and also `desc-<label>` so that the name does not overlap with the

From ead9a84de2379b863218192f598dd93aa1287bf3 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Sun, 24 May 2020 11:01:16 -0400
Subject: [PATCH 144/191] ENH: Apply Robert's suggestions

---
 src/05-derivatives/01-introduction.md      | 7 ++++---
 src/05-derivatives/02-common-data-types.md | 9 +++------
 2 files changed, 7 insertions(+), 9 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 54cefaa2f8..551c89a957 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -71,9 +71,10 @@ As for any BIDS dataset a `dataset_description.json` file MUST be found at the
 top level of the particular pipeline:
 `<dataset>/derivatives/<pipeline_name>/dataset_description.json`
 
-In addition to raw BIDS datasets, derived BIDS datasets include the following
-required or recommended `dataset_description.json` keys (a dot in the Key name
-denotes a key in a subdictionary):
+In addition to the keys for raw BIDS datasets,
+derived BIDS datasets include the following required or recommended
+`dataset_description.json` keys
+(a dot in the Key name denotes a key in a subdictionary):
 
 | **Key name**                  | **Description**                                                                                                                                                                                                                              |
 | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index 77c9f4034f..1a13a9144b 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -22,7 +22,7 @@ Examples:
  -  Inhomogeneity corrected and skull stripped T1w files
  -  Motion-corrected DWI files
  -  Time-domain filtered EEG data
- -  Spatially filtered EEG data
+ -  MaxFilter (for example, SSS) cleaned MEG data
 
 The `space` keyword is recomended to distinguish files with different underlying
 coordinate systems or registered to different reference maps.
@@ -30,10 +30,7 @@ The `desc` (description) keyword is a general purpose field with freeform values
 which SHOULD be used to distinguish between multiple different versions of
 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.
-
-Examples:
+Examples of preprocessed data:
 
 ```Text
 pipeline1/
@@ -54,4 +51,4 @@ pipeline1/
 All REQUIRED metadata fields coming from a derivative file’s source file(s) MUST
 be propagated to the JSON description of the derivative unless the processing
 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).
+static volume, a `RepetitionTime` property would no longer be relevant).

From 9aaf323ce7511be772a8f8859eeadb4ffb96d5fb Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Sun, 24 May 2020 11:03:15 -0400
Subject: [PATCH 145/191] Update BIDSVersion in derivatives example JSON

---
 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 551c89a957..8a4e729cff 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -89,7 +89,7 @@ Example:
 ```JSON
 {
     "Name": "FMRIPREP Outputs",
-    "BIDSVersion": "TODO (depends when this PR will be merged)",
+    "BIDSVersion": "1.4.0",
     "PipelineDescription": {
         "Name": "FMRIPREP",
         "Version": "1.2.5",

From 83b2faeaa65739fac42a49e95a7fd4a81dbf7b48 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Sun, 24 May 2020 11:26:15 -0400
Subject: [PATCH 146/191] ENH: Update wording for clarity

---
 src/02-common-principles.md           |  7 ++++---
 src/05-derivatives/01-introduction.md | 10 +++++-----
 src/05-derivatives/03-imaging.md      |  4 ++--
 3 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index 55166e603c..4d7d8c5ed8 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -102,9 +102,10 @@ in the appendix.
 
 ## Source vs. raw vs. derived data
 
-BIDS originally was designed to harmonize and describe raw (unprocessed
-or minimally processed due to file format conversion) data. During analysis such
-data will be transformed and partial as well as final results will be saved.
+BIDS originally was designed to describe and apply consistent naming conventions
+to raw (unprocessed or minimally processed due to file format conversion) data.
+During analysis such data will be transformed and partial as well as final results
+will be saved.
 Derivatives of the raw data (other than products of DICOM to NIfTI conversion)
 MUST be kept separate from the raw data. This way one can protect the raw data
 from accidental changes by file permissions. In addition it is easy to
diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 8a4e729cff..c829ff3e75 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -110,11 +110,11 @@ Example:
 
 ## Coordinate systems
 
-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][coordsys].
+The spatial reference (_space_ in the following) to which a particular derivative
+is aligned 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][coordsys].
 
 | File format                  | Description             |
 | ---------------------------- | ----------------------- |
diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index 5a5626a1dd..b7c6159eb5 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -323,7 +323,7 @@ pipeline/
             sub-001_space-orig_dseg.tsv
 ```
 
-Definitions can also be specified with a top-level dseg.tsv, which propagates to
+Definitions can also be specified with a top-level `dseg.tsv`, which propagates to
 segmentations in relative subdirectories.
 
 Example:
@@ -336,7 +336,7 @@ pipeline/
             sub-001_space-orig_dseg.nii.gz
 ```
 
-These tsv lookup tables should contain the following columns:
+These TSV lookup tables contain the following columns:
 
 | Column name | Description                                                             |
 | ----------- | ----------------------------------------------------------------------- |

From 89566f1f92af1f904cc52ad2c892bf3531480dbc Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Sun, 24 May 2020 11:26:29 -0400
Subject: [PATCH 147/191] dparc -> dseg

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

diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index b7c6159eb5..79d2ec48d7 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -273,8 +273,8 @@ REQUIRED for GIFTI files. For example:
 pipeline/
     sub-001/
         anat/
-            sub-001_hemi-L_dparc.label.gii
-            sub-001_hemi-R_dparc.label.gii
+            sub-001_hemi-L_dseg.label.gii
+            sub-001_hemi-R_dseg.label.gii
 ```
 
 The REQUIRED extension for CIFTI parcellations is `.dlabel.nii`. For example:
@@ -283,8 +283,8 @@ The REQUIRED extension for CIFTI parcellations is `.dlabel.nii`. For example:
 pipeline/
     sub-001/
         anat/
-            sub-001_dparc.dlabel.nii
-            sub-001_dparc.dlabel.nii
+            sub-001_dseg.dlabel.nii
+            sub-001_dseg.dlabel.nii
 ```
 
 ### Anatomical Labels

From bb909619f94a4523d07d864f71cec14a3c865789 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Sun, 24 May 2020 11:27:19 -0400
Subject: [PATCH 148/191] STY: Drop quotes in dseg.tsv and reformat with spaces

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

diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index 79d2ec48d7..b0a6dbfca9 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -349,10 +349,10 @@ These TSV lookup tables contain the following columns:
 An example, custom dseg.tsv that defines three labels:
 
 ```Text
-index   name            abbr	color       mapping
-100     "Gray Matter"	GM      #ff53bb	    1
-101     "White Matter"	WM      #2f8bbe	    2
-102     "Brainstem"     BS      #36de72	    11
+index   name            abbr    color       mapping
+100     Gray Matter     GM      #ff53bb     1
+101     White Matter    WM      #2f8bbe     2
+102     Brainstem       BS      #36de72     11
 ```
 
 []: <> (################)

From 94f1814dd234904a5c1599e7030d28d411467384 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Sun, 24 May 2020 12:41:23 -0400
Subject: [PATCH 149/191] Update link, conform RFC2119 terms

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

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index c829ff3e75..db683f8785 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -20,7 +20,7 @@ Derivatives can be stored/distributed in two ways:
     `AFNI-blurring`, `AFNI-noblurring`, etc.). For the sake of consistency, the
     subfolder name SHOULD be the `PipelineDescription.Name` field in
     `data_description.json`, optionally followed by a hyphen and a suffix (see
-    below).
+    [Derived dataset and pipeline description]#derived-dataset-and-pipeline-description).
 
     Example of derivatives with one directory per pipeline:
 
@@ -72,17 +72,17 @@ top level of the particular pipeline:
 `<dataset>/derivatives/<pipeline_name>/dataset_description.json`
 
 In addition to the keys for raw BIDS datasets,
-derived BIDS datasets include the following required or recommended
+derived BIDS datasets include the following REQUIRED, RECOMMENDED or OPTIONAL
 `dataset_description.json` keys
 (a dot in the Key name denotes a key in a subdictionary):
 
 | **Key name**                  | **Description**                                                                                                                                                                                                                              |
 | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | 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.Version   | RECOMMENDED. 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`.                                                    |
-| 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`.                                                                        |
+| SourceDatasets                | RECOMMENDED. 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:
 
@@ -231,7 +231,7 @@ should be the original `bold` file that defined the coordinate system:
 ## Metadata conventions
 
 -   Unless specified otherwise, individual sidecar JSON files and all metadata
-    fields within are optional. However, the appropriate use of these files and
+    fields within are OPTIONAL. However, the appropriate use of these files and
     pertinent fields is very valuable and thus encouraged. Moreover, for some
     types of files, there may be one or more required metadata fields, in which
     case at least one metadata file containing that field must be located
@@ -239,8 +239,8 @@ should be the original `bold` file that defined the coordinate system:
     Principle](../02-common-principles.md#the-inheritance-principle)).
 
 -   When chaining derivative pipelines, any JSON fields that were specified as
-    mandatory in the input files should be propagated forward in the output
-    file’s JSON provided they remain valid. Non-required JSON fields can be
+    mandatory in the input files SHOULD be propagated forward in the output
+    file’s JSON provided they remain valid. Non-required JSON fields MAY be
     propagated, and are highly useful, but it is the pipeline’s responsibility
     to ensure that the values are still relevant and appropriate to the type of
     output data.

From 2841b345f960324276a17404cb2409dae7858e49 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Sun, 24 May 2020 12:41:38 -0400
Subject: [PATCH 150/191] Use relative paths

---
 src/05-derivatives/01-introduction.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index db683f8785..850b358f52 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -174,7 +174,7 @@ sub-01/func/sub-01_task-rest_space-individual_bold.json
 
 ```JSON
 {
-    "SpatialReference": "/sub-01/anat/sub-01_desc-combined_T1w.nii.gz"
+    "SpatialReference": "sub-01/anat/sub-01_desc-combined_T1w.nii.gz"
 }
 ```
 
@@ -211,7 +211,7 @@ sub-01/func/sub-01_task-rest_desc-preproc_bold.json
 
 ```JSON
 {
-    "RawSources": ["/sub-01/func/sub-01_task-rest_bold.nii.gz"]
+    "RawSources": ["sub-01/func/sub-01_task-rest_bold.nii.gz"]
 }
 ```
 
@@ -222,8 +222,8 @@ should be the original `bold` file that defined the coordinate system:
 ```JSON
 {
     "RawSources": [
-        "/sub-01/func/sub-01_task-rest_bold.nii.gz",
-        "/sub-01/anat/sub-01_T1w.nii.gz"
+        "sub-01/func/sub-01_task-rest_bold.nii.gz",
+        "sub-01/anat/sub-01_T1w.nii.gz"
     ]
 }
 ```

From 2d9923c6ad611b978187c0a59dfc113d02042e29 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Sun, 24 May 2020 13:03:39 -0400
Subject: [PATCH 151/191] Add resolution/density to masks and segmentations

---
 src/05-derivatives/03-imaging.md | 20 ++++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index b0a6dbfca9..1f679776f3 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -119,7 +119,7 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         anat|func|dwi/
-            <source_keywords>[_space-<space>][_desc-<label>]_mask.nii.gz
+            <source_keywords>[_space-<space>][_res-<label>][_den-<label>][_desc-<label>]_mask.nii.gz
 ```
 
 A binary (1 - inside, 0 - outside) mask in the space defined by `<space>`. By
@@ -132,6 +132,8 @@ JSON metadata fields:
 | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
 | RawSources   | Same as defined in [Introduction][intro], 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 |
+| 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.                    |
 
 Examples:
 
@@ -155,10 +157,12 @@ manual_masks/
 
 Common JSON metadata fields:
 
-| **Key name** | **Description**                                                                                    |
-| ------------ | -------------------------------------------------------------------------------------------------- |
-| Manual       | OPTIONAL. Boolean. Indicates if the segmenation was performed manually or via an automated process |
-| Atlas        | OPTIONAL. Which atlas (if any) was used to derive the segmentation.                                |
+| **Key name** | **Description**                                                                                                                |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| Manual       | OPTIONAL. Boolean. Indicates if the segmenation was performed manually or via an automated process                             |
+| Atlas        | OPTIONAL. Which atlas (if any) was used to derive the segmentation.                                                            |
+| 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.    |
 
 ### Discrete Segmentations
 
@@ -172,7 +176,7 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         anat|func|dwi/
-            <source_keywords>[_space-<space>]_dseg.nii.gz
+            <source_keywords>[_space-<space>][_res-<label>][_den-<label>]_dseg.nii.gz
 ```
 
 Example:
@@ -211,7 +215,7 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         func|anat|dwi/
-            <source_keywords>[_space-<space>][_label-<label>]_probseg.nii.gz
+            <source_keywords>[_space-<space>][_res-<label>][_den-<label>][_label-<label>]_probseg.nii.gz
 ```
 
 Example:
@@ -263,7 +267,7 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         anat/
-            <source_keywords>[_hemi-{L|R}][_space-<space>]_dseg.{label.gii|dlabel.nii}
+            <source_keywords>[_hemi-{L|R}][_space-<space>][_res-<label>][_den-<label>]_dseg.{label.gii|dlabel.nii}
 ```
 
 The REQUIRED extension for GIFTI parcellations is `.label.gii`. The `hemi` tag is

From 5f620fdf26fa67ddc84c49cda61ee2c9ae3db089 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Sun, 24 May 2020 13:08:54 -0400
Subject: [PATCH 152/191] STY: Typo

---
 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 850b358f52..270dc870ee 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -20,7 +20,7 @@ Derivatives can be stored/distributed in two ways:
     `AFNI-blurring`, `AFNI-noblurring`, etc.). For the sake of consistency, the
     subfolder name SHOULD be the `PipelineDescription.Name` field in
     `data_description.json`, optionally followed by a hyphen and a suffix (see
-    [Derived dataset and pipeline description]#derived-dataset-and-pipeline-description).
+    [Derived dataset and pipeline description](#derived-dataset-and-pipeline-description).
 
     Example of derivatives with one directory per pipeline:
 

From 0d4c1a03a7f45998f0ccb252b9841df183cf0265 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Mon, 25 May 2020 10:59:50 -0400
Subject: [PATCH 153/191] MNT: Drop admonition for now

---
 mkdocs.yml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/mkdocs.yml b/mkdocs.yml
index 9cc5498b34..14ab58c11b 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -10,7 +10,6 @@ markdown_extensions:
     - toc:
         anchorlink: true
     - pymdownx.superfences
-    - admonition
 plugins:
     - search
     - branchcustomization:

From debe853e83cdaa0bd13d303006fffa1f62c9881c Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Mon, 25 May 2020 14:49:11 -0400
Subject: [PATCH 154/191] Preface for individual/study templates

---
 src/99-appendices/08-coordinate-systems.md | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/src/99-appendices/08-coordinate-systems.md b/src/99-appendices/08-coordinate-systems.md
index 8dbf7d7fc1..68177f7cb3 100644
--- a/src/99-appendices/08-coordinate-systems.md
+++ b/src/99-appendices/08-coordinate-systems.md
@@ -140,12 +140,19 @@ Their use is NOT RECOMMENDED for new BIDS datasets and tooling, but their
 presence MUST NOT produce a validation error.
 
 | Coordinate System                                   | Recommended identifier |
-| -----------------------------------------------------------------------------------| ---------------------------------------------- |
+| --------------------------------------------------- | ---------------------- |
 | fsaverage\[3&#124;4&#124;5&#124;6&#124;sym\]        | fsaverage\[&#124;Sym\] |
 | UNCInfant\[0&#124;1&#124;2\]V\[21&#124;22&#124;23\] | UNCInfant              |
 
 ### Nonstandard coordinate system identifiers
 
+The following template identifiers are RECOMMENDED for individual- and study-specific reference
+spaces.
+In order for these spaces to be interpretable, `SpatialReference` metadata MUST be provided, as
+described in [Common file level metadata fields][common file level metadata fields].
+
+In the case of multiple study templates, additional names may need to be defined.
+
 | Coordinate System | Description                                                                                                                                                                                                                                                           |
 | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | individual        | Participant specific anatomical space (for example derived from T1w and/or T2w images). This coordinate system requires specifying an additional, participant-specific file to be fully defined. In context of surfaces this space has been refered to as `fsnative`. |
@@ -161,3 +168,5 @@ Please note that `space-scanner` SHOULD NOT be used, it is mentioned in this spe
 | scanner           | The intrinsic coordinate system of the original image (the first entry of `RawSources`) after reconstruction and conversion to NIfTI or equivalent for the case of surfaces and dual volume/surface files.                                                            |
 
 ---
+
+[common file level metadata fields]: ../05-derivatives/01-introduction.md#common-file-level-metadata-fields

From d95e799ae9da461b422f3f9287ae71a1890c0ba4 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Tue, 26 May 2020 16:32:13 -0400
Subject: [PATCH 155/191] Revert to pre-derivatives description of
 XXXCoordinateSystem

---
 src/99-appendices/08-coordinate-systems.md | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/src/99-appendices/08-coordinate-systems.md b/src/99-appendices/08-coordinate-systems.md
index 68177f7cb3..2d83be2a53 100644
--- a/src/99-appendices/08-coordinate-systems.md
+++ b/src/99-appendices/08-coordinate-systems.md
@@ -103,11 +103,10 @@ Restricted keywords for the `XXXCoordinateSystem` field in the
 ## Image-based Coordinate Systems
 
 The transformation of the real world geometry to an artificial frame of
-reference is described in `ImageCoordinateSystem`.
-The origin of the coordinate system and orientation of axes MUST be defined
-by the metadata or headers of the image/surface file (e.g. the
-`x-form` matrices and codes of NIfTI) that serves as `ImageCoordinateSystemReference`.
-Unless specified explicitly in the sidecar file in the `ImageCoordinateSystemUnits` field,
+reference is described in `XXXCoordinateSystem`.
+Unless otherwise specified below, the origin is at the AC and the orientation of
+the axes is RAS.
+Unless specified explicitly in the sidecar file in the `XXXCoordinateSystemUnits` field,
 the units are assumed to be mm.
 
 ### Standard template identifiers

From e0102fcd1f6c5d67d4ad99be9a93911d9a09c555 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Tue, 26 May 2020 17:05:26 -0400
Subject: [PATCH 156/191] FIX: Rename derivative directories to use
 <pipeline>-<variant>

---
 src/05-derivatives/01-introduction.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 270dc870ee..3462a60204 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -33,15 +33,15 @@ Derivatives can be stored/distributed in two ways:
     Example of a pipeline with split derivative directories:
 
     ```Plain
-    <dataset>/derivatives/spm_preproc/sub-0001
-    <dataset>/derivatives/spm_stats/sub-0001
+    <dataset>/derivatives/spm-preproc/sub-0001
+    <dataset>/derivatives/spm-stats/sub-0001
     ```
 
     Example of a pipeline with nested derivative directories:
 
     ```Plain
-    <dataset>/derivatives/spm_preproc/sub-0001
-    <dataset>/derivatives/spm_preproc/derivatives/spm_stats/sub-0001
+    <dataset>/derivatives/spm-preproc/sub-0001
+    <dataset>/derivatives/spm-preproc/derivatives/spm-stats/sub-0001
     ```
 
 

From 56c1d98a8457cf831e65ba30d7a32de0ad6303c5 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Wed, 27 May 2020 07:41:28 -0400
Subject: [PATCH 157/191] Apply suggestions from code review

Co-authored-by: Robert Smith <robert.smith@florey.edu.au>
---
 CODEOWNERS                                 | 2 +-
 src/05-derivatives/01-introduction.md      | 2 +-
 src/05-derivatives/02-common-data-types.md | 4 ++--
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/CODEOWNERS b/CODEOWNERS
index ee7729e3a7..5dbad3bf60 100644
--- a/CODEOWNERS
+++ b/CODEOWNERS
@@ -16,5 +16,5 @@
 /src/05-derivatives/03-imaging.md @effigies
 /src/05-derivatives/04-structural-derivatives.md @edickie @ahoopes
 /src/05-derivatives/05-functional-derivatives.md @effigies
-/src/05-derivatives/06-diffusion-derivatives.md @francopestilli @oesteban
+/src/05-derivatives/06-diffusion-derivatives.md @francopestilli @oesteban @Lestropie
 /src/99-appendices/06-meg-file-formats.md @monkeyman192
diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 3462a60204..b34191dba2 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -288,7 +288,7 @@ should be the original `bold` file that defined the coordinate system:
 ## Non-compliant datasets
 
 Nothing in this specification should be interpreted to disallow the
-storage/distribution non-compliant derivatives of BIDS datasets.
+storage/distribution of 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.
diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index 1a13a9144b..b8593cebae 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -44,8 +44,8 @@ pipeline1/
 pipeline1/
     sub-001/
         func/
-            sub-001_task-rest_run-1_desc-MC_bold.nii.gz
-            sub-001_task-rest_run-1_desc-MC_bold.json
+            sub-001_task-rest_run-1_desc-preproc_bold.nii.gz
+            sub-001_task-rest_run-1_desc-preproc_bold.json
 ```
 
 All REQUIRED metadata fields coming from a derivative file’s source file(s) MUST

From b21a9b8adce4513af1ab49bd5d9dea3fda1e7083 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Wed, 27 May 2020 14:11:27 -0400
Subject: [PATCH 158/191] FIX: Clarify recommendation of desc to when no other
 entity suits

---
 src/05-derivatives/01-introduction.md | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index b34191dba2..3e2b62bd02 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -273,12 +273,13 @@ should be the original `bold` file that defined the coordinate system:
     create and use the sidecar JSON files to detail the specifics of individual
     files.
 
--   When necessary to distinguish two files, the `_desc-<label>` keyword-value
-    should be used. This includes the cases of needing to distinguish both
-    differing inputs and differing outputs (e.g., `_desc-T1w` and `_desc-T2w` to
-    distinguish brain mask files derived from T1w and T2w images; or `_desc-sm4`
-    and `_desc-sm8` to distinguish between outputs generated with two different
-    levels of smoothing).
+-   When necessary to distinguish two files that do not otherwise have a
+    distinguishing entity, the `_desc-<label>` keyword-value SHOULD be used.
+    This includes the cases of needing to distinguish both differing inputs and
+    differing outputs (for example, `_desc-T1w` and `_desc-T2w` to distinguish
+    brain mask files derived from T1w and T2w images;
+    or `_desc-sm4` and `_desc-sm8` to distinguish between outputs generated with
+    two different levels of smoothing).
 
 -   When naming files that are not yet standardized, it is RECOMMENDED to use
     names consistent with BIDS conventions where those conventions apply.

From 82be287fe9c12f6798fe0e178797a07d44283c87 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Wed, 27 May 2020 15:51:51 -0400
Subject: [PATCH 159/191] Update examples with T1w, events, EDF (EEG)

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

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index b8593cebae..d6097fb69c 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -35,17 +35,22 @@ Examples of preprocessed data:
 ```Text
 pipeline1/
     sub-001/
+        anat/
+            sub-001_space-MNI305_T1w.nii.gz
+            sub-001_space-MNI305_T1w.json
         func/
-            sub-001_task-rest_run-1_space-MNI305_bold.nii.gz
-            sub-001_task-rest_run-1_space-MNI305_bold.json
+            sub-001_task-rest_run-1_space-MNI305_desc-preproc_bold.nii.gz
+            sub-001_task-rest_run-1_space-MNI305_desc-preproc_bold.json
 ```
 
 ```Text
-pipeline1/
+pipeline2/
     sub-001/
-        func/
-            sub-001_task-rest_run-1_desc-preproc_bold.nii.gz
-            sub-001_task-rest_run-1_desc-preproc_bold.json
+        eeg/
+            sub-001_task-listening_run-1_desc-autoannotation_events.tsv
+            sub-001_task-listening_run-1_desc-autoannotation_events.json
+            sub-001_task-listening_run-1_desc-filtered_eeg.edf
+            sub-001_task-listening_run-1_desc-filtered_eeg.json
 ```
 
 All REQUIRED metadata fields coming from a derivative file’s source file(s) MUST

From 0e2fcd20ae83f83fa31bff4966034b36b397bc34 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Wed, 27 May 2020 16:31:54 -0400
Subject: [PATCH 160/191] ENH: Drop "dictionary" for JSON "object"

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

diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index 1f679776f3..c608ed8b5a 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` 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.    |
+| **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 [object][] mapping labels to strings. Specifies the interpretation of the resolution keyword. |
+| Density       | REQUIRED if `den` is present. String, or [object][] mapping labels 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:
@@ -132,8 +132,8 @@ JSON metadata fields:
 | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
 | RawSources   | Same as defined in [Introduction][intro], 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 |
-| 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.                    |
+| Resolution   | REQUIRED if `res` is present. String, or [object][] mapping labels to strings. Specifies the interpretation of the resolution keyword.         |
+| Density      | REQUIRED if `den` is present. String, or [object][] mapping labels to strings. Specifies the interpretation of the density keyword.            |
 
 Examples:
 
@@ -157,12 +157,12 @@ manual_masks/
 
 Common JSON metadata fields:
 
-| **Key name** | **Description**                                                                                                                |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------ |
-| Manual       | OPTIONAL. Boolean. Indicates if the segmenation was performed manually or via an automated process                             |
-| Atlas        | OPTIONAL. Which atlas (if any) was used to derive the segmentation.                                                            |
-| 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.    |
+| **Key name** | **Description**                                                                                                                        |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
+| Manual       | OPTIONAL. Boolean. Indicates if the segmenation was performed manually or via an automated process                                     |
+| Atlas        | OPTIONAL. Which atlas (if any) was used to derive the segmentation.                                                                    |
+| Resolution   | REQUIRED if `res` is present. String, or [object][] mapping labels to strings. Specifies the interpretation of the resolution keyword. |
+| Density      | REQUIRED if `den` is present. String, or [object][] mapping labels to strings. Specifies the interpretation of the density keyword.    |
 
 ### Discrete Segmentations
 
@@ -293,7 +293,7 @@ pipeline/
 
 ### Anatomical Labels
 
-BIDS supplies a standard, generic label-index dictionary, defined in the table
+BIDS supplies a standard, generic label-index mapping, defined in the table
 below, that contains common tissue classes and can be used to map segmentations
 (and parcellations) between lookup tables.
 
@@ -365,3 +365,4 @@ index   name            abbr    color       mapping
 
 [intro]: 01-introduction.md
 [common_preproc]: 02-common-data-types.md#preprocessed-or-cleaned-data
+[object]: https://www.json.org/json-en.html

From 9efc02253a003c72f0e572510687597405e728d0 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Fri, 29 May 2020 17:17:35 -0400
Subject: [PATCH 161/191] Rename PipelineDescription to GeneratedBy, rework
 table and examples, add description field

---
 src/05-derivatives/01-introduction.md | 74 +++++++++++++++++----------
 1 file changed, 46 insertions(+), 28 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 3e2b62bd02..1f6198c6a2 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -18,7 +18,7 @@ Derivatives can be stored/distributed in two ways:
     the directory names; it is RECOMMENDED to use the format `<pipeline>-<variant>` in
     cases where it is anticipated that the same pipeline will output more than one variant (e.g.,
     `AFNI-blurring`, `AFNI-noblurring`, etc.). For the sake of consistency, the
-    subfolder name SHOULD be the `PipelineDescription.Name` field in
+    subfolder name SHOULD be the `GeneratedBy.Name` field in
     `data_description.json`, optionally followed by a hyphen and a suffix (see
     [Derived dataset and pipeline description](#derived-dataset-and-pipeline-description).
 
@@ -72,39 +72,57 @@ top level of the particular pipeline:
 `<dataset>/derivatives/<pipeline_name>/dataset_description.json`
 
 In addition to the keys for raw BIDS datasets,
-derived BIDS datasets include the following REQUIRED, RECOMMENDED or OPTIONAL
-`dataset_description.json` keys
-(a dot in the Key name denotes a key in a subdictionary):
-
-| **Key name**                  | **Description**                                                                                                                                                                                                                              |
-| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 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   | RECOMMENDED. 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`.                                                    |
-| SourceDatasets                | RECOMMENDED. A list of objects specifying the locations and relevant attributes of all source datasets. Valid fields in each object include `URL`, `DOI`, and `Version`.                                                                     |
+derived BIDS datasets include the following REQUIRED and RECOMMENDED
+`dataset_description.json` keys:
+
+| **Key name**          | **Description**                                                                                                                                                          |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| GeneratedBy           | REQUIRED. List of JSON objects with at least one element.                                                                                                                |
+| SourceDatasets        | RECOMMENDED. A list of objects specifying the locations and relevant attributes of all source datasets. Valid fields in each object include `URL`, `DOI`, and `Version`. |
+
+Each object in the `GeneratedBy` list includes the following REQUIRED, RECOMMENDED
+and OPTIONAL keys:
+
+| **Key name** | **Description**                                                                                                                                                                                              |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Name         | REQUIRED. Name of the pipeline or process that generated the outputs. Use `"Manual"` to indicate the derivatives were generated by hand, or adjusted manually after an initial run of an automated pipeline. |
+| Version      | RECOMMENDED. Version of the pipeline.                                                                                                                                                                        |
+| Description  | OPTIONAL. Plain-text description of the pipeline or process that generated the outputs. RECOMMENDED if `Name` is `"Manual"`.                                                                                 |
+| CodeURL      | OPTIONAL. URL where the code used to generate the derivatives may be found.                                                                                                                                  |
+| 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`.                    |
+
+If a derived dataset is stored as a subfolder of the raw dataset, then the `Name` field
+of the first `GeneratedBy` object MUST be a substring of the derived dataset folder name.
+That is, in a directory `<dataset>/derivatives/<pipeline>[-<variant>]/`, the first
+`GeneratedBy` object should have a `Name` of `<pipeline>`.
 
 Example:
 
 ```JSON
 {
-    "Name": "FMRIPREP Outputs",
-    "BIDSVersion": "1.4.0",
-    "PipelineDescription": {
-        "Name": "FMRIPREP",
-        "Version": "1.2.5",
-        "Container": {
-            "Type": "docker",
-            "Tag": "poldracklab/fmriprep:1.2.5"
-            }
-        },
-    "SourceDatasets": [
-        {
-            "DOI": "10.18112/openneuro.ds000114.v1.0.1",
-            "URL": "https://openneuro.org/datasets/ds000114/versions/1.0.1",
-            "Version": "1.0.1"
+  "Name": "FMRIPREP Outputs",
+  "BIDSVersion": "1.4.0",
+  "GeneratedBy": [
+    {
+      "Name": "FMRIPREP",
+      "Version": "1.2.5",
+      "Container": {
+        "Type": "docker",
+        "Tag": "poldracklab/fmriprep:1.2.5"
         }
-    ]
+    },
+    {
+      "Name": "Manual",
+      "Description": "Re-added RepetitionTime metadata to bold.json files"
+    }
+  ],
+  "SourceDatasets": [
+    {
+      "DOI": "10.18112/openneuro.ds000114.v1.0.1",
+      "URL": "https://openneuro.org/datasets/ds000114/versions/1.0.1",
+      "Version": "1.0.1"
+    }
+  ]
 }
 ```
 

From fa5808ea5ac064342a651bb27bc38a26d909b1c9 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Fri, 29 May 2020 17:41:04 -0400
Subject: [PATCH 162/191] FIX: More dictionary -> object

---
 src/05-derivatives/01-introduction.md | 19 ++++++++++++-------
 1 file changed, 12 insertions(+), 7 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 1f6198c6a2..78a91370e7 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -75,10 +75,10 @@ In addition to the keys for raw BIDS datasets,
 derived BIDS datasets include the following REQUIRED and RECOMMENDED
 `dataset_description.json` keys:
 
-| **Key name**          | **Description**                                                                                                                                                          |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| GeneratedBy           | REQUIRED. List of JSON objects with at least one element.                                                                                                                |
-| SourceDatasets        | RECOMMENDED. A list of objects specifying the locations and relevant attributes of all source datasets. Valid fields in each object include `URL`, `DOI`, and `Version`. |
+| **Key name**   | **Description**                                                                                                                                                                    |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| GeneratedBy    | REQUIRED. List of [objects][object] with at least one element.                                                                                                                     |
+| SourceDatasets | RECOMMENDED. A list of [objects][object] specifying the locations and relevant attributes of all source datasets. Valid fields in each object include `URL`, `DOI`, and `Version`. |
 
 Each object in the `GeneratedBy` list includes the following REQUIRED, RECOMMENDED
 and OPTIONAL keys:
@@ -89,7 +89,7 @@ and OPTIONAL keys:
 | Version      | RECOMMENDED. Version of the pipeline.                                                                                                                                                                        |
 | Description  | OPTIONAL. Plain-text description of the pipeline or process that generated the outputs. RECOMMENDED if `Name` is `"Manual"`.                                                                                 |
 | CodeURL      | OPTIONAL. URL where the code used to generate the derivatives may be found.                                                                                                                                  |
-| 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`.                    |
+| Container    | OPTIONAL. [Object][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`.          |
 
 If a derived dataset is stored as a subfolder of the raw dataset, then the `Name` field
 of the first `GeneratedBy` object MUST be a substring of the derived dataset folder name.
@@ -167,7 +167,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 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 | 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 JSON object MUST be used.                      |
 
 ### SpatialReference key allowed values
 
@@ -176,7 +176,7 @@ share the following (non-required) ones:
 | `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.
+In the case of images with multiple references, an [object][] 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.
 
@@ -312,4 +312,9 @@ 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.
 
+[]: <> (################)
+[]: <> (Link definitions)
+[]: <> (################)
+
 [coordsys]: ../99-appendices/08-coordinate-systems.md#image-based-coordinate-systems
+[object]: https://www.json.org/json-en.html

From 8a6821ced380e3a9358479bd4ba315ee1f07bfa8 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Fri, 29 May 2020 17:41:23 -0400
Subject: [PATCH 163/191] Do not abbreviate abbreviation

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

diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index c608ed8b5a..d7b15f99f2 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -342,21 +342,21 @@ pipeline/
 
 These TSV lookup tables contain the following columns:
 
-| Column name | Description                                                             |
-| ----------- | ----------------------------------------------------------------------- |
-| index       | REQUIRED. The label integer index                                       |
-| name        | REQUIRED. The unique label name                                         |
-| abbr        | OPTIONAL. The unique label abbreviation                                 |
-| mapping     | OPTIONAL. Corresponding integer label in the standard BIDS label lookup |
-| color       | OPTIONAL. Hexadecimal. Label color for visualization                    |
+| Column name  | Description                                                             |
+| ------------ | ----------------------------------------------------------------------- |
+| index        | REQUIRED. The label integer index                                       |
+| name         | REQUIRED. The unique label name                                         |
+| abbreviation | OPTIONAL. The unique label abbreviation                                 |
+| mapping      | OPTIONAL. Corresponding integer label in the standard BIDS label lookup |
+| color        | OPTIONAL. Hexadecimal. Label color for visualization                    |
 
 An example, custom dseg.tsv that defines three labels:
 
 ```Text
-index   name            abbr    color       mapping
-100     Gray Matter     GM      #ff53bb     1
-101     White Matter    WM      #2f8bbe     2
-102     Brainstem       BS      #36de72     11
+index   name            abbreviation    color       mapping
+100     Gray Matter     GM              #ff53bb     1
+101     White Matter    WM              #2f8bbe     2
+102     Brainstem       BS              #36de72     11
 ```
 
 []: <> (################)

From 6a91d348ac248eaae404f496a760c1a04790aaff Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Fri, 29 May 2020 17:46:21 -0400
Subject: [PATCH 164/191] Rename: keyword -> entity

---
 src/05-derivatives/01-introduction.md      |  9 +++++----
 src/05-derivatives/02-common-data-types.md |  2 +-
 src/05-derivatives/03-imaging.md           | 14 +++++++-------
 3 files changed, 13 insertions(+), 12 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 78a91370e7..9dfc1c2722 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -274,14 +274,14 @@ should be the original `bold` file that defined the coordinate system:
     copy of that raw file.
 
 -   Each Derivatives filename MUST be of the form:
-    `<source_keywords>[_keyword-<value>]_<suffix>.<ext>`
+    `<source_entities>[_keyword-<value>]_<suffix>.<ext>`
     (where `<value>` could either be an `<index>` or a `<label>` depending on
-    the keyword)
+    the keyword; see [Definitions][definitions])
 
 -   When the derivatives chain involves outputs derived from a single raw input,
-    `source_keywords` MUST be the entire source filename, with the omission of
+    `source_entities` MUST be the entire source filename, with the omission of
     the source suffix and extension. One exception to this rule is filename
-    keywords that are no longer relevant. Depending on the nature of the
+    entities that are no longer relevant. Depending on the nature of the
     derivative file, the suffix can either be the same as the source file if
     that suffix is still appropriate, or a new appropriate value selected from
     the controlled list.
@@ -316,5 +316,6 @@ datasets and non-compliant derivatives.
 []: <> (Link definitions)
 []: <> (################)
 
+[definitions]: ../02-common-principles.md#defintions
 [coordsys]: ../99-appendices/08-coordinate-systems.md#image-based-coordinate-systems
 [object]: https://www.json.org/json-en.html
diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index d6097fb69c..d9d89a660a 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>][_desc-<label>]_<suffix>.<ext>
+            <source_entities>[_space-<space>][_desc-<label>]_<suffix>.<ext>
 ```
 
 Preprocessing in this context means transformations of data that do not change
diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index d7b15f99f2..f9f8d98501 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -11,7 +11,7 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         <datatype>/
-            <source_keywords>[_space-<space>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<ext>
+            <source_entities>[_space-<space>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<ext>
 ```
 
 Volumetric preprocessing does not modify the number of dimensions, and so
@@ -26,7 +26,7 @@ or surface sampling density being the only difference between them, then the
 *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.
+and `den` entities simultaneously.
 
 Examples:
 
@@ -82,7 +82,7 @@ And one corresponding to `res-hi`
 ```
 
 Example of CIFTI-2 files (a format that combines regularly sampled data
-and non-parametric surfaces) having both `res` and `den` keywords:
+and non-parametric surfaces) having both `res` and `den` entities:
 
 ```Text
 pipeline1/
@@ -119,7 +119,7 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         anat|func|dwi/
-            <source_keywords>[_space-<space>][_res-<label>][_den-<label>][_desc-<label>]_mask.nii.gz
+            <source_entities>[_space-<space>][_res-<label>][_den-<label>][_desc-<label>]_mask.nii.gz
 ```
 
 A binary (1 - inside, 0 - outside) mask in the space defined by `<space>`. By
@@ -176,7 +176,7 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         anat|func|dwi/
-            <source_keywords>[_space-<space>][_res-<label>][_den-<label>]_dseg.nii.gz
+            <source_entities>[_space-<space>][_res-<label>][_den-<label>]_dseg.nii.gz
 ```
 
 Example:
@@ -215,7 +215,7 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         func|anat|dwi/
-            <source_keywords>[_space-<space>][_res-<label>][_den-<label>][_label-<label>]_probseg.nii.gz
+            <source_entities>[_space-<space>][_res-<label>][_den-<label>][_label-<label>]_probseg.nii.gz
 ```
 
 Example:
@@ -267,7 +267,7 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         anat/
-            <source_keywords>[_hemi-{L|R}][_space-<space>][_res-<label>][_den-<label>]_dseg.{label.gii|dlabel.nii}
+            <source_entities>[_hemi-{L|R}][_space-<space>][_res-<label>][_den-<label>]_dseg.{label.gii|dlabel.nii}
 ```
 
 The REQUIRED extension for GIFTI parcellations is `.label.gii`. The `hemi` tag is

From 80cc32fe6450dfa39b8277eca7cfa88c2b30da8d Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Fri, 29 May 2020 18:57:47 -0400
Subject: [PATCH 165/191] Rewrite Sources description to clarify the A/B/C and
 X/Y/Z examples

---
 src/05-derivatives/01-introduction.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 9dfc1c2722..19acea30da 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -162,12 +162,12 @@ JSON file is also REQUIRED.
 Each derivative type defines their own set of fields, but all of them
 share the following (non-required) ones:
 
-| **Key name**     | **Description**                                                                                                                                                                                                                                                                                                                                       |
-| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 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. 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 JSON object MUST be used.                      |
+| **Key name**     | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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, if a derivative A is used in the creation of another derivative B, which is in turn used to generate C in a chain of A->B->C, C should only list B in `Sources`, and B should only list A in `Sources`. However, in case both X and Y are directly used in the creation of Z, then Z should list X and Y in `Sources`, regardless of whether X was used to generate Y. |
+| 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. 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 JSON object MUST be used.                                                                                                                                                                                           |
 
 ### SpatialReference key allowed values
 

From ddcec7a4a5345dd86314b8f4267b0f83aebcfcc3 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Fri, 29 May 2020 20:38:30 -0400
Subject: [PATCH 166/191] More cleanup

---
 src/05-derivatives/01-introduction.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 19acea30da..51bea6476b 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -129,9 +129,9 @@ Example:
 ## Coordinate systems
 
 The spatial reference (_space_ in the following) to which a particular derivative
-is aligned SHOULD be denoted using a filename keyword `space` whenever such keyword
+is aligned SHOULD be denoted using the entity `space` whenever the entity
 is present in the filename template of a given derivative type.
-The allowed values for this keyword depend are identifiers given in section
+The allowed values for this entity depend are identifiers given in section
 [Image-Based Coordinate Systems][coordsys].
 
 | File format                  | Description             |
@@ -316,6 +316,6 @@ datasets and non-compliant derivatives.
 []: <> (Link definitions)
 []: <> (################)
 
-[definitions]: ../02-common-principles.md#defintions
+[definitions]: ../02-common-principles.md#definitions
 [coordsys]: ../99-appendices/08-coordinate-systems.md#image-based-coordinate-systems
 [object]: https://www.json.org/json-en.html

From 7ef9a9d037265642c18e026d7214460e8d863f78 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Sat, 30 May 2020 17:23:23 -0400
Subject: [PATCH 167/191] Update src/05-derivatives/03-imaging.md

Co-authored-by: Satrajit Ghosh <satrajit.ghosh@gmail.com>
---
 src/05-derivatives/03-imaging.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index f9f8d98501..c95679df32 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -291,10 +291,10 @@ pipeline/
             sub-001_dseg.dlabel.nii
 ```
 
-### Anatomical Labels
+### Common Image-derived Labels
 
 BIDS supplies a standard, generic label-index mapping, defined in the table
-below, that contains common tissue classes and can be used to map segmentations
+below, that contains common image-derived segmentations and can be used to map segmentations
 (and parcellations) between lookup tables.
 
 | Integer value | Description             | Abbreviation (label) |

From 55d54ea527630282ccd6a55a89d23b161c0f3b51 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Sat, 30 May 2020 13:25:48 -0400
Subject: [PATCH 168/191] Reorganize derivatives

---
 src/02-common-principles.md                |  95 +++++++-
 src/03-modality-agnostic-files.md          |  61 +++++
 src/05-derivatives/01-introduction.md      | 262 +--------------------
 src/05-derivatives/02-common-data-types.md | 133 ++++++++++-
 4 files changed, 290 insertions(+), 261 deletions(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index ad00431d16..1be949892f 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -170,7 +170,7 @@ In this example, where `sourcedata` and `derivatives` are not nested inside
 `rawdata`, **only the `rawdata` subfolder** needs to be a BIDS-compliant
 dataset.
 The subfolders of `derivatives` MAY be BIDS-compliant derivatives datasets
-(see [Non-compliant datasets][non-compliant-datasets] for further discussion).
+(see [Non-compliant derivatives][#non-compliant-derivatives] for further discussion).
 This specification does not prescribe anything about the contents of `sourcedata`
 folders in the above example - nor does it prescribe the `sourcedata`,
 `derivatives`, or `rawdata` folder names.
@@ -185,9 +185,100 @@ field in `dataset_description.json` of each subfolder of `derivatives` to:
 }
 ```
 
+### Storage of derived datasets
+
+Derivatives can be stored/distributed in two ways:
+
+1.  Under a `derivatives/` subfolder in the root of the source BIDS dataset
+    folder to make a clear distinction between raw data and results of data
+    processing. A data processing pipeline will typically have a dedicated directory
+    under which it stores all of its outputs. Different components of a pipeline can,
+    however, also be stored under different subfolders. There are few restrictions on
+    the directory names; it is RECOMMENDED to use the format `<pipeline>-<variant>` in
+    cases where it is anticipated that the same pipeline will output more than one variant (e.g.,
+    `AFNI-blurring`, `AFNI-noblurring`, etc.). For the sake of consistency, the
+    subfolder name SHOULD be the `GeneratedBy.Name` field in
+    `data_description.json`, optionally followed by a hyphen and a suffix (see
+    [Derived dataset and pipeline description](#derived-dataset-and-pipeline-description).
+
+    Example of derivatives with one directory per pipeline:
+
+    ```Plain
+    <dataset>/derivatives/fmriprep-v1.4.1/sub-0001
+    <dataset>/derivatives/spm/sub-0001
+    <dataset>/derivatives/vbm/sub-0001
+    ```
+
+    Example of a pipeline with split derivative directories:
+
+    ```Plain
+    <dataset>/derivatives/spm-preproc/sub-0001
+    <dataset>/derivatives/spm-stats/sub-0001
+    ```
+
+    Example of a pipeline with nested derivative directories:
+
+    ```Plain
+    <dataset>/derivatives/spm-preproc/sub-0001
+    <dataset>/derivatives/spm-preproc/derivatives/spm-stats/sub-0001
+    ```
+
+
+1.  As a standalone dataset independent of the source (raw or derived) BIDS
+    dataset.
+    This way of specifying derivatives is particularly useful when the source
+    dataset is provided with read-only access, for publishing derivatives as
+    independent bodies of work, or for describing derivatives that were created
+    from more than one source dataset.
+    The `sourcedata/` subdirectory MAY be used to include the source dataset(s)
+    that were used to generate the derivatives.
+    Likewise, any code used to generate the derivatives from the source data
+    MAY be included in the `code/` subdirectory.
+
+    Example of a derivative dataset including the raw dataset as source:
+
+    ```Plain
+    my_processed_data/
+      code/
+        processing_pipeline-1.0.0.img
+        hpc_submitter.sh
+        ...
+      sourcedata/
+        dataset_description.json
+        participants.tsv
+        sub-01/
+        sub-02/
+        ...
+      dataset_description.json
+      sub-01/
+      sub-02/
+      ...
+    ```
+
+Throughout this specification, if a section applies particularly to derivatives,
+then Case 1 will be assumed for clarity in templates and examples, but removing
+`/derivatives/<pipeline>` from the template name will provide the equivalent for
+Case 2.
+In both cases, every derivatives dataset is considered a BIDS dataset and must
+include a `dataset_description.json` file at the root level (see
+[Dataset description](03-modality-agnostic-files.md#dataset-description).
+Consequently, files should be organized to comply with BIDS to the full extent
+possible (that is, unless explicitly contradicted for derivatives).
+Any subject-specific derivatives should be housed within each subject’s directory;
+if session-specific derivatives are generated, they should be deposited under a
+session subdirectory within the corresponding subject directory; and so on.
+
 See [Derived dataset and pipeline description](05-derivatives/01-introduction.md#derived-dataset-and-pipeline-description)
 for more information.
 
+### Non-compliant deriatives
+
+Nothing in this specification should be interpreted to disallow the
+storage/distribution of 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.
+
 ## The Inheritance Principle
 
 Any metadata file (`.json`, `.bvec`, `.tsv`, etc.) may be defined at any
@@ -520,5 +611,3 @@ meaning of file names and setting requirements on their contents or metadata.
 Validation and parsing tools MAY treat the presence of non-standard files and
 directories as an error, so consult the details of these tools for mechanisms
 to suppress warnings or provide interpretations of your file names.
-
-[non-compliant-datasets]: 05-derivatives/01-introduction.md#non-compliant-datasets
diff --git a/src/03-modality-agnostic-files.md b/src/03-modality-agnostic-files.md
index 69afd71ea2..8c5e82f5f8 100644
--- a/src/03-modality-agnostic-files.md
+++ b/src/03-modality-agnostic-files.md
@@ -54,6 +54,67 @@ Example:
 }
 ```
 
+#### Derived dataset and pipeline description
+
+As for any BIDS dataset a `dataset_description.json` file MUST be found at the
+top level of the a derived dataset:
+`<dataset>/derivatives/<pipeline_name>/dataset_description.json`
+
+In addition to the keys for raw BIDS datasets,
+derived BIDS datasets include the following REQUIRED and RECOMMENDED
+`dataset_description.json` keys:
+
+| **Key name**   | **Description**                                                                                                                                                                    |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| GeneratedBy    | REQUIRED. List of [objects][object] with at least one element.                                                                                                                     |
+| SourceDatasets | RECOMMENDED. A list of [objects][object] specifying the locations and relevant attributes of all source datasets. Valid fields in each object include `URL`, `DOI`, and `Version`. |
+
+Each object in the `GeneratedBy` list includes the following REQUIRED, RECOMMENDED
+and OPTIONAL keys:
+
+| **Key name** | **Description**                                                                                                                                                                                              |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Name         | REQUIRED. Name of the pipeline or process that generated the outputs. Use `"Manual"` to indicate the derivatives were generated by hand, or adjusted manually after an initial run of an automated pipeline. |
+| Version      | RECOMMENDED. Version of the pipeline.                                                                                                                                                                        |
+| Description  | OPTIONAL. Plain-text description of the pipeline or process that generated the outputs. RECOMMENDED if `Name` is `"Manual"`.                                                                                 |
+| CodeURL      | OPTIONAL. URL where the code used to generate the derivatives may be found.                                                                                                                                  |
+| Container    | OPTIONAL. [Object][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`.          |
+
+Example:
+
+```JSON
+{
+  "Name": "FMRIPREP Outputs",
+  "BIDSVersion": "1.4.0",
+  "GeneratedBy": [
+    {
+      "Name": "FMRIPREP",
+      "Version": "1.2.5",
+      "Container": {
+        "Type": "docker",
+        "Tag": "poldracklab/fmriprep:1.2.5"
+        }
+    },
+    {
+      "Name": "Manual",
+      "Description": "Re-added RepetitionTime metadata to bold.json files"
+    }
+  ],
+  "SourceDatasets": [
+    {
+      "DOI": "10.18112/openneuro.ds000114.v1.0.1",
+      "URL": "https://openneuro.org/datasets/ds000114/versions/1.0.1",
+      "Version": "1.0.1"
+    }
+  ]
+}
+```
+
+If a derived dataset is stored as a subfolder of the raw dataset, then the `Name` field
+of the first `GeneratedBy` object MUST be a substring of the derived dataset folder name.
+That is, in a directory `<dataset>/derivatives/<pipeline>[-<variant>]/`, the first
+`GeneratedBy` object should have a `Name` of `<pipeline>`.
+
 ### `README`
 
 In addition a free form text file (`README`) describing the dataset in more
diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 51bea6476b..becf2e33ac 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -1,250 +1,15 @@
-# Goals and scope
+# BIDS Derivatives
 
 Derivatives are outputs of common processing pipelines, capturing data and
 meta-data sufficient for a researcher to understand and (critically) reuse those
-outputs in subsequent processing. Standardizing derivatives is motivated by use
-cases where formalized machine-readable access to processed data enables higher
-level processing.
+outputs in subsequent processing.
+Standardizing derivatives is motivated by use cases where formalized
+machine-readable access to processed data enables higher level processing.
 
-## Storage of derived datasets
-
-Derivatives can be stored/distributed in two ways:
-
-1.  Under a `derivatives/` subfolder in the root of the source BIDS dataset
-    folder to make a clear distinction between raw data and results of data
-    processing. A data processing pipeline will typically have a dedicated directory
-    under which it stores all of its outputs. Different components of a pipeline can,
-    however, also be stored under different subfolders. There are few restrictions on
-    the directory names; it is RECOMMENDED to use the format `<pipeline>-<variant>` in
-    cases where it is anticipated that the same pipeline will output more than one variant (e.g.,
-    `AFNI-blurring`, `AFNI-noblurring`, etc.). For the sake of consistency, the
-    subfolder name SHOULD be the `GeneratedBy.Name` field in
-    `data_description.json`, optionally followed by a hyphen and a suffix (see
-    [Derived dataset and pipeline description](#derived-dataset-and-pipeline-description).
-
-    Example of derivatives with one directory per pipeline:
-
-    ```Plain
-    <dataset>/derivatives/fmriprep-v1.4.1/sub-0001
-    <dataset>/derivatives/spm/sub-0001
-    <dataset>/derivatives/vbm/sub-0001
-    ```
-
-    Example of a pipeline with split derivative directories:
-
-    ```Plain
-    <dataset>/derivatives/spm-preproc/sub-0001
-    <dataset>/derivatives/spm-stats/sub-0001
-    ```
-
-    Example of a pipeline with nested derivative directories:
-
-    ```Plain
-    <dataset>/derivatives/spm-preproc/sub-0001
-    <dataset>/derivatives/spm-preproc/derivatives/spm-stats/sub-0001
-    ```
-
-
-1.  As a standalone dataset independent of the source (raw or derived) BIDS
-    dataset. This way of specifying derivatives is particularly useful when the
-    source dataset is provided with read-only access, and for publishing
-    derivatives as independent bodies of work, or for describing derivatives
-    that were created from more than one source dataset. The `sourcedata/`
-    subdirectory MAY be used to include the source dataset(s) that were used
-    to generate the derivatives.
-    Likewise, any code used to generate the derivatives from the source data
-    MAY be included in the `code/` subdirectory.
-
-The rest of the Derivatives specification assumes Case 1, but Case 2 applies
-after removing `/derivatives/<pipeline_name>` from template names. In both cases
-every derivatives dataset is considered a BIDS dataset and must include a
-`dataset_description.json` file at the root level. Consequently, files should be
-organized to comply with BIDS to the full extent possible (i.e., unless
-explicitly contradicted below). Any subject-specific derivatives should be
-housed within each subject’s directory; if session-specific derivatives are
-generated, they should be deposited under a session subdirectory within the
-corresponding subject directory; and so on.
-
-## Derived dataset and pipeline description
-
-As for any BIDS dataset a `dataset_description.json` file MUST be found at the
-top level of the particular pipeline:
-`<dataset>/derivatives/<pipeline_name>/dataset_description.json`
-
-In addition to the keys for raw BIDS datasets,
-derived BIDS datasets include the following REQUIRED and RECOMMENDED
-`dataset_description.json` keys:
-
-| **Key name**   | **Description**                                                                                                                                                                    |
-| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| GeneratedBy    | REQUIRED. List of [objects][object] with at least one element.                                                                                                                     |
-| SourceDatasets | RECOMMENDED. A list of [objects][object] specifying the locations and relevant attributes of all source datasets. Valid fields in each object include `URL`, `DOI`, and `Version`. |
-
-Each object in the `GeneratedBy` list includes the following REQUIRED, RECOMMENDED
-and OPTIONAL keys:
-
-| **Key name** | **Description**                                                                                                                                                                                              |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Name         | REQUIRED. Name of the pipeline or process that generated the outputs. Use `"Manual"` to indicate the derivatives were generated by hand, or adjusted manually after an initial run of an automated pipeline. |
-| Version      | RECOMMENDED. Version of the pipeline.                                                                                                                                                                        |
-| Description  | OPTIONAL. Plain-text description of the pipeline or process that generated the outputs. RECOMMENDED if `Name` is `"Manual"`.                                                                                 |
-| CodeURL      | OPTIONAL. URL where the code used to generate the derivatives may be found.                                                                                                                                  |
-| Container    | OPTIONAL. [Object][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`.          |
-
-If a derived dataset is stored as a subfolder of the raw dataset, then the `Name` field
-of the first `GeneratedBy` object MUST be a substring of the derived dataset folder name.
-That is, in a directory `<dataset>/derivatives/<pipeline>[-<variant>]/`, the first
-`GeneratedBy` object should have a `Name` of `<pipeline>`.
-
-Example:
-
-```JSON
-{
-  "Name": "FMRIPREP Outputs",
-  "BIDSVersion": "1.4.0",
-  "GeneratedBy": [
-    {
-      "Name": "FMRIPREP",
-      "Version": "1.2.5",
-      "Container": {
-        "Type": "docker",
-        "Tag": "poldracklab/fmriprep:1.2.5"
-        }
-    },
-    {
-      "Name": "Manual",
-      "Description": "Re-added RepetitionTime metadata to bold.json files"
-    }
-  ],
-  "SourceDatasets": [
-    {
-      "DOI": "10.18112/openneuro.ds000114.v1.0.1",
-      "URL": "https://openneuro.org/datasets/ds000114/versions/1.0.1",
-      "Version": "1.0.1"
-    }
-  ]
-}
-```
-
-## Coordinate systems
-
-The spatial reference (_space_ in the following) to which a particular derivative
-is aligned SHOULD be denoted using the entity `space` whenever the entity
-is present in the filename template of a given derivative type.
-The allowed values for this entity depend are identifiers given in section
-[Image-Based Coordinate Systems][coordsys].
-
-| File format                  | Description             |
-| ---------------------------- | ----------------------- |
-| NIfTI (`.nii` and `.nii.gz`) | Volume data             |
-| GIFTI (`.gii`)               | Surface data            |
-| CIFTI (`.nii`)               | Volume and surface data |
-
-Examples:
-
-```Text
-sub-01/func/sub-01_task-rest_space-MNI305_bold.nii.gz
-sub-01/func/sub-01_task-rest_space-individual_bold.nii.gz
-sub-01/anat/sub-01_hemi-L_space-fsaverage5_thickness.shape.gii
-sub-01/anat/sub-01_hemi-R_space-fsaverage5_thickness.shape.gii
-sub-01/anat/sub-01_hemi-L_space-individual_thickness.shape.gii
-sub-01/anat/sub-01_hemi-R_space-individual_thickness.shape.gii
-sub-01/func/sub-01_task-rest_space-fsLR_bold.dtseries.nii
-```
-
-## Common file level metadata fields
-
-Each derivative file SHOULD be described by a JSON file provided as a sidecar or
-higher up in the hierarchy of the derived dataset (according to
-[The Inheritance Principle](../02-common-principles.md#the-inheritance-principle))
-unless a particular derivative includes REQUIRED metadata fields in which case a
-JSON file is also REQUIRED.
-Each derivative type defines their own set of fields, but all of them
-share the following (non-required) ones:
-
-| **Key name**     | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 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, if a derivative A is used in the creation of another derivative B, which is in turn used to generate C in a chain of A->B->C, C should only list B in `Sources`, and B should only list A in `Sources`. However, in case both X and Y are directly used in the creation of Z, then Z should list X and Y in `Sources`, regardless of whether X was used to generate Y. |
-| 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. 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 JSON object MUST be used.                                                                                                                                                                                           |
-
-### SpatialReference key allowed values
-
-| **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. Paths are written relative to the root of the derivative dataset.               |
-
-In the case of images with multiple references, an [object][] 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
-
-Preprocessed `bold` NIfTI file in `individual` coordinate space. Please mind
-that in this case `SpatialReference` key is REQUIRED.
-
-```Text
-sub-01/func/sub-01_task-rest_space-individual_bold.nii.gz
-sub-01/func/sub-01_task-rest_space-individual_bold.json
-```
-
-```JSON
-{
-    "SpatialReference": "sub-01/anat/sub-01_desc-combined_T1w.nii.gz"
-}
-```
-
-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"
-    }
-}
-```
-
-Preprocessed `bold` NIfTI file in the original coordinate space of the
-original run. Please mind that in this case `RawSources` key is REQUIRED
-(and also `desc-<label>` so that the name does not overlap with the
-original filename).
-
-```Text
-sub-01/func/sub-01_task-rest_desc-preproc_bold.nii.gz
-sub-01/func/sub-01_task-rest_desc-preproc_bold.json
-```
-
-```JSON
-{
-    "RawSources": ["sub-01/func/sub-01_task-rest_bold.nii.gz"]
-}
-```
-
-If this file was generated with prior knowledge from additional sources
-(e.g., say the same subject's `T1w`), then the first item of `RawSources`
-should be the original `bold` file that defined the coordinate system:
-
-```JSON
-{
-    "RawSources": [
-        "sub-01/func/sub-01_task-rest_bold.nii.gz",
-        "sub-01/anat/sub-01_T1w.nii.gz"
-    ]
-}
-```
+The following sections cover additions to and divergences from "raw" BIDS.
+Placement and naming conventions for derived datasets are addressed in
+[Storage of derived datasets][storage], and dataset-level metadata is included
+in [Derived dataset and pipeline description][derived-dataset-description].
 
 ## Metadata conventions
 
@@ -304,18 +69,11 @@ should be the original `bold` file that defined the coordinate system:
     For example, if a summary statistic is derived from a given task, the file
     name SHOULD contain `_task-<label>`.
 
-## Non-compliant datasets
-
-Nothing in this specification should be interpreted to disallow the
-storage/distribution of 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.
 
 []: <> (################)
 []: <> (Link definitions)
 []: <> (################)
 
 [definitions]: ../02-common-principles.md#definitions
-[coordsys]: ../99-appendices/08-coordinate-systems.md#image-based-coordinate-systems
-[object]: https://www.json.org/json-en.html
+[storage]: ../02-common-principles.md#storage-of-derived-datasets
+[derived-dataset-description]: ../03-modality-agnostic-files.md#derived-dataset-and-pipeline-description
diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index d9d89a660a..f78361e7cc 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -1,4 +1,115 @@
-# Common data types
+# Common data types and metadata
+
+## Common file level metadata fields
+
+Each derivative file SHOULD be described by a JSON file provided as a sidecar or
+higher up in the hierarchy of the derived dataset (according to
+[The Inheritance Principle](../02-common-principles.md#the-inheritance-principle))
+unless a particular derivative includes REQUIRED metadata fields, in which case a
+JSON file is also REQUIRED.
+Each derivative type defines their own set of fields, but all of them
+share the following (non-required) ones:
+
+| **Key name** | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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, if a derivative A is used in the creation of another derivative B, which is in turn used to generate C in a chain of A->B->C, C should only list B in `Sources`, and B should only list A in `Sources`. However, in case both X and Y are directly used in the creation of Z, then Z should list X and Y in `Sources`, regardless of whether X was used to generate Y. |
+| 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.                                                                                                                                                                                                    |
+
+### Examples
+
+Preprocessed `bold` NIfTI file in the original coordinate space of the
+original run. Please mind that in this case `RawSources` key is REQUIRED
+(and also `desc-<label>` so that the name does not overlap with the
+original filename).
+
+```Text
+sub-01/func/sub-01_task-rest_desc-preproc_bold.nii.gz
+sub-01/func/sub-01_task-rest_desc-preproc_bold.json
+```
+
+```JSON
+{
+    "RawSources": ["sub-01/func/sub-01_task-rest_bold.nii.gz"]
+}
+```
+
+If this file was generated with prior knowledge from additional sources
+(e.g., say the same subject's `T1w`), then the first item of `RawSources`
+should be the original `bold` file that defined the coordinate system:
+
+```JSON
+{
+    "RawSources": [
+        "sub-01/func/sub-01_task-rest_bold.nii.gz",
+        "sub-01/anat/sub-01_T1w.nii.gz"
+    ]
+}
+```
+
+## Spatial references
+
+Derivatives are often aligned to a common spatial reference to allow for the
+comparison of acquired data across runs, sessions, subjects or datasets.
+A file may indicate the spatial reference to which it has been aligned using the
+`space` entity and/or the `SpatialReference` metadata.
+
+The `space` entity may take any value in [Image-Based Coordinate Systems][coordsys].
+
+If the `space` entity is omitted, or the space is not in the [Standard template
+identifiers][templates] table, then the `SpatialReference` metadata is REQUIRED.
+
+| **Key name**     | **Description**                                                                                                                                                                                                                                                                                                          |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| SpatialReference | RECOMMENDED if the derivative is aligned to a standard template listed in [Standard template identifiers][templates]. REQUIRED otherwise. 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 JSON object MUST be used. |
+
+### SpatialReference key allowed values
+
+| **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. Paths are written relative to the root of the derivative dataset.               |
+
+In the case of images with multiple references, an [object][] 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
+
+Preprocessed `bold` NIfTI file in `individual` coordinate space. Please mind
+that in this case `SpatialReference` key is REQUIRED.
+
+```Text
+sub-01/func/sub-01_task-rest_space-individual_bold.nii.gz
+sub-01/func/sub-01_task-rest_space-individual_bold.json
+```
+
+```JSON
+{
+    "SpatialReference": "sub-01/anat/sub-01_desc-combined_T1w.nii.gz"
+}
+```
+
+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"
+    }
+}
+```
 
 ## Preprocessed or cleaned data
 
@@ -11,12 +122,13 @@ Template:
             <source_entities>[_space-<space>][_desc-<label>]_<suffix>.<ext>
 ```
 
-Preprocessing in this context means transformations of data that do not change
-the data type of the input (as expressed by its BIDS `suffix`).
-For instance, a change in the number of dimensions is likely to disrupt the propagation
-of the input's `suffix` and generally, the outcomes of such transformation
+Data is considered to be *preprocessed* or *cleaned* if the data type of the input,
+as expressed by the BIDS `suffix`, is unchanged.
+By contrast, processing steps that change the number of dimensions are likely to disrupt
+the propagation of the input's `suffix` and generally, the outcomes of such transformation
 cannot be considered _preprocessed_ or _cleaned data_.
-Examples:
+
+Examples of preprocessing:
 
  -  Motion-corrected, temporally denoised, and transformed to MNI space BOLD series
  -  Inhomogeneity corrected and skull stripped T1w files
@@ -26,6 +138,7 @@ Examples:
 
 The `space` keyword is recomended to distinguish files with different underlying
 coordinate systems or registered to different reference maps.
+See [Spatial references](#spatial-references) for details.
 The `desc` (description) keyword is a general purpose field with freeform values,
 which SHOULD be used to distinguish between multiple different versions of
 processing for the same input data.
@@ -57,3 +170,11 @@ All REQUIRED metadata fields coming from a derivative file’s source file(s) MU
 be propagated to the JSON description of the derivative unless the processing
 makes them invalid (e.g., if a source 4D image is averaged to create a single
 static volume, a `RepetitionTime` property would no longer be relevant).
+
+[]: <> (################)
+[]: <> (Link definitions)
+[]: <> (################)
+
+[coordsys]: ../99-appendices/08-coordinate-systems.md#image-based-coordinate-systems
+[templates]: ../99-appendices/08-coordinate-systems.md#standard-template-identifiers
+[object]: https://www.json.org/json-en.html

From bbd0df111f2c6cd5dc155aef0c0336de343d9e1f Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Sat, 30 May 2020 13:51:35 -0400
Subject: [PATCH 169/191] STY: Clean up links, formatting, outdated text

---
 src/02-common-principles.md                | 19 ++++++++++++-------
 src/05-derivatives/01-introduction.md      |  1 -
 src/05-derivatives/02-common-data-types.md |  2 +-
 3 files changed, 13 insertions(+), 9 deletions(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index 1be949892f..6e27520352 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -127,8 +127,9 @@ will be saved.
 Derivatives of the raw data (other than products of DICOM to NIfTI conversion)
 MUST be kept separate from the raw data. This way one can protect the raw data
 from accidental changes by file permissions. In addition it is easy to
-distinguish partial results from the raw data and share the latter. You can read
-more about organizing derivatives [here](05-derivatives/01-introduction.md).
+distinguish partial results from the raw data and share the latter.
+See [Storage of derived datasets](#storage-of-derived-datasets) for more on
+organizing derivatives.
 
 Similar rules apply to source data, which is defined as data before
 harmonization, reconstruction, and/or file format conversion (for example E-Prime event logs or
@@ -199,7 +200,7 @@ Derivatives can be stored/distributed in two ways:
     `AFNI-blurring`, `AFNI-noblurring`, etc.). For the sake of consistency, the
     subfolder name SHOULD be the `GeneratedBy.Name` field in
     `data_description.json`, optionally followed by a hyphen and a suffix (see
-    [Derived dataset and pipeline description](#derived-dataset-and-pipeline-description).
+    [Derived dataset and pipeline description][derived-dataset-description].
 
     Example of derivatives with one directory per pipeline:
 
@@ -261,16 +262,13 @@ then Case 1 will be assumed for clarity in templates and examples, but removing
 Case 2.
 In both cases, every derivatives dataset is considered a BIDS dataset and must
 include a `dataset_description.json` file at the root level (see
-[Dataset description](03-modality-agnostic-files.md#dataset-description).
+[Dataset description][dataset-description].
 Consequently, files should be organized to comply with BIDS to the full extent
 possible (that is, unless explicitly contradicted for derivatives).
 Any subject-specific derivatives should be housed within each subject’s directory;
 if session-specific derivatives are generated, they should be deposited under a
 session subdirectory within the corresponding subject directory; and so on.
 
-See [Derived dataset and pipeline description](05-derivatives/01-introduction.md#derived-dataset-and-pipeline-description)
-for more information.
-
 ### Non-compliant deriatives
 
 Nothing in this specification should be interpreted to disallow the
@@ -611,3 +609,10 @@ meaning of file names and setting requirements on their contents or metadata.
 Validation and parsing tools MAY treat the presence of non-standard files and
 directories as an error, so consult the details of these tools for mechanisms
 to suppress warnings or provide interpretations of your file names.
+
+[]: <> (################)
+[]: <> (Link definitions)
+[]: <> (################)
+
+[dataset-description]: 03-modality-agnostic-files.md#dataset-description
+[derived-dataset-description]: 03-modality-agnostic-files.md#derived-dataset-and-pipeline-description
diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index becf2e33ac..9615fe814a 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -69,7 +69,6 @@ in [Derived dataset and pipeline description][derived-dataset-description].
     For example, if a summary statistic is derived from a given task, the file
     name SHOULD contain `_task-<label>`.
 
-
 []: <> (################)
 []: <> (Link definitions)
 []: <> (################)
diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index f78361e7cc..0de4d687bd 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -126,7 +126,7 @@ Data is considered to be *preprocessed* or *cleaned* if the data type of the inp
 as expressed by the BIDS `suffix`, is unchanged.
 By contrast, processing steps that change the number of dimensions are likely to disrupt
 the propagation of the input's `suffix` and generally, the outcomes of such transformation
-cannot be considered _preprocessed_ or _cleaned data_.
+cannot be considered preprocessed or cleaned data.
 
 Examples of preprocessing:
 

From 6817af9f0f7b0b8d1d6f9269a47094ba3dd7975f Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Sat, 30 May 2020 13:56:40 -0400
Subject: [PATCH 170/191] Fix link

---
 src/99-appendices/08-coordinate-systems.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/99-appendices/08-coordinate-systems.md b/src/99-appendices/08-coordinate-systems.md
index 2d83be2a53..09ff2e1cfa 100644
--- a/src/99-appendices/08-coordinate-systems.md
+++ b/src/99-appendices/08-coordinate-systems.md
@@ -166,6 +166,8 @@ Please note that `space-scanner` SHOULD NOT be used, it is mentioned in this spe
 | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | scanner           | The intrinsic coordinate system of the original image (the first entry of `RawSources`) after reconstruction and conversion to NIfTI or equivalent for the case of surfaces and dual volume/surface files.                                                            |
 
----
+[]: <> (################)
+[]: <> (Link definitions)
+[]: <> (################)
 
-[common file level metadata fields]: ../05-derivatives/01-introduction.md#common-file-level-metadata-fields
+[common file level metadata fields]: ../05-derivatives/02-common-data-types.md#common-file-level-metadata-fields

From 1f1b46d5767c3a9e285241a84a3f30dde700791e Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Sat, 30 May 2020 14:04:45 -0400
Subject: [PATCH 171/191] Update TOC

---
 mkdocs.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/mkdocs.yml b/mkdocs.yml
index 14ab58c11b..3af074092d 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -34,8 +34,8 @@ nav:
         - Behavioral experiments (with no MRI): 04-modality-specific-files/07-behavioral-experiments.md
         - Genetic Descriptor: 04-modality-specific-files/08-genetic-descriptor.md
       - Derivatives:
-        - Introduction: 05-derivatives/01-introduction.md
-        - Common data types: 05-derivatives/02-common-data-types.md
+        - BIDS Derivatives: 05-derivatives/01-introduction.md
+        - Common data types and metadata: 05-derivatives/02-common-data-types.md
         - Imaging data types: 05-derivatives/03-imaging.md
       - Longitudinal and multi-site studies: 06-longitudinal-and-multi-site-studies.md
       - BIDS Extension Proposals: 07-extensions.md

From fa78c9498233d7e1c6553d5e576561c135bf7907 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Mon, 1 Jun 2020 14:11:02 -0400
Subject: [PATCH 172/191] Make dataset description example consistent with
 folder name example

---
 src/03-modality-agnostic-files.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/03-modality-agnostic-files.md b/src/03-modality-agnostic-files.md
index 8c5e82f5f8..61283a2600 100644
--- a/src/03-modality-agnostic-files.md
+++ b/src/03-modality-agnostic-files.md
@@ -88,11 +88,11 @@ Example:
   "BIDSVersion": "1.4.0",
   "GeneratedBy": [
     {
-      "Name": "FMRIPREP",
-      "Version": "1.2.5",
+      "Name": "fmriprep",
+      "Version": "1.4.1",
       "Container": {
         "Type": "docker",
-        "Tag": "poldracklab/fmriprep:1.2.5"
+        "Tag": "poldracklab/fmriprep:1.4.1"
         }
     },
     {

From ded6875faf05bdc90388b65ac7d04749871c3d5f Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Mon, 1 Jun 2020 14:11:52 -0400
Subject: [PATCH 173/191] Remove RawSources overlap with SpatialReference, some
 additional clarifying wording

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

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index 0de4d687bd..67784b6fd1 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -2,26 +2,25 @@
 
 ## Common file level metadata fields
 
-Each derivative file SHOULD be described by a JSON file provided as a sidecar or
-higher up in the hierarchy of the derived dataset (according to
-[The Inheritance Principle](../02-common-principles.md#the-inheritance-principle))
+Each derivative data file SHOULD be described by a JSON file provided as a sidecar
+or higher up in the hierarchy of the derived dataset (according to the
+[Inheritance Principle](../02-common-principles.md#the-inheritance-principle))
 unless a particular derivative includes REQUIRED metadata fields, in which case a
 JSON file is also REQUIRED.
 Each derivative type defines their own set of fields, but all of them
 share the following (non-required) ones:
 
-| **Key name** | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 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, if a derivative A is used in the creation of another derivative B, which is in turn used to generate C in a chain of A->B->C, C should only list B in `Sources`, and B should only list A in `Sources`. However, in case both X and Y are directly used in the creation of Z, then Z should list X and Y in `Sources`, regardless of whether X was used to generate Y. |
-| 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.                                                                                                                                                                                                    |
+| **Key name** | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Description  | RECOMMENDED. Free-form natural language description of the nature of the file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| Sources      | OPTIONAL. A list of files with the paths specified relative to dataset root; these files were directly used in the creation of this derivative data file. For example, if a derivative A is used in the creation of another derivative B, which is in turn used to generate C in a chain of A->B->C, C should only list B in `Sources`, and B should only list A in `Sources`. However, in case both X and Y are directly used in the creation of Z, then Z should list X and Y in `Sources`, regardless of whether X was used to generate Y. |
+| 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.                                                                                                                                                                                                                                                                                                                                                                                                        |
 
 ### Examples
 
-Preprocessed `bold` NIfTI file in the original coordinate space of the
-original run. Please mind that in this case `RawSources` key is REQUIRED
-(and also `desc-<label>` so that the name does not overlap with the
-original filename).
+Preprocessed `bold` NIfTI file in the original coordinate space of the original run.
+The location of the file in the original datasets is encoded in the `RawSources`
+metadata, and `desc-<label>` is used to prevent clashing with the original file name.
 
 ```Text
 sub-01/func/sub-01_task-rest_desc-preproc_bold.nii.gz
@@ -34,8 +33,8 @@ sub-01/func/sub-01_task-rest_desc-preproc_bold.json
 }
 ```
 
-If this file was generated with prior knowledge from additional sources
-(e.g., say the same subject's `T1w`), then the first item of `RawSources`
+If this file was generated with prior knowledge from additional sources, such as
+the same subject's `T1w`, then both files MAY be included in `RawSources`.
 should be the original `bold` file that defined the coordinate system:
 
 ```JSON
@@ -47,6 +46,20 @@ should be the original `bold` file that defined the coordinate system:
 }
 ```
 
+On the other hand, if a preprocessed version of the T1w image was used, and it also
+occurs in the derivatives, `Sources` and `RawSources` can both be specified:
+
+```JSON
+{
+    "Sources": [
+        "sub-01/anat/sub-01_desc-preproc_T1w.nii.gz"
+    ],
+    "RawSources": [
+        "sub-01/func/sub-01_task-rest_bold.nii.gz"
+    ]
+}
+```
+
 ## Spatial references
 
 Derivatives are often aligned to a common spatial reference to allow for the

From 5af5c1e9b553a69f2d1bbe545d6e254f275849c2 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Sat, 30 May 2020 16:09:23 -0400
Subject: [PATCH 174/191] ENH: Change single ROI binary image suffix from dseg
 to mask

---
 src/05-derivatives/03-imaging.md | 41 ++++++++++++++++++++++----------
 1 file changed, 29 insertions(+), 12 deletions(-)

diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index c95679df32..b967979202 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -122,9 +122,8 @@ Template:
             <source_entities>[_space-<space>][_res-<label>][_den-<label>][_desc-<label>]_mask.nii.gz
 ```
 
-A binary (1 - inside, 0 - outside) mask in the space defined by `<space>`. By
-default (i.e., if no transformation has taken place) the value of `space` should
-be set to `orig`.
+A binary (1 - inside, 0 - outside) mask in the space defined by `<space>`.
+If no transformation has taken place, the value of `space` SHOULD be set to `orig`.
 
 JSON metadata fields:
 
@@ -132,6 +131,7 @@ JSON metadata fields:
 | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
 | RawSources   | Same as defined in [Introduction][intro], 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 |
+| Atlas        | OPTIONAL. Which atlas (if any) was used to generate the mask.                                                                                  |
 | Resolution   | REQUIRED if `res` is present. String, or [object][] mapping labels to strings. Specifies the interpretation of the resolution keyword.         |
 | Density      | REQUIRED if `den` is present. String, or [object][] mapping labels to strings. Specifies the interpretation of the density keyword.            |
 
@@ -153,9 +153,24 @@ manual_masks/
             sub-001_desc-tumor_mask.json
 ```
 
-## Segmentations and parcellations
+## Segmentations
 
-Common JSON metadata fields:
+A *segmentation* is a labeling of a spatial image with anatomical structures
+such that each voxel is identified with a label or a combination of labels.
+A *discrete segmentation* represents each tissue class with a unique integer
+label.
+A *probabilistic segmentation* represents each tissue class as values between
+0 and 1 (inclusive) at each location in the image, and one volume/frame per
+tissue class are concatenated in a single file.
+
+Segmentations may be defined in a volume (labeled voxels), a surface (labeled
+vertices) or a combined volume/surface space.
+
+The following section describes discrete and probabilistic segmentations of
+volumes, followed by discrete segmentations of surface/combined spaces.
+Probabilistic segmentations of surfaces are currently [unspecified][].
+
+The following metadata fields apply to all segmentation files:
 
 | **Key name** | **Description**                                                                                                                        |
 | ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
@@ -189,24 +204,25 @@ pipeline/
             sub-001_space-orig_dseg.json
 ```
 
-A segmentation could be a binary mask that functions as a discrete `label` for a
-single structure. In this case, the label key must be used to specify the
-corresponding structure. For example:
+A segmentation can be used to generate a binary mask that functions as a
+discrete "label" for a single structure.
+In this case, the mask suffix MUST be used, and the `desc` entity SHOULD be used
+to specify the masked structure (see [Anatomical labels](#anatomical-labels), and
+the `Atlas` metadata SHOULD be defined.
+For example:
 
 ```Text
 pipeline/
     sub-001/
         anat/
-            sub-001_space-orig_label-GM_dseg.nii.gz
+            sub-001_space-orig_desc-GM_mask.nii.gz
 ```
 
-See [Anatomical Labels](#anatomical-labels) for reserved key values for `label`.
-
 ### Probabilistic Segmentations
 
 Probabilistic segmentations of brain tissue represent a single tissue class with
 values ranging from 0 to 1 in individual 3D volumes or across multiple frames.
-Similarly to a discrete, binary segmentation, the label key can be used to
+If a single tissue class is included the `label` entity SHOULD be used to
 specify the corresponding structure.
 
 Template:
@@ -366,3 +382,4 @@ index   name            abbreviation    color       mapping
 [intro]: 01-introduction.md
 [common_preproc]: 02-common-data-types.md#preprocessed-or-cleaned-data
 [object]: https://www.json.org/json-en.html
+[unspecified]: ../02-common-principles.md#unspecified-data

From 9f1d3a0a9b977add604fd6e604c0e41dab27909b Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Sat, 30 May 2020 17:12:25 -0400
Subject: [PATCH 175/191] Improve wording

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

diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index b967979202..fcbfdc707a 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -270,7 +270,8 @@ for each volume:
 }
 ```
 
-Values of `label` need to map to Abbreviations defined in [Anatomical Labels](#anatomical-labels).
+Values of `label` SHOULD correspond to abbreviations defined in
+[Anatomical Labels](#anatomical-labels).
 
 ### Surface Parcellations
 

From 4225839aa6dba6e961c2a19756cfc71ef76e1fc4 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Sat, 30 May 2020 17:12:59 -0400
Subject: [PATCH 176/191] Clarify discrete surface segmentations

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

diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index fcbfdc707a..75f424c390 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -273,10 +273,12 @@ for each volume:
 Values of `label` SHOULD correspond to abbreviations defined in
 [Anatomical Labels](#anatomical-labels).
 
-### Surface Parcellations
+### Discrete surface segmentations
 
-Discrete parcellations (surface segmentations) of cortical structures should be
-stored as GIFTI or CIFTI file.
+Discrete surface segmentations (sometimes called *parcellations*) of cortical
+structures MUST be stored as GIFTI label files, with extension `.label.gii`.
+For combined volume/surface spaces, discrete segmentations MUST be stored as
+CIFTI-2 dense label fles, with extension `.dlabel.nii`.
 
 Template:
 
@@ -287,8 +289,7 @@ Template:
             <source_entities>[_hemi-{L|R}][_space-<space>][_res-<label>][_den-<label>]_dseg.{label.gii|dlabel.nii}
 ```
 
-The REQUIRED extension for GIFTI parcellations is `.label.gii`. The `hemi` tag is
-REQUIRED for GIFTI files. For example:
+The `hemi` tag is REQUIRED for GIFTI files. For example:
 
 ```Text
 pipeline/

From 82fab3d2ca1f25abd840e85b7e8b841ae0497464 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Sat, 30 May 2020 17:13:31 -0400
Subject: [PATCH 177/191] Swap mapping/color and add an example dseg with new
 labels

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

diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index 75f424c390..7cd9291def 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -365,10 +365,10 @@ These TSV lookup tables contain the following columns:
 | index        | REQUIRED. The label integer index                                       |
 | name         | REQUIRED. The unique label name                                         |
 | abbreviation | OPTIONAL. The unique label abbreviation                                 |
-| mapping      | OPTIONAL. Corresponding integer label in the standard BIDS label lookup |
 | color        | OPTIONAL. Hexadecimal. Label color for visualization                    |
+| mapping      | OPTIONAL. Corresponding integer label in the standard BIDS label lookup |
 
-An example, custom dseg.tsv that defines three labels:
+An example, custom `dseg.tsv` that defines three labels:
 
 ```Text
 index   name            abbreviation    color       mapping
@@ -377,6 +377,16 @@ index   name            abbreviation    color       mapping
 102     Brainstem       BS              #36de72     11
 ```
 
+The following example `dseg.tsv` defines regions that are not part of the
+standard BIDS labels:
+
+```Text
+index   name                abbreviation
+137     pars opercularis    IFGop
+138     pars triangularis   IFGtr
+139     pars orbitalis      IFGor
+```
+
 []: <> (################)
 []: <> (Link definitions)
 []: <> (################)

From 18d462d14a9c8b8b5da86041611aadabdf1f09fa Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Sun, 31 May 2020 16:46:36 -0400
Subject: [PATCH 178/191] Replace "tissue class" with more general "anatomical
 structure"

---
 src/05-derivatives/03-imaging.md | 27 +++++++++++++++------------
 1 file changed, 15 insertions(+), 12 deletions(-)

diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index 7cd9291def..c9cd9a4c74 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -156,12 +156,13 @@ manual_masks/
 ## Segmentations
 
 A *segmentation* is a labeling of a spatial image with anatomical structures
-such that each voxel is identified with a label or a combination of labels.
-A *discrete segmentation* represents each tissue class with a unique integer
+such that each location (for example, a voxel or a surface vertex) is identified
+with a label or a combination of labels.
+A *discrete segmentation* represents each structure with a unique integer
 label.
-A *probabilistic segmentation* represents each tissue class as values between
+A *probabilistic segmentation* represents each structure as values between
 0 and 1 (inclusive) at each location in the image, and one volume/frame per
-tissue class are concatenated in a single file.
+structure may be concatenated in a single file.
 
 Segmentations may be defined in a volume (labeled voxels), a surface (labeled
 vertices) or a combined volume/surface space.
@@ -181,9 +182,10 @@ The following metadata fields apply to all segmentation files:
 
 ### Discrete Segmentations
 
-Discrete segmentations of brain tissue represent each tissue class with a unique
-integer label in a 3D volume. See [Anatomical Labels](#anatomical-labels) for interpretation how
-integer values map to tissue classes.
+Discrete segmentations of brain tissue represent multiple anatomical structures
+(such as tissue class or Brodmann area) with a unique integer label in a 3D volume.
+See [Anatomical Labels](#anatomical-labels) for interpretation how integer values
+map to anatomical structures.
 
 Template:
 
@@ -215,15 +217,16 @@ For example:
 pipeline/
     sub-001/
         anat/
-            sub-001_space-orig_desc-GM_mask.nii.gz
+            sub-001_space-orig_label-GM_mask.nii.gz
 ```
 
 ### Probabilistic Segmentations
 
-Probabilistic segmentations of brain tissue represent a single tissue class with
-values ranging from 0 to 1 in individual 3D volumes or across multiple frames.
-If a single tissue class is included the `label` entity SHOULD be used to
-specify the corresponding structure.
+Probabilistic segmentations of brain tissue represent a single anatomical
+structure with values ranging from 0 to 1 in individual 3D volumes or across
+multiple frames.
+If a single structure is included the `label` entity SHOULD be used to specify
+the structure.
 
 Template:
 

From e0508a79557c5c9eb40659b34b8611c6f3c70be7 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Sun, 31 May 2020 16:46:48 -0400
Subject: [PATCH 179/191] Add labels for masks

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

diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index c9cd9a4c74..04f059e9d2 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -119,11 +119,14 @@ Template:
 <pipeline_name>/
     sub-<participant_label>/
         anat|func|dwi/
-            <source_entities>[_space-<space>][_res-<label>][_den-<label>][_desc-<label>]_mask.nii.gz
+            <source_entities>[_space-<space>][_res-<label>][_den-<label>][_label-<label>][_desc-<label>]_mask.nii.gz
 ```
 
 A binary (1 - inside, 0 - outside) mask in the space defined by `<space>`.
 If no transformation has taken place, the value of `space` SHOULD be set to `orig`.
+If the mask is an ROI mask derived from an atlas, then the `label` entity SHOULD
+be used to specify the masked structure (see [Anatomical labels](#anatomical-labels),
+and the `Atlas` metadata SHOULD be defined.
 
 JSON metadata fields:
 
@@ -131,7 +134,7 @@ JSON metadata fields:
 | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
 | RawSources   | Same as defined in [Introduction][intro], 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 |
-| Atlas        | OPTIONAL. Which atlas (if any) was used to generate the mask.                                                                                  |
+| Atlas        | OPTIONAL. Which atlas (if any) was used to generate the mask. RECOMMENDED if `label` entity is defined.                                        |
 | Resolution   | REQUIRED if `res` is present. String, or [object][] mapping labels to strings. Specifies the interpretation of the resolution keyword.         |
 | Density      | REQUIRED if `den` is present. String, or [object][] mapping labels to strings. Specifies the interpretation of the density keyword.            |
 
@@ -208,7 +211,7 @@ pipeline/
 
 A segmentation can be used to generate a binary mask that functions as a
 discrete "label" for a single structure.
-In this case, the mask suffix MUST be used, and the `desc` entity SHOULD be used
+In this case, the mask suffix MUST be used, and the `label` entity SHOULD be used
 to specify the masked structure (see [Anatomical labels](#anatomical-labels), and
 the `Atlas` metadata SHOULD be defined.
 For example:

From b1d64ff4bf9df1773524da048f395ff28befb812 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Mon, 1 Jun 2020 14:13:48 -0400
Subject: [PATCH 180/191] Update src/05-derivatives/03-imaging.md

Co-authored-by: Robert Smith <robert.smith@florey.edu.au>
---
 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 04f059e9d2..397b43ca69 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -333,7 +333,7 @@ below, that contains common image-derived segmentations and can be used to map s
 | 7             | Non-brain               | NB                   |
 | 8             | Lesion                  | L                    |
 | 9             | Cortical Gray Matter    | CGM                  |
-| 10            | Subcortical Gray Matter | SCGM                 |
+| 10            | Subcortical Gray Matter | SGM                  |
 | 11            | Brainstem               | BS                   |
 | 12            | Cerebellum              | CBM                  |
 

From 20b22698c6886054bca4be790ae791e174eec1f9 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Mon, 1 Jun 2020 14:28:01 -0400
Subject: [PATCH 181/191] Fix section links, capitalization

---
 src/05-derivatives/03-imaging.md | 19 +++++++++++--------
 1 file changed, 11 insertions(+), 8 deletions(-)

diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index 397b43ca69..ea5315c148 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -125,7 +125,8 @@ Template:
 A binary (1 - inside, 0 - outside) mask in the space defined by `<space>`.
 If no transformation has taken place, the value of `space` SHOULD be set to `orig`.
 If the mask is an ROI mask derived from an atlas, then the `label` entity SHOULD
-be used to specify the masked structure (see [Anatomical labels](#anatomical-labels),
+be used to specify the masked structure
+(see [Common image-derived labels](#common-image-derived-labels)),
 and the `Atlas` metadata SHOULD be defined.
 
 JSON metadata fields:
@@ -187,8 +188,8 @@ The following metadata fields apply to all segmentation files:
 
 Discrete segmentations of brain tissue represent multiple anatomical structures
 (such as tissue class or Brodmann area) with a unique integer label in a 3D volume.
-See [Anatomical Labels](#anatomical-labels) for interpretation how integer values
-map to anatomical structures.
+See [Common image-derived labels](#common-image-derived-labels) for interpretation
+how integer values map to anatomical structures.
 
 Template:
 
@@ -212,8 +213,9 @@ pipeline/
 A segmentation can be used to generate a binary mask that functions as a
 discrete "label" for a single structure.
 In this case, the mask suffix MUST be used, and the `label` entity SHOULD be used
-to specify the masked structure (see [Anatomical labels](#anatomical-labels), and
-the `Atlas` metadata SHOULD be defined.
+to specify the masked structure
+(see [Common image-derived labels](#common-image-derived-labels)),
+and the `Atlas` metadata SHOULD be defined.
 For example:
 
 ```Text
@@ -250,7 +252,8 @@ pipeline/
             sub-001_space-orig_label-WM_probseg.nii.gz
 ```
 
-See [Anatomical labels](#anatomical-labels) for reserved key values for `label`.
+See [Common image-derived labels](#common-image-derived-labels)
+for reserved key values for `label`.
 
 A 4D probabilistic segmentation, in which each frame corresponds to a different
 tissue class, must provide a label mapping in its JSON sidecar. For example:
@@ -277,7 +280,7 @@ for each volume:
 ```
 
 Values of `label` SHOULD correspond to abbreviations defined in
-[Anatomical Labels](#anatomical-labels).
+[Common image-derived labels](#common-image-derived-labels).
 
 ### Discrete surface segmentations
 
@@ -315,7 +318,7 @@ pipeline/
             sub-001_dseg.dlabel.nii
 ```
 
-### Common Image-derived Labels
+### Common image-derived labels
 
 BIDS supplies a standard, generic label-index mapping, defined in the table
 below, that contains common image-derived segmentations and can be used to map segmentations

From 5dd98d237be35087d10598907ea160051dfb731f Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Mon, 1 Jun 2020 16:25:55 -0400
Subject: [PATCH 182/191] Drop "Gray and White Matter" label

---
 src/05-derivatives/03-imaging.md | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index ea5315c148..92ae8c6e2a 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -330,15 +330,14 @@ below, that contains common image-derived segmentations and can be used to map s
 | 1             | Gray Matter             | GM                   |
 | 2             | White Matter            | WM                   |
 | 3             | Cerebrospinal Fluid     | CSF                  |
-| 4             | Gray and White Matter   | GWM                  |
-| 5             | Bone                    | B                    |
-| 6             | Soft Tissue             | ST                   |
-| 7             | Non-brain               | NB                   |
-| 8             | Lesion                  | L                    |
-| 9             | Cortical Gray Matter    | CGM                  |
-| 10            | Subcortical Gray Matter | SGM                  |
-| 11            | Brainstem               | BS                   |
-| 12            | Cerebellum              | CBM                  |
+| 4             | Bone                    | B                    |
+| 5             | Soft Tissue             | ST                   |
+| 6             | Non-brain               | NB                   |
+| 7             | Lesion                  | L                    |
+| 8             | Cortical Gray Matter    | CGM                  |
+| 9             | Subcortical Gray Matter | SGM                  |
+| 10            | Brainstem               | BS                   |
+| 11            | Cerebellum              | CBM                  |
 
 These definitions can be overridden (or added to) by providing custom labels in
 a sidecar `<matches>.tsv` file, in which `<matches>` corresponds to segmentation

From f43c0d4397fb31e14b81c0293b77068ebce89dc4 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Mon, 1 Jun 2020 18:17:22 -0400
Subject: [PATCH 183/191] Drop extraneous line, make punctuation consistent

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

diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index 67784b6fd1..bc93b43231 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -35,7 +35,6 @@ sub-01/func/sub-01_task-rest_desc-preproc_bold.json
 
 If this file was generated with prior knowledge from additional sources, such as
 the same subject's `T1w`, then both files MAY be included in `RawSources`.
-should be the original `bold` file that defined the coordinate system:
 
 ```JSON
 {
@@ -47,7 +46,7 @@ should be the original `bold` file that defined the coordinate system:
 ```
 
 On the other hand, if a preprocessed version of the T1w image was used, and it also
-occurs in the derivatives, `Sources` and `RawSources` can both be specified:
+occurs in the derivatives, `Sources` and `RawSources` can both be specified.
 
 ```JSON
 {

From 37c2bf2b73173f8b6a9a08e351e4832ce049d2bd Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Tue, 2 Jun 2020 10:46:23 -0400
Subject: [PATCH 184/191] Missing paren

---
 src/02-common-principles.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index 6e27520352..6bbe1ccaaf 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -200,7 +200,7 @@ Derivatives can be stored/distributed in two ways:
     `AFNI-blurring`, `AFNI-noblurring`, etc.). For the sake of consistency, the
     subfolder name SHOULD be the `GeneratedBy.Name` field in
     `data_description.json`, optionally followed by a hyphen and a suffix (see
-    [Derived dataset and pipeline description][derived-dataset-description].
+    [Derived dataset and pipeline description][derived-dataset-description]).
 
     Example of derivatives with one directory per pipeline:
 

From 02408bf1fed84388d25fc372cd2ec6db2dd9419d Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Wed, 3 Jun 2020 11:46:30 -0400
Subject: [PATCH 185/191] Apply suggestions from code review

Co-authored-by: Sanjula Madurapperuma <32578617+sanjulamadurapperuma@users.noreply.github.com>
---
 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 92ae8c6e2a..baf466e956 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -212,7 +212,7 @@ pipeline/
 
 A segmentation can be used to generate a binary mask that functions as a
 discrete "label" for a single structure.
-In this case, the mask suffix MUST be used, and the `label` entity SHOULD be used
+In this case, the mask suffix MUST be used, the `label` entity SHOULD be used
 to specify the masked structure
 (see [Common image-derived labels](#common-image-derived-labels)),
 and the `Atlas` metadata SHOULD be defined.
@@ -230,7 +230,7 @@ pipeline/
 Probabilistic segmentations of brain tissue represent a single anatomical
 structure with values ranging from 0 to 1 in individual 3D volumes or across
 multiple frames.
-If a single structure is included the `label` entity SHOULD be used to specify
+If a single structure is included, the `label` entity SHOULD be used to specify
 the structure.
 
 Template:
@@ -266,7 +266,7 @@ pipeline/
 		    sub-001_space-orig_probseg.json
 ```
 
-The JSON sidecar must include the label-map key that specifies a tissue label
+The JSON sidecar MUST include the label-map key that specifies a tissue label
 for each volume:
 
 ```JSON
@@ -285,9 +285,9 @@ Values of `label` SHOULD correspond to abbreviations defined in
 ### Discrete surface segmentations
 
 Discrete surface segmentations (sometimes called *parcellations*) of cortical
-structures MUST be stored as GIFTI label files, with extension `.label.gii`.
+structures MUST be stored as GIFTI label files, with the extension `.label.gii`.
 For combined volume/surface spaces, discrete segmentations MUST be stored as
-CIFTI-2 dense label fles, with extension `.dlabel.nii`.
+CIFTI-2 dense label fles, with the extension `.dlabel.nii`.
 
 Template:
 

From f9734a5c15dd2552b402383ed68747fedd944fa5 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Wed, 3 Jun 2020 11:48:15 -0400
Subject: [PATCH 186/191] Apply suggestions from code review

Co-authored-by: Sanjula Madurapperuma <32578617+sanjulamadurapperuma@users.noreply.github.com>
---
 src/02-common-principles.md       | 6 +++---
 src/03-modality-agnostic-files.md | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index 6bbe1ccaaf..496f2f1b45 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -120,7 +120,7 @@ in the appendix.
 
 ## Source vs. raw vs. derived data
 
-BIDS originally was designed to describe and apply consistent naming conventions
+BIDS was originally designed to describe and apply consistent naming conventions
 to raw (unprocessed or minimally processed due to file format conversion) data.
 During analysis such data will be transformed and partial as well as final results
 will be saved.
@@ -132,7 +132,7 @@ See [Storage of derived datasets](#storage-of-derived-datasets) for more on
 organizing derivatives.
 
 Similar rules apply to source data, which is defined as data before
-harmonization, reconstruction, and/or file format conversion (for example E-Prime event logs or
+harmonization, reconstruction, and/or file format conversion (for example, E-Prime event logs or
 DICOM files). This specification currently does not go into details of
 recommending a particular naming scheme for including different types of
 source data (raw event logs, parameter files, etc. before conversion to BIDS).
@@ -146,7 +146,7 @@ However, in the case that these data are to be included:
 1.  A README file SHOULD be found at the root of the `sourcedata` folder or the
     `derivatives` folder, or both.
     This file should describe the nature of the raw data or the derived data.
-    We RECOMMEND including the PDF print-out with  the actual sequence
+    We RECOMMEND including the PDF print-out with the actual sequence
     parameters generated by the scanner in the `sourcedata`  folder.
 
 Alternatively one can organize their data in the following way
diff --git a/src/03-modality-agnostic-files.md b/src/03-modality-agnostic-files.md
index 61283a2600..641ad7ce94 100644
--- a/src/03-modality-agnostic-files.md
+++ b/src/03-modality-agnostic-files.md
@@ -56,7 +56,7 @@ Example:
 
 #### Derived dataset and pipeline description
 
-As for any BIDS dataset a `dataset_description.json` file MUST be found at the
+As for any BIDS dataset, a `dataset_description.json` file MUST be found at the
 top level of the a derived dataset:
 `<dataset>/derivatives/<pipeline_name>/dataset_description.json`
 

From 95c4af7d1909772394240c8998c463a3d2c82ccb Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Wed, 3 Jun 2020 13:53:46 -0400
Subject: [PATCH 187/191] Update src/05-derivatives/03-imaging.md

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

diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index baf466e956..61368fe03d 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -188,8 +188,8 @@ The following metadata fields apply to all segmentation files:
 
 Discrete segmentations of brain tissue represent multiple anatomical structures
 (such as tissue class or Brodmann area) with a unique integer label in a 3D volume.
-See [Common image-derived labels](#common-image-derived-labels) for interpretation
-how integer values map to anatomical structures.
+See [Common image-derived labels](#common-image-derived-labels) for a description
+of how integer values map to anatomical structures.
 
 Template:
 

From 131160cb93b2decb58372082ca3514ecf0e787ce Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Thu, 4 Jun 2020 08:22:00 -0400
Subject: [PATCH 188/191] Update src/05-derivatives/03-imaging.md

---
 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 61368fe03d..4021f520ce 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -287,7 +287,7 @@ Values of `label` SHOULD correspond to abbreviations defined in
 Discrete surface segmentations (sometimes called *parcellations*) of cortical
 structures MUST be stored as GIFTI label files, with the extension `.label.gii`.
 For combined volume/surface spaces, discrete segmentations MUST be stored as
-CIFTI-2 dense label fles, with the extension `.dlabel.nii`.
+CIFTI-2 dense label files, with the extension `.dlabel.nii`.
 
 Template:
 

From 0aaa881b5cff783b26a3b4cb1f14f2f54ebad0f1 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Thu, 4 Jun 2020 09:16:17 -0400
Subject: [PATCH 189/191] Update src/05-derivatives/03-imaging.md

---
 src/05-derivatives/03-imaging.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index 4021f520ce..e7080a3dca 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -298,7 +298,9 @@ Template:
             <source_entities>[_hemi-{L|R}][_space-<space>][_res-<label>][_den-<label>]_dseg.{label.gii|dlabel.nii}
 ```
 
-The `hemi` tag is REQUIRED for GIFTI files. For example:
+The `hemi` tag is REQUIRED for GIFTI files storing information about
+a structure that is restricted to a hemibrain.
+For example:
 
 ```Text
 pipeline/

From 3096fbe33f628b390e8cc53a1c21f30c3e5238ef Mon Sep 17 00:00:00 2001
From: Satrajit Ghosh <satrajit.ghosh@gmail.com>
Date: Thu, 4 Jun 2020 09:27:13 -0400
Subject: [PATCH 190/191] Update src/05-derivatives/03-imaging.md

Co-authored-by: Chris Markiewicz <markiewicz@stanford.edu>
---
 src/05-derivatives/03-imaging.md | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index e7080a3dca..b8d9d91c1a 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -159,12 +159,16 @@ manual_masks/
 
 ## Segmentations
 
-A *segmentation* is a labeling of a spatial image with anatomical structures
-such that each location (for example, a voxel or a surface vertex) is identified
-with a label or a combination of labels.
-A *discrete segmentation* represents each structure with a unique integer
+A *segmentation* is a labeling of regions of an image such that each location
+(for example, a voxel or a surface vertex) is identified with a label or a
+combination of labels. 
+Labeled regions may include anatomical structures (such as tissue class,
+Brodmann area or white matter tract), discontiguous, functionally-defined
+networks, tumors or lesions.
+
+A *discrete segmentation* represents each region with a unique integer
 label.
-A *probabilistic segmentation* represents each structure as values between
+A *probabilistic segmentation* represents each region as values between
 0 and 1 (inclusive) at each location in the image, and one volume/frame per
 structure may be concatenated in a single file.
 

From 7bfc0e4259e24862b918888cd08bf6fd155caf18 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Thu, 4 Jun 2020 16:04:50 -0400
Subject: [PATCH 191/191] ENH: Add RECOMMENDED DatasetType key to dataset
 description (#494)

---
 src/03-modality-agnostic-files.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/03-modality-agnostic-files.md b/src/03-modality-agnostic-files.md
index 641ad7ce94..4c7084264b 100644
--- a/src/03-modality-agnostic-files.md
+++ b/src/03-modality-agnostic-files.md
@@ -17,6 +17,7 @@ dataset MUST include this file with the following fields:
 | ------------------------------------------------------------------------------| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Name               | REQUIRED. Name of the dataset.                                                                                                                                                                                                       |
 | BIDSVersion        | REQUIRED. The version of the BIDS standard that was used.                                                                                                                                                                            |
+| DatasetType        | RECOMMENDED. The interpretaton of the dataset. MUST be one of `"raw"` or `"derivative"`. For backwards compatibility, the default value is `"raw"`.                                                                                  |
 | License            | RECOMMENDED. What license is this dataset distributed under? The use of license name abbreviations is suggested for specifying a license. A list of common licenses with suggested abbreviations can be found in Appendix II.        |
 | Authors            | OPTIONAL. List of individuals who contributed to the creation/curation of the dataset.                                                                                                                                               |
 | Acknowledgements   | OPTIONAL. Text acknowledging contributions of individuals or institutions beyond those listed in Authors or Funding.                                                                                                                 |
@@ -31,7 +32,8 @@ Example:
 ```JSON
 {
   "Name": "The mother of all experiments",
-  "BIDSVersion": "1.0.1",
+  "BIDSVersion": "1.4.0",
+  "DatasetType": "raw",
   "License": "CC0",
   "Authors": [
     "Paul Broca",
@@ -86,6 +88,7 @@ Example:
 {
   "Name": "FMRIPREP Outputs",
   "BIDSVersion": "1.4.0",
+  "DatasetType": "derivative",
   "GeneratedBy": [
     {
       "Name": "fmriprep",