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 01/10] 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 02/10] 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 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 03/10] 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 04/10] 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 05/10] 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 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 06/10] 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 07/10] 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 08/10] 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 09/10] 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 10/10] 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: